diff --git a/docs/development/icons_guide.md b/docs/development/icons_guide.md new file mode 100644 index 00000000..43936b61 --- /dev/null +++ b/docs/development/icons_guide.md @@ -0,0 +1,424 @@ +# Icon System Guide + +## Overview + +This project uses **Heroicons** (inline SVG) with a custom helper system for clean, maintainable icon usage across the multi-tenant ecommerce platform. + +### Why This Approach? + +- **No External Dependencies**: All icons are inline SVG - no CDN required +- **Performance**: Zero extra HTTP requests +- **Tailwind Integration**: Icons work seamlessly with Tailwind utility classes +- **Clean HTML**: No verbose SVG code cluttering your templates +- **Type Safety**: All available icons are defined in one place + +--- + +## Quick Start + +### 1. Include the Icon Helper + +Add this script **before** Alpine.js in your HTML pages: + +```html + + + + + +``` + +### 2. Use Icons with Alpine Magic Helper + +```html + + + + + + + + +``` + +--- + +## Available Icons + +### Navigation Icons +| Icon Name | Usage | Description | +|-----------|-------|-------------| +| `home` | `$icon('home')` | Dashboard, homepage | +| `menu` | `$icon('menu')` | Mobile menu toggle | +| `search` | `$icon('search')` | Search functionality | +| `arrow-left` | `$icon('arrow-left')` | Back navigation | +| `chevron-down` | `$icon('chevron-down')` | Dropdowns | +| `chevron-right` | `$icon('chevron-right')` | Next/forward | + +### User & Profile Icons +| Icon Name | Usage | Description | +|-----------|-------|-------------| +| `user` | `$icon('user')` | Single user profile | +| `users` | `$icon('users')` | Multiple users, team | +| `user-circle` | `$icon('user-circle')` | User avatar | +| `user-group` | `$icon('user-group')` | Groups, teams | +| `identification` | `$icon('identification')` | ID, credentials | +| `badge-check` | `$icon('badge-check')` | Verified badge | + +### Action Icons +| Icon Name | Usage | Description | +|-----------|-------|-------------| +| `edit` | `$icon('edit')` | Edit action | +| `delete` | `$icon('delete')` | Delete action | +| `plus` | `$icon('plus')` | Add/create action | +| `check` | `$icon('check')` | Success, confirmed | +| `close` | `$icon('close')` | Close, dismiss | +| `refresh` | `$icon('refresh')` | Reload, refresh | +| `duplicate` | `$icon('duplicate')` | Copy, duplicate | +| `eye` | `$icon('eye')` | View, show | +| `eye-off` | `$icon('eye-off')` | Hide | +| `filter` | `$icon('filter')` | Filter options | +| `dots-vertical` | `$icon('dots-vertical')` | More options (vertical) | +| `dots-horizontal` | `$icon('dots-horizontal')` | More options (horizontal) | + +### E-commerce Icons +| Icon Name | Usage | Description | +|-----------|-------|-------------| +| `shopping-bag` | `$icon('shopping-bag')` | Vendors, products | +| `shopping-cart` | `$icon('shopping-cart')` | Cart | +| `credit-card` | `$icon('credit-card')` | Payment | +| `currency-dollar` | `$icon('currency-dollar')` | Money, pricing | +| `gift` | `$icon('gift')` | Promotions, gifts | +| `tag` | `$icon('tag')` | Tags, categories | +| `truck` | `$icon('truck')` | Shipping, delivery | +| `receipt` | `$icon('receipt')` | Orders, receipts | + +### Inventory & Product Icons +| Icon Name | Usage | Description | +|-----------|-------|-------------| +| `cube` | `$icon('cube')` | Products, packages | +| `collection` | `$icon('collection')` | Collections, catalog | +| `photograph` | `$icon('photograph')` | Images, media | +| `color-swatch` | `$icon('color-swatch')` | Variants, colors | +| `template` | `$icon('template')` | Templates, layouts | +| `clipboard-list` | `$icon('clipboard-list')` | Lists, inventory | + +### Analytics & Reports +| Icon Name | Usage | Description | +|-----------|-------|-------------| +| `chart` | `$icon('chart')` | Analytics, stats | +| `trending-up` | `$icon('trending-up')` | Growth, increase | +| `trending-down` | `$icon('trending-down')` | Decline, decrease | +| `presentation-chart-line` | `$icon('presentation-chart-line')` | Reports, presentations | +| `calculator` | `$icon('calculator')` | Calculations, math | + +### Communication Icons +| Icon Name | Usage | Description | +|-----------|-------|-------------| +| `bell` | `$icon('bell')` | Notifications | +| `mail` | `$icon('mail')` | Email, messages | +| `chat` | `$icon('chat')` | Chat, messaging | +| `annotation` | `$icon('annotation')` | Comments, notes | +| `phone` | `$icon('phone')` | Phone, call | + +### System & Settings +| Icon Name | Usage | Description | +|-----------|-------|-------------| +| `cog` | `$icon('cog')` | Settings, configuration | +| `sun` | `$icon('sun')` | Light theme | +| `moon` | `$icon('moon')` | Dark theme | +| `database` | `$icon('database')` | Database, storage | +| `server` | `$icon('server')` | Server, hosting | +| `shield-check` | `$icon('shield-check')` | Security, verified | +| `key` | `$icon('key')` | API keys, passwords | +| `lock-closed` | `$icon('lock-closed')` | Locked, secure | +| `lock-open` | `$icon('lock-open')` | Unlocked | + +### Document & File Icons +| Icon Name | Usage | Description | +|-----------|-------|-------------| +| `document` | `$icon('document')` | Documents, files | +| `folder` | `$icon('folder')` | Folders, directories | +| `folder-open` | `$icon('folder-open')` | Open folder | +| `download` | `$icon('download')` | Download action | +| `upload` | `$icon('upload')` | Upload action | + +### Time & Calendar +| Icon Name | Usage | Description | +|-----------|-------|-------------| +| `calendar` | `$icon('calendar')` | Calendar, dates | +| `clock` | `$icon('clock')` | Time, schedule | + +### Location Icons +| Icon Name | Usage | Description | +|-----------|-------|-------------| +| `location-marker` | `$icon('location-marker')` | Location, address | +| `globe` | `$icon('globe')` | International, language | + +### Status & Indicators +| Icon Name | Usage | Description | +|-----------|-------|-------------| +| `exclamation` | `$icon('exclamation')` | Warning, alert | +| `information-circle` | `$icon('information-circle')` | Information, help | +| `spinner` | `$icon('spinner')` | Loading state | +| `star` | `$icon('star')` | Favorites, ratings | +| `heart` | `$icon('heart')` | Likes, favorites | +| `flag` | `$icon('flag')` | Reports, flags | + +### Links & External +| Icon Name | Usage | Description | +|-----------|-------|-------------| +| `external-link` | `$icon('external-link')` | Open in new tab | +| `link` | `$icon('link')` | URL, hyperlink | +| `logout` | `$icon('logout')` | Sign out | + +--- + +## Common Usage Patterns + +### Buttons with Icons + +```html + + + + + + + + +``` + +### Status Indicators + +```html + +
+ + Verified +
+ + +
+ + Pending Review +
+ + +
+ + Processing... +
+``` + +### Navigation Items + +```html + + +``` + +### Form Fields + +```html + +
+
+ +
+ +
+ + +
+ + +
+``` + +### Cards & Panels + +```html + +
+
+
+

Total Sales

+

$12,345

+
+
+ +
+
+
+``` + +### Dropdown Menus + +```html +
+ + +
+ + + Edit + + + + Duplicate + + + + Delete + +
+
+``` + +--- + +## Size Guidelines + +| Class | Size | Use Case | +|-------|------|----------| +| `w-3 h-3` | 12px | Inline text icons | +| `w-4 h-4` | 16px | Small buttons, badges | +| `w-5 h-5` | 20px | Default size, most UI elements | +| `w-6 h-6` | 24px | Larger buttons, headers | +| `w-8 h-8` | 32px | Featured icons, empty states | +| `w-12 h-12` | 48px | Large feature displays | + +--- + +## Color Patterns + +```html + + + + + + + + + + + + + +``` + +--- + +## Best Practices + +### ✅ Do + +- Use consistent icon sizes within the same context +- Match icon color with text color for visual harmony +- Use semantic colors for status indicators +- Include descriptive text for accessibility +- Use the `$icon()` helper for cleaner templates + +### ❌ Don't + +- Mix icon styles (outline vs solid) inconsistently +- Use icons without considering their meaning +- Make icons too small to recognize (< 16px) +- Rely solely on icons without text labels for important actions +- Use decorative icons excessively + +--- + +## Adding New Icons + +To add a new icon to the system: + +1. Find the icon in [Heroicons](https://heroicons.com/) +2. Copy the SVG path data +3. Add to the `Icons` object in `icons.js`: + +```javascript +'new-icon-name': ` + +` +``` + +4. Update this guide with the new icon + +--- + +## Browser Support + +The icon system works in all modern browsers: +- Chrome/Edge (latest) +- Firefox (latest) +- Safari (latest) +- Mobile browsers (iOS Safari, Chrome Mobile) + +--- + +## Performance Notes + +- Icons are inline SVG - no additional HTTP requests +- Total icon library size: ~15KB uncompressed +- Minimal impact on page load time +- Icons render instantly with the page + +--- + +## Troubleshooting + +**Icon not displaying?** +- Check that `icons.js` is loaded before Alpine.js +- Verify the icon name exists in the Icons object +- Check browser console for warnings + +**Icon wrong size?** +- Ensure you're passing valid Tailwind size classes +- Use both width and height (e.g., `w-5 h-5`) + +**Icon wrong color?** +- Add text color class (e.g., `text-gray-600`) +- Check parent element's color inheritance + +--- + +## Related Resources + +- [Heroicons Official Site](https://heroicons.com/) +- [Tailwind CSS Documentation](https://tailwindcss.com/docs) +- [Alpine.js Magic Properties](https://alpinejs.dev/magics/el) \ No newline at end of file