Save this content to: .claude/skills/zivar-ui/SKILL.md

# Zivar UI Component Reference & Developer Skill Guide

**Zivar UI** (`zivar/laravel-ui`) is a modern, high-performance UI Component Kit and Admin Template library for **Laravel 11+**, **Livewire 4**, **Tailwind CSS v4**, and **Alpine.js 3**.

---

## ⚡ Core Philosophy & Architecture

1. **Ergonomic `<z:...>` Tag Compiler**: Write clean `<z:button>` or `<z:card>` tags. Laravel compiles them automatically into package Blade components.
2. **Zero-FOUC Dark Mode**: Automatic synchronization with localStorage and system preferences.
3. **Reactive Livewire Integration**: Seamless `wire:model`, `wire:click`, auto-loading states, and live state syncing.
4. **Curated Color Tokens**: 12 harmonious color palettes: `sky`, `emerald`, `indigo`, `violet`, `amber`, `rose`, `teal`, `lime`, `pink`, `cyan`, `orange`, `zinc`.

---

## 🏗️ 1. App Layout & Admin Scaffold

### Main Page Wrapper: `<z:layout.app>`
Wraps the entire page with collapsible desktop sidebar, touch mobile drawer, top navbar, and content container.

```blade
<z:layout.app title="Dashboard - Zivar Workspace">
    {{-- Optional: Custom Page Header --}}
    <z:header 
        category="MANAJEMEN"
        title="Dashboard Utama" 
        subtitle="Pantau analitik, pengguna aktif, dan performa sistem secara real-time."
    >
        <x-slot:actions>
            <z:button color="sky" icon="plus">Tambah Data</z:button>
        </x-slot:actions>
    </z:header>

    {{-- Main Content Area --}}
    <div class="space-y-6">
        <!-- Components here -->
    </div>
</z:layout.app>
```

### Custom Sidebar Override: `<x-slot:sidebar>`
```blade
<z:layout.app title="Dashboard">
    <x-slot:sidebar>
        <z:layout.sidebar brandName="My App" brandSubtitle="Enterprise" logoIcon="shield">
            <z:layout.sidebar.group title="Menu Utama">
                <z:layout.sidebar.item href="/dashboard" :active="request()->is('dashboard')" icon="dashboard">
                    Dashboard
                </z:layout.sidebar.item>
                <z:layout.sidebar.item href="/users" :active="request()->is('users*')" icon="user-circle" badge="12" badgeColor="sky">
                    Kelola Pengguna
                </z:layout.sidebar.item>
            </z:layout.sidebar.group>
        </z:layout.sidebar>
    </x-slot:sidebar>
</z:layout.app>
```

---

## 🎨 2. Core UI Components

### Button: `<z:button>`
| Prop | Options / Type | Default | Description |
| :--- | :--- | :--- | :--- |
| `variant` | `solid`, `label`, `outline`, `text`, `glow`, `gradient`, `glass` | `solid` | Visual aesthetic style |
| `color` | `sky`, `emerald`, `indigo`, `violet`, `amber`, `rose`, `teal`, `lime`, `pink`, `cyan`, `orange`, `zinc` | `sky` | Palette tint |
| `size` | `xs`, `sm`, `md`, `lg`, `xl` | `md` | Padding & text scale |
| `icon` | String (e.g. `sparkles`, `plus`, `arrow-right`) | `null` | Preceding icon |
| `iconTrailing` | String | `null` | Trailing icon |
| `copy` | String | `null` | 1-click clipboard copy text |
| `loading` | Boolean | `false` | Shows animated loading spinner |

```blade
<z:button variant="glow" color="sky" icon="sparkles">Simpan Perubahan</z:button>
<z:button variant="label" color="emerald" icon="check">Selesai</z:button>
<z:button variant="outline" color="rose" icon="trash">Hapus</z:button>
```

---

### Card & Metric Box: `<z:card>`
| Prop | Options / Type | Default | Description |
| :--- | :--- | :--- | :--- |
| `title` | String | `null` | Card title |
| `subtitle` | String | `null` | Card subtitle / description |
| `icon` | String | `null` | Header icon |
| `iconColor`| Color token | `sky` | Icon background tint |
| `glass` | Boolean | `false` | Frosted glassmorphism effect |
| `collapsible`| Boolean | `false` | Enable collapse/expand trigger |

```blade
<z:card title="Total Penjualan" subtitle="Bulan Ini" icon="chart-bar" iconColor="emerald">
    <div class="text-3xl font-black text-slate-900 dark:text-white">Rp 124.500.000</div>
    <p class="text-xs text-emerald-600 mt-1 font-semibold">↑ +14.2% dari bulan lalu</p>
</z:card>
```

---

### Autocomplete & Typeahead: `<z:autocomplete>`
Supports both slotted `<z:autocomplete.item>` child items and dynamic `:items="[...]"` arrays with two-way `wire:model`.

```blade
{{-- Slotted Syntax --}}
<z:autocomplete wire:model.live="state" label="Provinsi" placeholder="Cari provinsi..." icon="map-pin">
    <z:autocomplete.item>Jawa Barat</z:autocomplete.item>
    <z:autocomplete.item>Jawa Tengah</z:autocomplete.item>
    <z:autocomplete.item>DKI Jakarta</z:autocomplete.item>
</z:autocomplete>

{{-- Array / Object Syntax --}}
<z:autocomplete 
    wire:model.live="selectedUser" 
    :items="$userList" 
    label="Pilih Anggota" 
    placeholder="Ketik nama pengguna..." 
/>
```

---

### Avatar & Avatar Group: `<z:avatar>`
```blade
<z:avatar src="https://i.pravatar.cc/150?img=1" size="lg" status="online" />
<z:avatar name="Ravi Zulfikar" color="sky" size="md" />

{{-- Stacked Group --}}
<z:avatar.group max="3">
    <z:avatar name="Sarah Jenkins" color="rose" />
    <z:avatar name="Alex Rivera" color="indigo" />
    <z:avatar name="Budi Santoso" color="emerald" />
    <z:avatar name="Dewi Lestari" color="amber" />
</z:avatar.group>
```

---

### Badge & Counter: `<z:badge>`
```blade
<z:badge variant="glow" color="emerald" dot>Aktif</z:badge>
<z:badge variant="label" color="amber">Menunggu Konfirmasi</z:badge>
<z:badge variant="solid" color="rose">Critical</z:badge>
```

---

### Modal & Slideover: `<z:modal>`, `<z:slideover>`
```blade
<z:modal id="edit-user-modal" title="Edit Profil Pengguna">
    <form class="space-y-4">
        <z:input label="Nama Lengkap" placeholder="Masukkan nama..." />
        <z:input label="Alamat Email" type="email" placeholder="[email protected]" />
    </form>
    <x-slot:footer>
        <z:button color="zinc" variant="text" @click="open = false">Batal</z:button>
        <z:button color="sky">Simpan</z:button>
    </x-slot:footer>
</z:modal>
```

---

### Data Table: `<z:table>`
```blade
<z:table>
    <x-slot:head>
        <z:table.th>Nama</z:table.th>
        <z:table.th>Peran</z:table.th>
        <z:table.th>Status</z:table.th>
        <z:table.th align="right">Aksi</z:table.th>
    </x-slot:head>
    <z:table.tr>
        <z:table.td font-bold>Ravi Zulfikar</z:table.td>
        <z:table.td>Lead Developer</z:table.td>
        <z:table.td><z:badge color="emerald" dot>Active</z:badge></z:table.td>
        <z:table.td align="right">
            <z:button size="xs" variant="text" icon="pencil" />
        </z:table.td>
    </z:table.tr>
</z:table>
```

---

## 🚀 3. Extended Advanced Suites

### Digital Signature Pad: `<z:signature>`
Bézier curve touch drawing, undo history, color presets, PNG base64 export.

```blade
<z:signature 
    wire:model="signatureData" 
    label="Tanda Tangan Digital" 
    color="sky" 
    clearable 
    downloadable 
/>
```

---

### Kanban Project Board: `<z:kanban>`
Multi-column HTML5 drag & drop task board with Livewire event syncing.

```blade
<z:kanban :columns="$columns" wire:on-move="updateTaskOrder" />
```

---

### Image Gallery & Lightbox: `<z:image-gallery>`
Masonry or responsive grid gallery with fullscreen lightbox and thumbnail ribbon.

```blade
<z:image-gallery :images="$galleryImages" layout="masonry" lightbox />
```

---

### Full Calendar Suite: `<z:calendar>`
Monthly scheduling calendar with category badges and event modal.

```blade
<z:calendar :events="$calendarEvents" />
```

---

### ApexCharts & Graphs: `<z:chart>`
Dark/Light mode auto-synchronization observer.

```blade
<z:chart 
    type="area" 
    :series="$chartSeries" 
    :categories="$chartDates" 
    height="320" 
    color="sky" 
/>
```

---

## 🛠️ 4. Artisan CLI Helper

```bash
# Publish components to resources/views/components
php artisan zivar:install

# Publish full documentation views
php artisan zivar:install --views

# Overwrite existing files
php artisan zivar:install --force
```