orion/docs/development/icons-guide.md

Icon System Guide

Overview

This project uses Heroicons (inline SVG) with a custom helper system for clean, maintainable icon usage across all 4 frontends:

• Platform - Public platform pages
• Admin - Administrative portal
• Store - Store management portal
• Shop - Customer-facing store

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:

<!-- Load icon helper -->
<script src="/static/shared/js/icons.js"></script>

<!-- Alpine.js v3 -->
<script defer src="https://cdn.jsdelivr.net/npm/alpinejs@3.14.0/dist/cdn.min.js"></script>

2. Use Icons with Alpine Magic Helper

<!-- Default size (w-5 h-5) -->
<span x-html="$icon('home')"></span>

<!-- Custom size and color -->
<span x-html="$icon('home', 'w-6 h-6 text-purple-600')"></span>

<!-- In buttons -->
<button>
    <span x-html="$icon('plus', 'w-4 h-4 mr-2')"></span>
    Create Store
</button>

---

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')	Stores, 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

<!-- Primary action button -->
<button class="btn-primary">
    <span x-html="$icon('plus', 'w-4 h-4 mr-2')"></span>
    Create Product
</button>

<!-- Icon-only button -->
<button class="p-2 hover:bg-gray-100 rounded">
    <span x-html="$icon('edit', 'w-5 h-5 text-gray-600')"></span>
</button>

<!-- Danger button -->
<button class="btn-danger">
    <span x-html="$icon('delete', 'w-4 h-4 mr-2')"></span>
    Delete
</button>

Status Indicators

<!-- Success state -->
<div class="flex items-center text-green-600">
    <span x-html="$icon('check', 'w-5 h-5 mr-2')"></span>
    <span>Verified</span>
</div>

<!-- Warning state -->
<div class="flex items-center text-yellow-600">
    <span x-html="$icon('exclamation', 'w-5 h-5 mr-2')"></span>
    <span>Pending Review</span>
</div>

<!-- Loading state -->
<div class="flex items-center text-blue-600">
    <span x-html="$icon('spinner', 'w-5 h-5 mr-2')"></span>
    <span>Processing...</span>
</div>

Navigation Items

<!-- Sidebar navigation -->
<nav>
    <a href="/dashboard" class="nav-item">
        <span x-html="$icon('home', 'w-5 h-5 mr-3')"></span>
        Dashboard
    </a>
    <a href="/products" class="nav-item">
        <span x-html="$icon('cube', 'w-5 h-5 mr-3')"></span>
        Products
    </a>
    <a href="/orders" class="nav-item">
        <span x-html="$icon('shopping-cart', 'w-5 h-5 mr-3')"></span>
        Orders
    </a>
</nav>

Form Fields

<!-- Search input -->
<div class="relative">
    <div class="absolute inset-y-0 left-0 pl-3 flex items-center">
        <span x-html="$icon('search', 'w-5 h-5 text-gray-400')"></span>
    </div>
    <input type="text" class="pl-10" placeholder="Search...">
</div>

<!-- Password field with toggle -->
<div class="relative" x-data="{ show: false }">
    <input :type="show ? 'text' : 'password'" class="pr-10">
    <button @click="show = !show" class="absolute inset-y-0 right-0 pr-3">
        <span x-show="!show" x-html="$icon('eye', 'w-5 h-5 text-gray-400')"></span>
        <span x-show="show" x-html="$icon('eye-off', 'w-5 h-5 text-gray-400')"></span>
    </button>
</div>

Cards & Panels

<!-- Stat card -->
<div class="bg-white p-6 rounded-lg shadow">
    <div class="flex items-center justify-between">
        <div>
            <p class="text-gray-500 text-sm">Total Sales</p>
            <p class="text-2xl font-bold">$12,345</p>
        </div>
        <div class="p-3 bg-blue-100 rounded-full">
            <span x-html="$icon('currency-dollar', 'w-6 h-6 text-blue-600')"></span>
        </div>
    </div>
</div>

Dropdown Menus

<div x-data="{ open: false }" class="relative">
    <button @click="open = !open" class="flex items-center">
        <span>Options</span>
        <span x-html="$icon('chevron-down', 'w-4 h-4 ml-2')"></span>
    </button>
    
    <div x-show="open" class="absolute right-0 mt-2 w-48 bg-white rounded-lg shadow-lg">
        <a href="#" class="flex items-center px-4 py-2 hover:bg-gray-100">
            <span x-html="$icon('edit', 'w-4 h-4 mr-2')"></span>
            Edit
        </a>
        <a href="#" class="flex items-center px-4 py-2 hover:bg-gray-100">
            <span x-html="$icon('duplicate', 'w-4 h-4 mr-2')"></span>
            Duplicate
        </a>
        <a href="#" class="flex items-center px-4 py-2 text-red-600 hover:bg-gray-100">
            <span x-html="$icon('delete', 'w-4 h-4 mr-2')"></span>
            Delete
        </a>
    </div>
</div>

---

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

<!-- Semantic colors -->
<span x-html="$icon('check', 'w-5 h-5 text-green-600')"></span>    <!-- Success -->
<span x-html="$icon('exclamation', 'w-5 h-5 text-yellow-600')"></span> <!-- Warning -->
<span x-html="$icon('close', 'w-5 h-5 text-red-600')"></span>      <!-- Error -->
<span x-html="$icon('information-circle', 'w-5 h-5 text-blue-600')"></span> <!-- Info -->

<!-- Gray scale -->
<span x-html="$icon('user', 'w-5 h-5 text-gray-400')"></span>      <!-- Muted -->
<span x-html="$icon('user', 'w-5 h-5 text-gray-600')"></span>      <!-- Normal -->
<span x-html="$icon('user', 'w-5 h-5 text-gray-900')"></span>      <!-- Emphasized -->

<!-- With hover states -->
<button class="group">
    <span x-html="$icon('edit', 'w-5 h-5 text-gray-400 group-hover:text-gray-600')"></span>
</button>

---

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
2. Copy the SVG path data
3. Add to the Icons object in icons.js:

'new-icon-name': `<svg class="{{classes}}" fill="none" stroke="currentColor" viewBox="0 0 24 24">
    <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="YOUR_PATH_DATA"/>
</svg>`

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
• Tailwind CSS Documentation
• Alpine.js Magic Properties