vibes-plug 1.0.0 → 2.11.0

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

@@ -1,63 +1,166 @@
----
-name: ui-components-expert
-description: Expert guide for checking and improving the 4 main pillars of UI components: input controls, navigation, information, and containers. / Panduan ahli untuk memeriksa dan meningkatkan 4 pilar utama komponen UI: kontrol input, navigasi, informasi, dan kontainer.
----
-
-# 🎨 UI Components 4 Pillars Expert
-
-Skill ini memberikan panduan komprehensif untuk mengevaluasi, mengaudit, dan meningkatkan 4 pilar utama komponen User Interface (UI). Tujuannya adalah memastikan setiap komponen tidak hanya terlihat indah secara visual (Aesthetics), tetapi juga berfungsi secara intuitif (Usability), dapat diakses oleh semua pengguna (Accessibility/a11y), dan konsisten dengan sistem desain.
-
-## 🎯 4 Pilar Utama Komponen UI
-
-### 1. Kontrol Input (Input Controls)
-Komponen yang memungkinkan pengguna berinteraksi dan memasukkan data.
-*Contoh: Buttons, Checkboxes, Radio Buttons, Text Fields, Toggles/Switches, Dropdowns.*
-
-**✅ Checklist & Best Practices:**
-- **State Visual yang Jelas:** Pastikan ada perbedaan visual yang jelas untuk state `Default`, `Hover`, `Active/Pressed`, `Focus` (untuk aksesibilitas keyboard), dan `Disabled`.
-- **Ukuran Target Sentuh (Touch Target):** Minimal 44x44 pixel (berdasarkan standar HIG/Material) untuk kenyamanan pengguna mobile.
-- **Feedback Langsung:** Berikan umpan balik instan saat input berinteraksi (misalnya riak/ripple effect, perubahan warna, animasi transisi).
-- **Validasi & Error Handling:** Tampilkan pesan error yang spesifik dan inline pada form input, gunakan warna merah dan ikon peringatan, jangan hanya mengandalkan warna.
-- **Aksesibilitas (a11y):** Gunakan tag label yang terhubung ke input (misal `htmlFor`), sertakan atribut `aria-invalid` jika ada error.
-
-### 2. Navigasi (Navigation)
-Komponen yang membantu pengguna bergerak di dalam struktur aplikasi atau situs web.
-*Contoh: Menus, Tabs, Breadcrumbs, Pagination, Sidebars, Bottom Navigation.*
-
-**✅ Checklist & Best Practices:**
-- **Indikasi Lokasi Saat Ini (Active State):** Pengguna harus selalu tahu di mana mereka berada. Highlight menu atau tab yang sedang aktif dengan warna kontras, garis bawah, atau background tebal.
-- **Hierarki yang Logis:** Kelompokkan item navigasi berdasarkan kepentingannya. Jangan tampilkan terlalu banyak opsi (prinsip Hick's Law).
-- **Responsivitas:** Gunakan *Hamburger Menu* atau *Bottom Navigation* di perangkat mobile, pertahankan tab yang bisa digeser (swipeable/scrollable).
-- **Breadcrumbs:** Gunakan breadcrumbs untuk hierarki yang lebih dalam dari 2 level agar pengguna bisa dengan mudah kembali ke halaman induk.
-
-### 3. Informasi (Information)
-Komponen yang menyampaikan status, panduan, atau peringatan kepada pengguna.
-*Contoh: Notifications (Toasts), Tooltips, Badges, Alerts, Progress Bars, Spinners.*
-
-**✅ Checklist & Best Practices:**
-- **Pewarnaan Kontekstual:** Gunakan warna standar untuk status: Hijau (Sukses), Merah (Error), Kuning/Oranye (Peringatan), Biru (Informasi).
-- **Kemudahan Menutup (Dismissibility):** Berikan opsi (tombol X) untuk menutup notifikasi persisten. Untuk toast notifikasi sukses/info, berikan *auto-dismiss* (misalnya setelah 3-5 detik).
-- **Tooltips:** Hanya muncul saat di-*hover* (desktop) atau ditekan lama (mobile). Jangan gunakan tooltips untuk informasi kritis yang wajib dibaca, gunakan teks bantuan inline.
-- **Animasi Transisi:** Notifikasi harus muncul dan menghilang dengan animasi yang halus (slide in/out, fade in/out) agar tidak mengejutkan pengguna.
-
-### 4. Kontainer (Containers)
-Komponen yang mengelompokkan konten terkait menjadi unit visual yang terstruktur.
-*Contoh: Cards, Modals (Dialogs), Accordions, Drawers/Bottom Sheets, Carousels.*
-
-**✅ Checklist & Best Practices:**
-- **Visual Hierarchy & Depth:** Gunakan *Drop Shadows* atau batas tipis (borders) untuk membedakan kontainer dari background utama. Bedakan elevasi (z-index) antara Card biasa dan Modal yang melayang.
-- **Fokus Manajemen pada Modal:** Saat modal terbuka, background harus digelapkan (overlay/backdrop), *scroll* halaman di belakang harus dikunci (body `overflow: hidden`), dan fokus keyboard harus "terperangkap" (trap focus) di dalam modal. Bisa ditutup dengan tombol Escape (ESC) atau mengklik di luar area modal (backdrop click).
-- **Padding dan Whitespace:** Berikan ruang bernapas (padding) yang cukup di dalam kontainer. Hindari teks atau elemen yang terlalu menempel pada tepi *Card*.
-- **Clear Call to Action (CTA):** Pada Modal atau Card interaktif, pastikan tombol aksi utama (misal: "Simpan", "Beli") jelas dan ditempatkan secara logis (biasanya di kanan bawah atau bawah tengah).
-
-## 🛠 Panduan Penggunaan Skill
-
-Ketika Anda diminta untuk memeriksa atau meningkatkan UI aplikasi:
-
-1. **Identifikasi Komponen:** Kategorikan setiap komponen yang ada di halaman tersebut ke dalam 4 pilar di atas.
-2. **Audit Berdasarkan Checklist:** Jalankan checklist di atas pada komponen yang sedang direview. Cari kekurangan dalam *state*, aksesibilitas, responsivitas, dan umpan balik (feedback).
-3. **Usulkan Peningkatan Konkret:**
-   - **Perbaikan CSS/Tailwind:** Usulkan penambahan class seperti `focus:ring-2 focus:outline-none`, `hover:bg-gray-100`, atau transisi yang mulus `transition-colors duration-200`.
-   - **Peningkatan Aksesibilitas (a11y):** Berikan kode ARIA role atau atribut pendukung.
-   - **Interaksi JavaScript (opsional):** Jika diperlukan untuk modal atau tab, usulkan struktur state yang menangkap interaksi pengguna dengan benar.
-4. **Fokus pada Detail "Micro-interactions":** Peningkatan kecil pada *hover state* atau animasi *toast* berdampak besar pada impresi kualitas UI.
+---
+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/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.