vibes-plug 2.5.0 → 2.11.0

package/skills/ui-components-expert/SKILL.md

@@ -1,280 +1,166 @@
----
-name: ui-components-expert
-description: "Expert guide for building production-quality UI components following the 4 pillars: Input Controls, Navigation, Information, and Containers. Covers React 19, Radix UI, shadcn/ui, accessibility (WCAG 2.2), and modern interaction patterns / Panduan ahli membangun komponen UI berkualitas produksi dengan 4 pilar: Kontrol Input, Navigasi, Informasi, dan Kontainer."
+---
+name: ui-components-expert
+description: Expert guide for building production-quality UI components following the 4 pillars. Covers React 19, Radix UI, Base UI, Tailwind v4, Material Design 3 (M3), WCAG 2.2 / Panduan ahli membangun komponen UI berkualitas produksi dengan M3.
 author: "Roedy Rustam"
----
-
-# 🎨 UI Components Expert (2026 Edition)
-
-[English](#english) | [Bahasa Indonesia](#bahasa-indonesia)
-
----
-
-<a name="english"></a>
-## English
-
-### Description
-Expert guide for evaluating, auditing, and building production-quality UI components in 2026. Covers the **4 pillars of UI components** with modern tooling: **shadcn/ui**, **Radix UI**, **Base UI**, **React 19 patterns**, **WCAG 2.2 accessibility**, and micro-interaction design. Use this skill when building, reviewing, or improving any interactive UI element.
-
-### Trigger Conditions
-- Building or reviewing UI components: buttons, forms, modals, navigation, tooltips, notifications.
-- Implementing accessible components with ARIA patterns and keyboard navigation.
-- Auditing existing components against WCAG 2.2 and interaction design standards.
-- Setting up a component library with **shadcn/ui**, **Radix UI**, or **Base UI**.
-- Adding micro-interactions, hover states, focus rings, and animation to components.
-
----
-
-### Component Stack Recommendation (2026)
-
-| Layer | Tool | Purpose |
-|---|---|---|
-| **Headless Primitives** | Radix UI / Base UI (MUI) | Accessibility, behavior, no styles |
-| **Component Library** | shadcn/ui (copy-paste) | Pre-styled, customizable, owns the code |
-| **Styling** | Tailwind CSS v4 | Utility-first, design tokens via `@theme` |
-| **Animation** | Motion (Framer Motion v12) | Spring physics, layout animations |
-| **Icons** | Lucide React | Consistent, tree-shakeable icon set |
-| **Forms** | React Hook Form + Zod | Type-safe, performant form state |
-
----
-
-### The 4 Pillars of UI Components
-
-#### Pillar 1: Input Controls
-Components that capture user intent and data.
-*Examples: Buttons, Checkboxes, Radio Groups, Text Fields, Selects, Switches, Sliders, Date Pickers*
-
-**Best Practices:**
-- **Clear Visual States**: Every input must have distinct `default`, `hover`, `active`, `focus`, `disabled`, and `error` states.
-- **Touch Target Sizes**: Minimum 44×44px (WCAG 2.5.8) for all interactive elements on mobile.
-- **Immediate Feedback**: Provide visual/haptic feedback on interaction — ripple, color change, or animation.
-- **Inline Validation**: Show error messages immediately after blur, not only on submit. Use `aria-invalid` and `aria-describedby` for screen readers.
-- **React Hook Form + Zod Pattern**:
-```tsx
-import { useForm } from 'react-hook-form';
-import { zodResolver } from '@hookform/resolvers/zod';
-import { z } from 'zod';
-
-const schema = z.object({
-  email: z.string().email('Invalid email address'),
-  name: z.string().min(2, 'Name must be at least 2 characters'),
-});
-
-export function UserForm() {
-  const { register, handleSubmit, formState: { errors, isSubmitting } } = useForm({
-    resolver: zodResolver(schema),
-  });
-
-  return (
-    <form onSubmit={handleSubmit(onSubmit)}>
-      <div>
-        <input
-          {...register('email')}
-          aria-invalid={!!errors.email}
-          aria-describedby={errors.email ? 'email-error' : undefined}
-          className="..."
-        />
-        {errors.email && (
-          <p id="email-error" role="alert" className="text-destructive text-sm">
-            {errors.email.message}
-          </p>
-        )}
-      </div>
-      <button type="submit" disabled={isSubmitting}>
-        {isSubmitting ? 'Saving...' : 'Save'}
-      </button>
-    </form>
-  );
-}
-```
-
----
-
-#### Pillar 2: Navigation
-Components that help users move through the application structure.
-*Examples: Navbars, Tabs, Breadcrumbs, Pagination, Sidebars, Dropdowns, Command Palettes*
-
-**Best Practices:**
-- **Active State Clarity**: Always indicate the current location with a high-contrast visual indicator (filled background, underline, bold text). Never use color alone.
-- **Keyboard Navigation**: Tabs must support Arrow Keys; menus must support `Escape` to close; focus must be managed on open/close.
-- **Responsive Patterns**: Use bottom navigation on mobile (<768px), collapsible sidebar on tablet, full sidebar on desktop.
-- **Command Palette (2026 Standard)**: Add `⌘K` / `Ctrl+K` command palette for power users using `cmdk` library.
-- **`<Link>` with View Transitions** (Next.js 15):
-```tsx
-import Link from 'next/link';
-
-// Enables smooth page transitions
-<Link href="/dashboard" viewTransition>
-  Dashboard
-</Link>
-```
-- **ARIA Roles**: Use `role="navigation"` with `aria-label` on `<nav>`. Mark current page with `aria-current="page"`.
-
----
-
-#### Pillar 3: Information & Feedback
-Components that display status, guidance, or alerts to users.
-*Examples: Toast Notifications, Tooltips, Badges, Alert Banners, Progress Bars, Skeletons, Empty States*
-
-**Best Practices:**
-- **Contextual Color System**: Use semantic colors consistently — green (success), red (error/destructive), yellow (warning), blue (info).
-- **Toast Notifications**: Use **Sonner** (lightweight, accessible) — limit to 3 concurrent toasts, auto-dismiss success in 4s, keep errors until dismissed.
-- **Skeleton Loading**: Prefer skeletons over spinners for content areas — they reduce perceived load time and prevent layout shift (CLS).
-```tsx
-// Sonner toast
-import { toast } from 'sonner';
-
-toast.success('Profile updated!');
-toast.error('Something went wrong', { description: 'Please try again.' });
-toast.promise(saveProfile(), {
-  loading: 'Saving...',
-  success: 'Saved!',
-  error: 'Failed to save',
-});
-```
-- **Empty States**: Never show blank areas — provide illustration, explanation, and a clear CTA.
-- **`aria-live` for Dynamic Content**: Use `aria-live="polite"` for non-urgent updates, `aria-live="assertive"` for critical errors.
-
----
-
-#### Pillar 4: Containers & Layout
-Components that group related content into structured visual units.
-*Examples: Cards, Modals (Dialogs), Sheets (Drawers), Accordions, Tabs, Carousels, Popover*
-
-**Best Practices:**
-- **Modal/Dialog (Radix UI)**:
-```tsx
-import * as Dialog from '@radix-ui/react-dialog';
-
-export function ConfirmDialog({ onConfirm }: { onConfirm: () => void }) {
-  return (
-    <Dialog.Root>
-      <Dialog.Trigger asChild>
-        <button>Delete Account</button>
-      </Dialog.Trigger>
-      <Dialog.Portal>
-        <Dialog.Overlay className="fixed inset-0 bg-black/50 backdrop-blur-sm animate-in fade-in" />
-        <Dialog.Content
-          className="fixed left-1/2 top-1/2 -translate-x-1/2 -translate-y-1/2 bg-background rounded-xl shadow-2xl p-6 w-[400px] animate-in fade-in zoom-in-95"
-          aria-describedby="dialog-description"
-        >
-          <Dialog.Title className="text-lg font-semibold">Are you sure?</Dialog.Title>
-          <Dialog.Description id="dialog-description" className="text-muted-foreground mt-2">
-            This action cannot be undone.
-          </Dialog.Description>
-          <div className="flex gap-3 mt-6 justify-end">
-            <Dialog.Close asChild>
-              <button className="btn-secondary">Cancel</button>
-            </Dialog.Close>
-            <button onClick={onConfirm} className="btn-destructive">Delete</button>
-          </div>
-        </Dialog.Content>
-      </Dialog.Portal>
-    </Dialog.Root>
-  );
-}
-```
-- **Focus Trap**: Radix UI handles focus trapping automatically inside dialogs.
-- **Scroll Lock**: Lock body scroll when modal is open — Radix handles this.
-- **Card Design**: Use subtle shadows + borders for elevation. Never use heavy drop shadows on cards in light mode.
-- **Sheet/Drawer**: Use for mobile-first secondary actions. Prefer bottom sheet on mobile, side sheet on desktop.
-
----
-
-### Micro-Interaction Checklist (Next-Gen)
-These small details separate premium from basic UI:
-- [ ] All interactive elements have `:focus-visible` ring (2px, brand color).
-- [ ] Buttons have loading state with spinner + disabled state.
-- [ ] Form fields animate error shake on invalid submit.
-- [ ] **Physics-Based Animation**: Do not rely solely on linear `ease-in-out`. Use Framer Motion (v12) `spring` physics (`stiffness: 300, damping: 20`) for modals, popovers, and interactive elements to provide a natural, snappy feel.
-- [ ] Hover transitions on simple buttons use `transition-all duration-200 ease-out`.
-- [ ] Modals animate in with fade + scale: `animate-in fade-in zoom-in-95`.
-- [ ] List items stagger-animate when rendered (use Motion `stagger`).
-- [ ] Skeleton loaders match the exact layout of the content they replace.
-- [ ] Dark mode tested for all states (especially error/warning colors).
-
-### Accessibility (WCAG 2.2) Quick Reference
-| Criterion | Requirement |
-|---|---|
-| **1.4.3** | Text contrast ≥4.5:1 (normal), ≥3:1 (large/bold) |
-| **2.5.8** | Touch target ≥24×24px (min), 44×44px (recommended) |
-| **2.4.7** | Focus indicator visible on all interactive elements |
-| **2.4.11** | Focus not obscured by sticky headers |
-| **3.2.2** | No unexpected context change on input |
-
----
-
-<a name="bahasa-indonesia"></a>
-## Bahasa Indonesia
-
-### Deskripsi
-Panduan ahli untuk mengevaluasi, mengaudit, dan membangun komponen UI berkualitas produksi di 2026. Mencakup **4 pilar komponen UI** dengan tooling modern: **shadcn/ui**, **Radix UI**, **Base UI**, **pola React 19**, **aksesibilitas WCAG 2.2**, dan desain micro-interaction. Gunakan skill ini saat membangun, me-review, atau meningkatkan elemen UI interaktif apapun.
-
-### Kondisi Pemicu
-- Membangun atau me-review komponen UI: tombol, form, modal, navigasi, tooltip, notifikasi.
-- Mengimplementasikan komponen aksesibel dengan pola ARIA dan navigasi keyboard.
-- Mengaudit komponen yang ada terhadap standar WCAG 2.2 dan desain interaksi.
-- Menyiapkan library komponen dengan shadcn/ui, Radix UI, atau Base UI.
-- Menambahkan micro-interaction, hover state, focus ring, dan animasi ke komponen.
-
-### QA Visual Mandatori (KRITIS)
-- **Siklus Verifikasi Visual**: Anda DILARANG KERAS menyelesaikan komponen UI tanpa mengambil screenshot menggunakan `browser_subagent` dan menganalisisnya via `visual-qa-vision-agent`.
-- **Standar Pixel-Perfect**: Jangan menebak padding/margin. Ambil gambar, analisis dengan kemampuan Vision Anda, dan koreksi pergeseran tata letak hingga sempurna.
-
-### Stack Komponen Rekomendasi (2026)
-- **Headless Primitives**: Radix UI / Base UI — aksesibilitas dan behavior tanpa style.
-- **Library Komponen**: shadcn/ui — pre-styled, customizable, kode dimiliki sendiri.
-- **Styling**: Tailwind CSS v4 — utility-first dengan design token via `@theme`.
-- **Animasi**: Motion (Framer Motion v12) — spring physics, layout animations.
-- **Form**: React Hook Form + Zod — type-safe, performa tinggi.
-
-### 4 Pilar Komponen UI
-
-#### Pilar 1: Kontrol Input
-Komponen yang menangkap input dan data pengguna (tombol, form, checkbox, select, switch).
-
-**Best Practices:**
-- Setiap input harus memiliki state visual yang jelas: `default`, `hover`, `active`, `focus`, `disabled`, `error`.
-- Ukuran touch target minimal 44×44px untuk elemen interaktif di mobile.
-- Validasi inline dengan pesan error yang muncul setelah blur, bukan hanya saat submit.
-- Gunakan `aria-invalid` dan `aria-describedby` untuk screen reader.
-- Gunakan **React Hook Form + Zod** untuk form yang type-safe dan berperforma tinggi.
-
-#### Pilar 2: Navigasi
-Komponen yang membantu pengguna bergerak dalam struktur aplikasi (navbar, tab, breadcrumb, sidebar, command palette).
-
-**Best Practices:**
-- Selalu tunjukkan lokasi saat ini dengan indikator visual yang jelas (background, garis bawah, teks tebal).
-- Navigasi keyboard wajib: Arrow Keys untuk tab/menu, Escape untuk menutup, fokus terkelola saat buka/tutup.
-- Gunakan bottom navigation di mobile, sidebar di desktop.
-- Tambahkan command palette `⌘K` untuk power user menggunakan library `cmdk`.
-- Tandai halaman aktif dengan `aria-current="page"`.
-
-#### Pilar 3: Informasi & Feedback
-Komponen yang menampilkan status, panduan, atau peringatan (toast, tooltip, badge, skeleton, empty state).
-
-**Best Practices:**
-- Warna semantik yang konsisten: hijau (sukses), merah (error), kuning (peringatan), biru (info).
-- Gunakan **Sonner** untuk toast notifikasi — ringan dan aksesibel.
-- Gunakan skeleton loader (bukan spinner) untuk area konten guna mengurangi perceived load time.
-- Selalu sediakan empty state dengan ilustrasi, penjelasan, dan CTA yang jelas.
-- Gunakan `aria-live="polite"` untuk pembaruan konten dinamis.
-
-#### Pilar 4: Kontainer & Layout
-Komponen yang mengelompokkan konten terkait (card, modal/dialog, sheet/drawer, accordion, popover).
-
-**Best Practices:**
-- Gunakan **Radix UI Dialog** untuk modal — menangani focus trap, scroll lock, dan aksesibilitas secara otomatis.
-- Animasikan modal dengan fade + scale: `animate-in fade-in zoom-in-95`.
-- Gunakan shadow tipis + border untuk elevasi card. Hindari drop shadow berat di mode terang.
-- Gunakan bottom sheet di mobile, side sheet di desktop untuk aksi sekunder.
-
-### Checklist Micro-Interaction (Next-Gen)
-Detail kecil yang membedakan UI premium dari yang biasa:
-- [ ] Semua elemen interaktif memiliki `:focus-visible` ring (2px, warna brand).
-- [ ] Tombol memiliki loading state dengan spinner + disabled state.
-- [ ] **Animasi Fisika (Spring)**: Hindari transisi linier kaku. Gunakan Framer Motion (v12) `spring` (`stiffness: 300, damping: 20`) pada interaksi klik, modal, dan dropdown agar terasa alami dan sangat responsif.
-- [ ] Hover transition sederhana menggunakan `transition-all duration-200 ease-out`.
-- [ ] Modal dan drawer muncul dengan animasi fade + scale yang mulus.
-- [ ] Skeleton loader sesuai persis dengan layout konten yang digantikan.
-- [ ] Dark mode diuji untuk semua state (terutama warna error/warning).
+---
+
+# 🎨 UI Components Expert (2026/2027 Edition)
+
+[English](#english) | [Bahasa Indonesia](#bahasa-indonesia)
+
+---
+
+<a name="english"></a>
+## English
+
+### Description
+Evaluate, audit, and build production-quality UI components. Apply the 4 pillars of UI components with modern tooling: **shadcn/ui**, **Radix UI**, **Base UI**, **React 19**, **Tailwind v4**, **Material Design 3 (M3)**, **WCAG 2.2**, and micro-interaction design.
+
+### Trigger Conditions
+- Build or review UI components (buttons, forms, modals, navigation, tooltips).
+- Implement accessible components (ARIA patterns, keyboard navigation).
+- Audit components against WCAG 2.2.
+- Set up component libraries (shadcn/ui, Radix UI, Base UI).
+- Add micro-interactions and animations.
+
+## Orchestration & Integration
+This skill orchestrates and connects with:
+- `senior-frontend`: For overall React 19 / Next.js 15 architecture.
+- `tailwind-expert`: For Tailwind v4 styling and theming.
+- `design-system-architect`: For system-wide design tokens and primitives.
+- `hig`: For Human Interface Guidelines (Hierarchy, Harmony, Consistency).
+
+### Component Stack (2026/2027)
+- **Headless Primitives**: Radix UI / Base UI (Accessibility, behavior).
+- **Component Library**: shadcn/ui (Pre-styled, customizable).
+- **Styling**: Tailwind CSS v4 (Utility-first, `@theme` tokens).
+- **Animation**: Motion / Framer Motion v12 (Spring physics).
+- **Icons**: Lucide React.
+- **Forms**: React Hook Form + Zod.
+
+### The 4 Pillars of UI Components
+
+#### 1: Input Controls
+Capture user intent and data (Buttons, Forms, Selects).
+- **M3 Integration (if requested)**: Use M3 button variants: Filled, Tonal, Elevated, Outlined, and Text. Include FABs (Floating Action Buttons) for primary screen actions.
+- **Visual States**: Define `default`, `hover`, `active`, `focus`, `disabled`, and `error`.
+- **Touch Targets**: Minimum 44×44px (WCAG 2.5.8), M3 recommends 48x48px.
+- **Immediate Feedback**: Provide visual ripple or scale animation on interaction.
+- **Inline Validation**: Show errors on blur. Use `aria-invalid` and `aria-describedby`.
+- **Stack**: React Hook Form + Zod.
+
+#### 2: Navigation
+Move through application structure (Navbars, Tabs, Command Palettes).
+- **M3 Integration (if requested)**: Use M3 Navigation Bar for mobile (bottom), Navigation Rail for tablet, and Navigation Drawer for desktop.
+- **Active State**: Indicate current location with high-contrast visual indicators.
+- **Keyboard Navigation**: Support Arrow Keys for tabs, `Escape` to close.
+- **Responsive**: Bottom navigation (<768px), collapsible sidebar (tablet), full sidebar (desktop).
+- **Command Palette**: Add `⌘K` via `cmdk`.
+- **Next.js 15**: Use `<Link viewTransition>` for smooth transitions.
+- **ARIA**: Use `role="navigation"` and `aria-current="page"`.
+
+#### 3: Information & Feedback
+Display status and guidance (Toasts, Skeletons, Empty States).
+- **M3 Integration (if requested)**: Use Snackbar for transient messages. Use Badges on navigation icons for notifications.
+- **Color Semantics**: Green (success), red (error), yellow (warning), blue (info).
+- **Toasts**: Use **Sonner**. Limit to 3 concurrent. Auto-dismiss success, keep errors until dismissed.
+- **Loading**: Use Skeletons matching exact content layout over spinners (prevents CLS).
+- **Empty States**: Provide illustration, context, and clear CTA.
+- **ARIA**: `aria-live="polite"` (updates), `aria-live="assertive"` (critical).
+
+#### 4: Containers & Layout
+Group related content (Cards, Modals, Sheets).
+- **M3 Integration (if requested)**: Use M3 Card variants: Elevated, Filled, Outlined. Follow M3 Dialog guidelines for Modals.
+- **Modals**: Use Radix UI Dialog. It handles focus trapping and scroll locking automatically.
+- **Animation**: Animate in (`animate-in fade-in zoom-in-95`).
+- **Cards**: Use subtle shadows + borders. Avoid heavy drop shadows in light mode.
+- **Sheets**: Use bottom sheet for mobile secondary actions, side sheet for desktop.
+
+### Micro-Interaction Checklist
+- [ ] Implement `:focus-visible` ring (2px, brand color) on all interactives.
+- [ ] **M3 State Layers**: If using M3, ensure interactive elements have distinct Hover, Focus, Pressed, and Dragged state layers.
+- [ ] Add loading state (spinner + disabled) to submit buttons.
+- [ ] Use **Framer Motion v12 spring physics** (`stiffness: 300, damping: 20`) for natural, snappy interactions. Avoid rigid linear transitions.
+- [ ] Use `transition-all duration-200 ease-out` for simple hovers.
+- [ ] Test dark mode for all states (especially error contrast).
+
+### WCAG 2.2 Quick Reference
+- **1.4.3**: Text contrast ≥4.5:1.
+- **2.5.8**: Touch target ≥24×24px (min), 44×44px (target).
+- **2.4.7**: Visible focus indicator.
+
+---
+
+<a name="bahasa-indonesia"></a>
+## Bahasa Indonesia
+
+### Deskripsi
+Evaluasi, audit, dan bangun komponen UI berkualitas produksi. Terapkan 4 pilar komponen UI dengan tooling modern: **shadcn/ui**, **Radix UI**, **Base UI**, **React 19**, **Tailwind v4**, **Material Design 3 (M3)**, **WCAG 2.2**, dan desain micro-interaction.
+
+### Kondisi Pemicu
+- Membangun atau me-review komponen UI (tombol, form, modal, navigasi).
+- Implementasi komponen aksesibel (pola ARIA, navigasi keyboard).
+- Audit komponen berdasarkan WCAG 2.2.
+- Setup library komponen (shadcn/ui, Radix UI, Base UI).
+- Menambahkan micro-interaction dan animasi.
+
+## Integrasi Orkestrasi
+Skill ini mengorkestrasi dan terhubung dengan:
+- `senior-frontend`: Untuk arsitektur keseluruhan React 19 / Next.js 15.
+- `tailwind-expert`: Untuk styling dan theming Tailwind v4.
+- `design-system-architect`: Untuk design token dan primitif skala sistem.
+- `hig`: Untuk panduan Human Interface (Hierarki, Harmoni, Konsistensi).
+
+### QA Visual Mandatori
+- Wajib gunakan `browser_subagent` dan `visual-qa-vision-agent` untuk validasi layout.
+- Standar Pixel-Perfect: Jangan menebak ukuran. Ambil screenshot dan koreksi pergeseran tata letak.
+
+### Stack Komponen (2026/2027)
+- **Headless**: Radix UI / Base UI.
+- **Library**: shadcn/ui.
+- **Styling**: Tailwind CSS v4.
+- **Animasi**: Motion / Framer Motion v12.
+- **Form**: React Hook Form + Zod.
+
+### 4 Pilar Komponen UI
+
+#### 1: Kontrol Input
+Tangkap data (Tombol, Form, Select).
+- **Integrasi M3 (jika diminta)**: Gunakan varian tombol M3: Filled, Tonal, Elevated, Outlined, dan Text. Sertakan FABs (Floating Action Buttons).
+- Definisikan state visual: `default`, `hover`, `active`, `focus`, `disabled`, `error`.
+- Target sentuh minimal 44×44px (M3 merekomendasikan 48x48px).
+- Tampilkan error saat blur dengan `aria-invalid` dan `aria-describedby`.
+- Gunakan React Hook Form + Zod.
+
+#### 2: Navigasi
+Pergerakan pengguna (Navbar, Tab, Command Palette).
+- **Integrasi M3 (jika diminta)**: Gunakan Navigation Bar M3 untuk mobile, Navigation Rail untuk tablet, dan Navigation Drawer untuk desktop.
+- Gunakan indikator visual kontras tinggi untuk lokasi aktif.
+- Wajib dukung navigasi keyboard (Arrow Keys, Escape).
+- Responsive: Bottom navigation (<768px), sidebar desktop.
+- Gunakan `cmdk` untuk Command Palette `⌘K`.
+- Tandai navigasi aktif dengan `aria-current="page"`.
+
+#### 3: Informasi & Feedback
+Tampilkan status (Toast, Skeleton, Empty State).
+- **Integrasi M3 (jika diminta)**: Gunakan Snackbar untuk pesan sementara. Gunakan Badges pada ikon navigasi.
+- Gunakan warna semantik secara konsisten.
+- Gunakan **Sonner** untuk toast (maks 3 sekaligus).
+- Gunakan Skeleton persis sesuai layout (jangan gunakan spinner untuk layout) guna mencegah CLS.
+- Sediakan ilustrasi dan CTA pada Empty State.
+
+#### 4: Kontainer & Layout
+Kelompokkan konten (Card, Modal, Sheet).
+- **Integrasi M3 (jika diminta)**: Gunakan varian Card M3: Elevated, Filled, Outlined. Ikuti panduan Dialog M3 untuk modal.
+- Gunakan Radix UI Dialog untuk modal (menangani focus trap dan scroll lock).
+- Animasikan kemunculan modal (fade + scale).
+- Gunakan shadow tipis untuk elevasi card di mode terang.
+- Gunakan bottom sheet di mobile.
+
+### Checklist Micro-Interaction
+- [ ] Ring `:focus-visible` (2px) pada elemen interaktif.
+- [ ] **State Layers M3**: Jika menggunakan M3, pastikan elemen interaktif memiliki lapisan status (Hover, Focus, Pressed, Dragged) yang berbeda.
+- [ ] State loading pada tombol.
+- [ ] Gunakan **Framer Motion v12 spring physics** (`stiffness: 300, damping: 20`) untuk interaksi alami.
+- [ ] Transisi hover `transition-all duration-200 ease-out`.
+- [ ] Uji kontras warna dark mode.

package/skills/ui-ux-pro-max/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: ui-ux-pro-max
 description: "Comprehensive design guide & BM25 search engine for web and mobile applications across 11 tech stacks / Panduan desain komprehensif & mesin pencari BM25 untuk aplikasi web dan mobile di 11 tech stack."
-author: "Roedy Rustam"
+author: "Roedy Rustam"
 ---
 
 # UI/UX Pro Max - Design Intelligence System
@@ -13,8 +13,11 @@ author: "Roedy Rustam"
 <a name="english"></a>
 ## English
 
+### Orchestration & Integration
+Connects and orchestrates with relevant domain skills like `brainstorming`, `zero-to-prod-orchestrator`, and `project-context-mapper` to ensure cohesive execution.
+
 ### Description
-UI/UX Pro Max is a comprehensive design intelligence engine equipped with an offline BM25 search index covering color palettes, typography, responsive patterns, icon sets, chart recommendations, UX guidelines, and stack-specific best practices across **11 technology stacks**.
+UI/UX Pro Max is a comprehensive design intelligence engine equipped with an offline BM25 search index covering color palettes, typography, responsive patterns, icon sets, chart recommendations, UX guidelines, **Material Design 3 (M3)**, and stack-specific best practices across **11 technology stacks**.
 
 ### Trigger Conditions
 Reference these guidelines or run the CLI search engine when:
@@ -55,6 +58,7 @@ python scripts/search.py "<query>" --domain <domain> --max-results 3
   - `icons`: Icon usage guidance, SVG libraries (Lucide, Heroicons), and code imports
   - `react`: React & Next.js performance optimizations, re-render fixes & dynamic imports
   - `web`: Web interface guidelines (ARIA, focus traps, virtual list, form inputs)
+  - `m3`: Material Design 3 specific design tokens, color roles, elevation, and component specs
 
 *Example:* `python scripts/search.py "fintech dark theme" --domain color`
 
@@ -92,6 +96,7 @@ python scripts/search.py "<query>" --stack <stack> --max-results 3
 - **Dark Mode**: High contrast foreground elements over dark slate/gray backgrounds; avoid pure black `#000000` text containers unless requested.
 
 #### 5. Dashboard & Information Hierarchy
+- **Material Design 3 (M3) Integration**: Follow M3 Layouts (compact, medium, expanded). Use M3 elevation for layering instead of heavy borders.
 - **Layout Flow**: KPI summary cards top -> Trend charts middle -> Detailed data tables bottom.
 - **Visual Grid**: Consistent gaps/padding (16px / 24px). Clean subtle borders instead of heavy black dividers.
 - **Data Viz**: Maximum 3–5 coordinated colors in graphs. Responsive tooltips and legend alignment.
@@ -110,8 +115,11 @@ python scripts/search.py "<query>" --stack <stack> --max-results 3
 <a name="bahasa-indonesia"></a>
 ## Bahasa Indonesia
 
+### Integrasi Orkestrasi
+Terhubung dan mengorkestrasi skill domain yang relevan seperti `brainstorming`, `zero-to-prod-orchestrator`, dan `project-context-mapper` untuk memastikan eksekusi yang kohesif.
+
 ### Deskripsi
-UI/UX Pro Max adalah mesin kecerdasan desain komprehensif yang dilengkapi indeks pencarian BM25 offline. Mencakup palet warna, tipografi, pola tata letak responsif, rekomendasi ikon, grafik visualisasi data, pedoman UX, serta praktik terbaik untuk **11 tumpukan teknologi (technology stacks)**.
+UI/UX Pro Max adalah mesin kecerdasan desain komprehensif yang dilengkapi indeks pencarian BM25 offline. Mencakup palet warna, tipografi, pola tata letak responsif, rekomendasi ikon, grafik visualisasi data, pedoman UX, **Material Design 3 (M3)**, serta praktik terbaik untuk **11 tumpukan teknologi (technology stacks)**.
 
 ### Kondisi Pemicu
 Gunakan pedoman ini atau jalankan mesin pencari CLI ketika:
@@ -151,6 +159,7 @@ python scripts/search.py "<kueri>" --domain <domain> --max-results 3
   - `icons`: Panduan penggunaan ikon, pustaka SVG (Lucide, Heroicons), & import kode
   - `react`: Optimasi performa React & Next.js, perbaikan re-render & dynamic import
   - `web`: Pedoman antarmuka web (ARIA, focus trap, virtual list, input form)
+  - `m3`: Token desain spesifik Material Design 3, peran warna, elevasi, dan spesifikasi komponen
 
 *Contoh:* `python scripts/search.py "fintech dark theme" --domain color`
 
@@ -188,6 +197,7 @@ python scripts/search.py "<kueri>" --stack <stack> --max-results 3
 - **Mode Gelap**: Kontras tinggi antara elemen latar depan dengan latar belakang gelap; hindari kontainer teks serba hitam pekat `#000000` kecuali diminta khusus.
 
 #### 5. Dashboard & Hierarki Informasi
+- **Integrasi Material Design 3 (M3)**: Ikuti tata letak M3 (compact, medium, expanded). Gunakan elevasi M3 untuk pelapisan alih-alih border tebal.
 - **Alur Tata Letak**: Kartu ringkasan KPI di atas -> Grafik tren di tengah -> Tabel detail data di bawah.
 - **Grid Visual**: Konsistensi gap/padding (16px / 24px). Gunakan border halus daripada pembatas tebal hitam.
 - **Visualisasi Data**: Maksimal 3–5 warna terkoordinasi dalam grafik. Tooltip responsif & perataan legenda yang rapi.
@@ -200,3 +210,13 @@ python scripts/search.py "<kueri>" --stack <stack> --max-results 3
 - [ ] **Kontras**: Rasio kontras teks minimal 4.5:1 pada mode terang. Border terlihat di kedua mode (terang & gelap).
 - [ ] **Tata Letak & Responsif**: Diuji pada breakpoint 375px, 768px, 1024px, 1440px. Tidak ada scroll horizontal tak disengaja pada perangkat mobile.
 - [ ] **Aksesibilitas**: Semua gambar memiliki `alt` text yang bermakna. Form input memiliki `<label>` terhubung atau `aria-label`.
+
+---
+### 🎨 Automatic Visual Assets Generation Mandate (CRITICAL)
+**MANDATORY**: Whenever you are building a new application, scaffolding a project, or finalizing the initial UI/UX, you MUST automatically use the `generate_image` tool to create a custom logo that perfectly matches the application's core concept and aesthetic. 
+This generated image MUST be explicitly used as:
+1. The primary application logo (e.g., in the header/navbar).
+2. The website favicon (`favicon.ico` or equivalent).
+3. The Open Graph (OG) image for SEO metadata (`og:image`).
+
+Do not use placeholders for these assets. Generate and integrate them automatically.