orion/docs/frontend/shared/ui-components-quick-reference.md

# UI Components Quick Reference

## Most Common Patterns

### 📝 Form Field (Basic)
```html
<label class="block mb-4 text-sm">
    <span class="text-gray-700 dark:text-gray-400">Field Name</span>
    <input
        type="text"
        x-model="formData.field"
        class="block w-full mt-1 text-sm dark:text-gray-300 dark:border-gray-600 dark:bg-gray-700 focus:border-purple-400 focus:outline-none focus:shadow-outline-purple dark:focus:shadow-outline-gray form-input"
    />
</label>
```

### 📝 Required Field with Error
```html
<label class="block mb-4 text-sm">
    <span class="text-gray-700 dark:text-gray-400">
        Field Name <span class="text-red-600">*</span>
    </span>
    <input
        type="text"
        x-model="formData.field"
        required
        :class="{ 'border-red-600': errors.field }"
        class="block w-full mt-1 text-sm dark:text-gray-300 dark:border-gray-600 dark:bg-gray-700 focus:border-purple-400 focus:outline-none focus:shadow-outline-purple form-input"
    />
    <span x-show="errors.field" class="text-xs text-red-600 dark:text-red-400" x-text="errors.field"></span>
</label>
```

### 📝 Read-Only Field
```html
<label class="block mb-4 text-sm">
    <span class="text-gray-700 dark:text-gray-400">Field Name</span>
    <input
        type="text"
        x-model="data.field"
        disabled
        class="block w-full mt-1 text-sm bg-gray-100 border-gray-300 rounded-md dark:bg-gray-700 dark:text-gray-400 dark:border-gray-600 cursor-not-allowed"
    />
</label>
```

### 🃏 Stats Card
```html
<div class="flex items-center p-4 bg-white rounded-lg shadow-xs dark:bg-gray-800">
    <div class="p-3 mr-4 text-purple-500 bg-purple-100 rounded-full dark:text-purple-100 dark:bg-purple-500">
        <span x-html="$icon('user-group', 'w-5 h-5')"></span>
    </div>
    <div>
        <p class="mb-2 text-sm font-medium text-gray-600 dark:text-gray-400">Label</p>
        <p class="text-lg font-semibold text-gray-700 dark:text-gray-200">Value</p>
    </div>
</div>
```

### 🃏 Info Card
```html
<div class="px-4 py-3 bg-white rounded-lg shadow-md dark:bg-gray-800">
    <h3 class="mb-4 text-lg font-semibold text-gray-700 dark:text-gray-200">Title</h3>
    <div class="space-y-3">
        <div>
            <p class="text-xs font-semibold text-gray-600 dark:text-gray-400 uppercase">Label</p>
            <p class="text-sm text-gray-700 dark:text-gray-300">Value</p>
        </div>
    </div>
</div>
```

### 🔘 Primary Button
```html
<button class="px-4 py-2 text-sm font-medium leading-5 text-white transition-colors duration-150 bg-purple-600 border border-transparent rounded-lg hover:bg-purple-700 focus:outline-none">
    Click Me
</button>
```

### 🔘 Button with Icon
```html
<button class="flex items-center px-4 py-2 text-sm font-medium leading-5 text-white transition-colors duration-150 bg-purple-600 border border-transparent rounded-lg hover:bg-purple-700">
    <span x-html="$icon('plus', 'w-4 h-4 mr-2')"></span>
    Add Item
</button>
```

### 🔘 Secondary Button
```html
<button class="px-4 py-2 text-sm font-medium leading-5 text-gray-700 transition-colors duration-150 bg-white border border-gray-300 rounded-lg hover:border-gray-400 dark:text-gray-400 dark:border-gray-600 dark:bg-gray-800">
    Cancel
</button>
```

### 🏷️ Status Badge (Success)
```html
<span class="inline-flex items-center px-3 py-1 text-xs font-semibold leading-tight text-green-700 bg-green-100 rounded-full dark:bg-green-700 dark:text-green-100">
    <span x-html="$icon('check-circle', 'w-3 h-3 mr-1')"></span>
    Active
</span>
```

### 🏷️ Status Badge (Warning)
```html
<span class="inline-flex items-center px-3 py-1 text-xs font-semibold leading-tight text-orange-700 bg-orange-100 rounded-full dark:bg-orange-700 dark:text-orange-100">
    <span x-html="$icon('clock', 'w-3 h-3 mr-1')"></span>
    Pending
</span>
```

### 🏷️ Status Badge (Danger)
```html
<span class="inline-flex items-center px-3 py-1 text-xs font-semibold leading-tight text-red-700 bg-red-100 rounded-full dark:bg-red-700 dark:text-red-100">
    <span x-html="$icon('x-circle', 'w-3 h-3 mr-1')"></span>
    Inactive
</span>
```

## Grid Layouts

### 2 Columns (Desktop)
```html
<div class="grid gap-6 md:grid-cols-2">
    <!-- Column 1 -->
    <div>...</div>
    <!-- Column 2 -->
    <div>...</div>
</div>
```

### 4 Columns (Responsive)
```html
<div class="grid gap-6 mb-8 md:grid-cols-2 xl:grid-cols-4">
    <!-- Cards -->
</div>
```

## Color Classes

### Background Colors
- Primary: `bg-purple-600`
- Success: `bg-green-600`
- Warning: `bg-orange-600`
- Danger: `bg-red-600`
- Info: `bg-blue-600`

### Text Colors
- Primary: `text-purple-600`
- Success: `text-green-600`
- Warning: `text-orange-600`
- Danger: `text-red-600`
- Info: `text-blue-600`

### Icon Colors
- Primary: `text-purple-500 bg-purple-100`
- Success: `text-green-500 bg-green-100`
- Warning: `text-orange-500 bg-orange-100`
- Danger: `text-red-500 bg-red-100`
- Info: `text-blue-500 bg-blue-100`

## Common Icons
- `user-group` - Users/Teams
- `badge-check` - Verified
- `check-circle` - Success
- `x-circle` - Error/Inactive
- `clock` - Pending
- `calendar` - Dates
- `refresh` - Update
- `edit` - Edit
- `delete` - Delete
- `plus` - Add
- `arrow-left` - Back
- `exclamation` - Warning

## Spacing
- Small gap: `gap-3`
- Medium gap: `gap-6`
- Large gap: `gap-8`
- Margin bottom: `mb-4`, `mb-6`, `mb-8`
- Padding: `p-3`, `p-4`, `px-4 py-3`

## Quick Copy-Paste: Page Structure

```html
{# app/templates/admin/your-page.html #}
{% extends "admin/base.html" %}

{% block title %}Your Page{% endblock %}

{% block alpine_data %}yourPageData(){% endblock %}

{% block content %}
<!-- Page Header -->
<div class="my-6">
    <h2 class="text-2xl font-semibold text-gray-700 dark:text-gray-200">
        Page Title
    </h2>
</div>

<!-- Loading State -->
<div x-show="loading" class="text-center py-12">
    <span x-html="$icon('spinner', 'inline w-8 h-8 text-purple-600')"></span>
    <p class="mt-2 text-gray-600 dark:text-gray-400">Loading...</p>
</div>

<!-- Content -->
<div x-show="!loading">
    <div class="px-4 py-3 mb-8 bg-white rounded-lg shadow-md dark:bg-gray-800">
        <!-- Your content here -->
    </div>
</div>
{% endblock %}
```

## Remember

1. Always use `dark:` variants for dark mode
2. Add `:disabled="saving"` to buttons during operations
3. Use `x-show` for conditional display
4. Use `x-text` for dynamic text
5. Use `x-html="$icon(...)"` for icons
6. Validation errors: `border-red-600` class
7. Helper text: `text-xs text-gray-600`
8. Error text: `text-xs text-red-600`

## Reference Page

Visit `/admin/components` for full component library with live examples!