vibes-plug 2.5.0 → 2.14.1

package/skills/design-system-architect/SKILL.md

@@ -1,260 +1,309 @@
----
-name: design-system-architect
-description: "Expert guide for designing, building, and maintaining scalable UI design systems with design tokens, headless primitives (Radix/Base UI), Tailwind v4 @theme, and WCAG 2.2 accessibility in English and Indonesian."
-author: vibes-plug-swarm
----
-
-# Design System Architect (2026 Edition — shadcn/ui Registry)
-
-[English](#english) | [Bahasa Indonesia](#bahasa-indonesia)
-
----
-
-<a name="english"></a>
-## English
-
-### Description
-Expert guide for building and maintaining scalable UI design systems. Covers design tokens with OKLCH and Tailwind v4 `@theme`, headless component primitives (Radix UI, **Base UI 1.x**), **shadcn/ui registry** for distributable component libraries, CVA for type-safe variants, and WCAG 2.2 accessibility compliance.
-
-### Trigger Conditions
-- Building a shared UI component library from scratch.
-- Setting up design tokens (colors, typography, spacing) with Tailwind v4.
-- Using headless primitives (Radix UI, Base UI 1.x) with custom styling.
-- Distributing components via the **shadcn/ui registry** format.
-- Auditing a component library for WCAG 2.2 accessibility compliance.
-
-### Design Token Foundation (Tailwind v4 + OKLCH)
-
-```css
-/* packages/ui/src/tokens.css */
-@import "tailwindcss";
-
-@theme {
-  /* --- Color System (OKLCH for wide-gamut P3 displays) --- */
-  /* Brand */
-  --color-brand-50:  oklch(97% 0.015 250);
-  --color-brand-100: oklch(93% 0.04  250);
-  --color-brand-500: oklch(55% 0.22  250);
-  --color-brand-700: oklch(40% 0.18  250);
-  --color-brand-900: oklch(20% 0.10  250);
-
-  /* Semantic (maps to brand in light/dark automatically) */
-  --color-primary:     var(--color-brand-500);
-  --color-primary-fg:  oklch(100% 0 0);        /* White */
-  --color-surface:     oklch(100% 0 0);        /* White */
-  --color-surface-2:   oklch(97% 0.005 250);
-  --color-border:      oklch(90% 0.01  250);
-  --color-text:        oklch(15% 0.02  250);
-  --color-text-muted:  oklch(50% 0.015 250);
-  --color-destructive: oklch(55% 0.22  25);    /* Red */
-
-  /* --- Fluid Typography (clamp) --- */
-  --font-sans: "Inter Variable", "Inter", ui-sans-serif, system-ui, sans-serif;
-  --font-mono: "JetBrains Mono", "Fira Code", ui-monospace, monospace;
-  --font-size-xs:   clamp(0.7rem, 0.17vi + 0.66rem, 0.75rem);
-  --font-size-sm:   clamp(0.8rem, 0.17vi + 0.76rem, 0.875rem);
-  --font-size-base: clamp(0.9rem, 0.17vi + 0.86rem, 1rem);
-  --font-size-lg:   clamp(1rem, 0.17vi + 0.96rem, 1.125rem);
-  --font-size-xl:   clamp(1.1rem, 0.34vi + 1.02rem, 1.25rem);
-  --font-size-2xl:  clamp(1.2rem, 0.69vi + 1.03rem, 1.5rem);
-  --font-size-3xl:  clamp(1.5rem, 0.86vi + 1.29rem, 1.875rem);
-  --font-size-4xl:  clamp(1.8rem, 1.03vi + 1.54rem, 2.25rem);
-
-  /* --- Spacing & Radius --- */
-  --radius-sm:  0.25rem;
-  --radius-md:  0.5rem;
-  --radius-lg:  0.75rem;
-  --radius-xl:  1rem;
-  --radius-full: 9999px;
-
-  /* --- Animation --- */
-  --animate-fade-in:   fade-in   0.2s ease-out;
-  --animate-slide-up:  slide-up  0.3s cubic-bezier(0.16, 1, 0.3, 1);
-  --animate-scale-in:  scale-in  0.2s ease-out;
-}
-
-/* Dark mode tokens */
-@variant dark {
-  :root {
-    --color-surface:    oklch(10% 0.015 250);
-    --color-surface-2:  oklch(15% 0.015 250);
-    --color-border:     oklch(25% 0.02  250);
-    --color-text:       oklch(95% 0.005 250);
-    --color-text-muted: oklch(60% 0.01  250);
-  }
-}
-```
-
-### Component Architecture
-
-#### Headless + Styled Pattern (Base UI 1.x / Radix UI)
-Use headless primitives for accessibility, apply styles via Tailwind + CVA:
-
-```typescript
-// packages/ui/src/button.tsx
-import * as React from 'react';
-import { cva, type VariantProps } from 'class-variance-authority';
-import { cn } from '@/lib/utils';
-
-const buttonVariants = cva(
-  // Base styles
-  'inline-flex items-center justify-center gap-2 rounded-md font-medium transition-all focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-brand-500 focus-visible:ring-offset-2 disabled:pointer-events-none disabled:opacity-50 select-none',
-  {
-    variants: {
-      variant: {
-        default:     'bg-primary text-primary-fg shadow-sm hover:brightness-110 active:brightness-90',
-        secondary:   'bg-surface-2 text-text border border-border hover:bg-surface hover:border-brand-300',
-        destructive: 'bg-destructive text-white hover:brightness-110',
-        ghost:       'hover:bg-surface-2 text-text',
-        link:        'text-primary underline-offset-4 hover:underline p-0 h-auto',
-      },
-      size: {
-        sm:   'h-8  px-3 text-xs',
-        md:   'h-9  px-4 text-sm',
-        lg:   'h-11 px-6 text-base',
-        icon: 'h-9  w-9',
-      },
-    },
-    defaultVariants: { variant: 'default', size: 'md' },
-  }
-);
-
-export interface ButtonProps
-  extends React.ButtonHTMLAttributes<HTMLButtonElement>,
-    VariantProps<typeof buttonVariants> {
-  asChild?: boolean;
-}
-
-const Button = React.forwardRef<HTMLButtonElement, ButtonProps>(
-  ({ className, variant, size, ...props }, ref) => (
-    <button
-      ref={ref}
-      className={cn(buttonVariants({ variant, size }), className)}
-      {...props}
-    />
-  )
-);
-Button.displayName = 'Button';
-
-export { Button, buttonVariants };
-```
-
-### Component Layout (Container Queries over Media Queries)
-Avoid `@media` queries for internal component styling. Use **CSS Container Queries (`@container`)** so components respond to their wrapper, not the viewport. This makes components truly reusable anywhere.
-```tsx
-// Example of a container-aware component using Tailwind v4
-<div className="@container">
-  <div className="flex flex-col @md:flex-row gap-4">
-    <div className="p-4 bg-surface rounded-xl">Fluid Card</div>
-  </div>
-</div>
-```
-
-### shadcn/ui Registry — Distributable Components (2026)
-
-shadcn/ui v2 introduces a **registry** system — distribute your components as a shareable library that others can `npx shadcn add` into their projects:
-
-```json
-// registry.json — defines your component library
-{
-  "$schema": "https://ui.shadcn.com/schema/registry.json",
-  "name": "my-ui",
-  "homepage": "https://ui.myapp.com",
-  "items": [
-    {
-      "name": "button",
-      "type": "registry:ui",
-      "title": "Button",
-      "description": "Multi-variant button component with CVA",
-      "files": [
-        { "path": "registry/ui/button.tsx", "type": "registry:ui" }
-      ],
-      "tailwind": {
-        "config": {
-          "theme": {
-            "extend": {
-              "colors": { "primary": "hsl(var(--primary))" }
-            }
-          }
-        }
-      }
-    }
-  ]
-}
-```
-
-```bash
-# Users install your components directly
-npx shadcn add https://ui.myapp.com/registry.json button
-npx shadcn add https://ui.myapp.com/registry.json card dialog
-```
-
-### Base UI 1.x — Unstyled Accessibility Primitives
-Base UI (from MUI team) is the 2026 alternative to Radix UI with React 19 native support:
-```typescript
-import { Dialog, Button, Select } from '@base-ui-components/react';
-
-// Fully unstyled — apply any className/Tailwind styles
-<Dialog.Root>
-  <Dialog.Trigger render={<Button />}>Open Dialog</Dialog.Trigger>
-  <Dialog.Portal>
-    <Dialog.Backdrop className="fixed inset-0 bg-black/50 animate-fade-in" />
-    <Dialog.Popup className="fixed inset-0 m-auto h-fit max-w-md rounded-xl bg-surface p-6 shadow-xl animate-slide-up">
-      <Dialog.Title className="text-lg font-semibold">Title</Dialog.Title>
-      <Dialog.Close className="absolute right-4 top-4">✕</Dialog.Close>
-    </Dialog.Popup>
-  </Dialog.Portal>
-</Dialog.Root>
-```
-
-### WCAG 2.2 Accessibility Checklist
-- [ ] All interactive elements have visible focus indicators (`ring-2`).
-- [ ] Color contrast ≥ 4.5:1 (text), ≥ 3:1 (large text / UI components).
-- [ ] All images have `alt` text; decorative images have `alt=""`.
-- [ ] All form inputs have associated `<label>` elements.
-- [ ] Keyboard navigation works for all interactions (Tab, Enter, Space, Escape, Arrow keys).
-- [ ] `aria-label` or `aria-labelledby` on icon buttons.
-- [ ] Modals trap focus and restore it on close.
-- [ ] No content relies on color alone to convey information.
-- [ ] Touch targets ≥ 24×24px (WCAG 2.2 new requirement).
-
----
-
-<a name="bahasa-indonesia"></a>
-## Bahasa Indonesia
-
-### Deskripsi
-Panduan ahli untuk membangun dan memelihara design system UI yang skalabel. Mencakup design token dengan OKLCH dan `@theme` Tailwind v4, primitif komponen headless (Radix UI, **Base UI 1.x**), **registry shadcn/ui** untuk distribusi library komponen, CVA untuk varian type-safe, dan kepatuhan aksesibilitas WCAG 2.2.
-
-### Kondisi Pemicu
-- Membangun library komponen UI bersama dari awal.
-- Menyiapkan design token (warna, tipografi, spacing) dengan Tailwind v4.
-- Menggunakan primitif headless (Radix UI, Base UI 1.x) dengan styling kustom.
-- Mendistribusikan komponen via format **registry shadcn/ui**.
-- Mengaudit library komponen untuk kepatuhan aksesibilitas WCAG 2.2.
-
-### Fondasi Design Token (Tailwind v4 + OKLCH)
-Definisikan semua token di CSS menggunakan direktif `@theme`. Gunakan warna OKLCH untuk tampilan P3 wide-gamut. Definisikan token semantik (`--color-primary`, `--color-surface`, `--color-border`) yang secara otomatis beradaptasi antara mode terang/gelap melalui `@variant dark`.
-
-### Arsitektur Komponen
-Gunakan pola Headless + Styled: primitif headless (Base UI/Radix) untuk aksesibilitas, gaya melalui Tailwind + CVA (class-variance-authority) untuk varian type-safe.
-
-**Container Queries (`@container`)**: DILARANG keras menggunakan `@media` query (misal `md:`, `lg:`) untuk layout di dalam sebuah komponen. Gunakan **Container Queries (`@md:`, `@lg:`)** agar komponen dapat menyesuaikan diri dengan lebar pembungkusnya, bukan lebar layar secara keseluruhan. Ini membuat komponen Anda 100% *reusable*.
-
-### Registry shadcn/ui — Komponen yang Dapat Didistribusikan (2026)
-shadcn/ui v2 memperkenalkan sistem registry — distribusikan komponen Anda sebagai library yang dapat dibagikan sehingga orang lain dapat menginstalnya dengan `npx shadcn add [url] [komponen]`.
-
-### Base UI 1.x — Primitif Aksesibilitas Tanpa Gaya
-Base UI (dari tim MUI) adalah alternatif Radix UI untuk 2026 dengan dukungan native React 19. Sepenuhnya tanpa gaya — terapkan className/Tailwind apapun.
-
-### Checklist Aksesibilitas WCAG 2.2
-- Semua elemen interaktif memiliki indikator fokus yang terlihat.
-- Kontras warna ≥ 4.5:1 (teks), ≥ 3:1 (komponen UI).
-- Semua input form memiliki elemen `<label>` terkait.
-- Navigasi keyboard berfungsi untuk semua interaksi.
-- Modal menjebak fokus dan memulihkannya saat ditutup.
-- Target sentuh ≥ 24×24px (persyaratan baru WCAG 2.2).
-
-
-## Orchestration & Integration
-- Integrates with frontend orchestrators, Tailwind v4, Base UI, and shadcn/ui.
+---
+name: design-system-architect
+description: "Expert guide for designing, building, and maintaining scalable UI design systems with design tokens, headless primitives, Material Design 3 (M3), Tailwind v4 @theme, and WCAG 2.2 accessibility."
+author: "Roedy Rustam"
+---
+
+# Design System Architect (2026 Edition — shadcn/ui Registry)
+
+[English](#english) | [Bahasa Indonesia](#bahasa-indonesia)
+
+---
+
+<a name="english"></a>
+## English
+
+### Description
+Expert guide for building and maintaining scalable UI design systems. Covers design tokens with OKLCH and Tailwind v4 `@theme`, **Material Design 3 (M3)** integration, headless component primitives (Radix UI, **Base UI 1.x**), **shadcn/ui registry** for distributable component libraries, CVA for type-safe variants, and WCAG 2.2 accessibility compliance.
+
+### Trigger Conditions
+- Building a shared UI component library from scratch.
+- Setting up design tokens (colors, typography, spacing) with Tailwind v4.
+- Applying Material Design 3 (M3) principles (https://m3.material.io/).
+- Using headless primitives (Radix UI, Base UI 1.x) with custom styling.
+- Distributing components via the **shadcn/ui registry** format.
+- Auditing a component library for WCAG 2.2 accessibility compliance.
+
+### Design Token Foundation (Tailwind v4 + OKLCH)
+
+```css
+/* packages/ui/src/tokens.css */
+@import "tailwindcss";
+
+@theme {
+  /* --- Color System (OKLCH for wide-gamut P3 displays) --- */
+  /* Brand */
+  --color-brand-50:  oklch(97% 0.015 250);
+  --color-brand-100: oklch(93% 0.04  250);
+  --color-brand-500: oklch(55% 0.22  250);
+  --color-brand-700: oklch(40% 0.18  250);
+  --color-brand-900: oklch(20% 0.10  250);
+
+  /* Semantic (maps to brand in light/dark automatically) */
+  --color-primary:     var(--color-brand-500);
+  --color-primary-fg:  oklch(100% 0 0);        /* White */
+  --color-surface:     oklch(100% 0 0);        /* White */
+  --color-surface-2:   oklch(97% 0.005 250);
+  --color-border:      oklch(90% 0.01  250);
+  --color-text:        oklch(15% 0.02  250);
+  --color-text-muted:  oklch(50% 0.015 250);
+  --color-destructive: oklch(55% 0.22  25);    /* Red */
+
+  /* --- Fluid Typography (clamp) --- */
+  --font-sans: "Inter Variable", "Inter", ui-sans-serif, system-ui, sans-serif;
+  --font-mono: "JetBrains Mono", "Fira Code", ui-monospace, monospace;
+  --font-size-xs:   clamp(0.7rem, 0.17vi + 0.66rem, 0.75rem);
+  --font-size-sm:   clamp(0.8rem, 0.17vi + 0.76rem, 0.875rem);
+  --font-size-base: clamp(0.9rem, 0.17vi + 0.86rem, 1rem);
+  --font-size-lg:   clamp(1rem, 0.17vi + 0.96rem, 1.125rem);
+  --font-size-xl:   clamp(1.1rem, 0.34vi + 1.02rem, 1.25rem);
+  --font-size-2xl:  clamp(1.2rem, 0.69vi + 1.03rem, 1.5rem);
+  --font-size-3xl:  clamp(1.5rem, 0.86vi + 1.29rem, 1.875rem);
+  --font-size-4xl:  clamp(1.8rem, 1.03vi + 1.54rem, 2.25rem);
+
+  /* --- Spacing & Radius --- */
+  --radius-sm:  0.25rem;
+  --radius-md:  0.5rem;
+  --radius-lg:  0.75rem;
+  --radius-xl:  1rem;
+  --radius-full: 9999px;
+
+  /* --- Animation --- */
+  --animate-fade-in:   fade-in   0.2s ease-out;
+  --animate-slide-up:  slide-up  0.3s cubic-bezier(0.16, 1, 0.3, 1);
+  --animate-scale-in:  scale-in  0.2s ease-out;
+}
+
+/* Dark mode tokens */
+@variant dark {
+  :root {
+    --color-surface:    oklch(10% 0.015 250);
+    --color-surface-2:  oklch(15% 0.015 250);
+    --color-border:     oklch(25% 0.02  250);
+    --color-text:       oklch(95% 0.005 250);
+    --color-text-muted: oklch(60% 0.01  250);
+  }
+}
+```
+
+### Material Design 3 (M3) Integration
+When requested to follow **Material Design 3 (https://m3.material.io/)**, implement the following M3 token principles in your design system:
+1. **Color Roles**: Map Tailwind colors to M3 roles (`Primary`, `Secondary`, `Tertiary`, `Error`, `Surface`, `Outline`). Implement `On-*` colors for text/icons on top of those roles, and `*-Container` / `On-*-Container` for lower emphasis. Support Dynamic Color if applicable.
+2. **Typography Scale**: Use M3 naming conventions: `Display`, `Headline`, `Title`, `Body`, `Label` (each with `Large`, `Medium`, `Small` sizes).
+3. **Elevation & Surface**: Use M3 Elevation levels (0 to 5) implemented via subtle shadows and surface tint colors, not just heavy drop shadows.
+4. **Shapes**: Map `--radius-*` to M3 shape families: `None`, `Extra Small`, `Small`, `Medium`, `Large`, `Extra Large`, `Full`.
+
+### Component Architecture
+
+#### Headless + Styled Pattern (Base UI 1.x / Radix UI)
+Use headless primitives for accessibility, apply styles via Tailwind + CVA:
+
+```typescript
+// packages/ui/src/button.tsx
+import * as React from 'react';
+import { cva, type VariantProps } from 'class-variance-authority';
+import { cn } from '@/lib/utils';
+
+const buttonVariants = cva(
+  // Base styles
+  'inline-flex items-center justify-center gap-2 rounded-md font-medium transition-all focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-brand-500 focus-visible:ring-offset-2 disabled:pointer-events-none disabled:opacity-50 select-none',
+  {
+    variants: {
+      variant: {
+        default:     'bg-primary text-primary-fg shadow-sm hover:brightness-110 active:brightness-90',
+        secondary:   'bg-surface-2 text-text border border-border hover:bg-surface hover:border-brand-300',
+        destructive: 'bg-destructive text-white hover:brightness-110',
+        ghost:       'hover:bg-surface-2 text-text',
+        link:        'text-primary underline-offset-4 hover:underline p-0 h-auto',
+      },
+      size: {
+        sm:   'h-8  px-3 text-xs',
+        md:   'h-9  px-4 text-sm',
+        lg:   'h-11 px-6 text-base',
+        icon: 'h-9  w-9',
+      },
+    },
+    defaultVariants: { variant: 'default', size: 'md' },
+  }
+);
+
+export interface ButtonProps
+  extends React.ButtonHTMLAttributes<HTMLButtonElement>,
+    VariantProps<typeof buttonVariants> {
+  asChild?: boolean;
+}
+
+const Button = React.forwardRef<HTMLButtonElement, ButtonProps>(
+  ({ className, variant, size, ...props }, ref) => (
+    <button
+      ref={ref}
+      className={cn(buttonVariants({ variant, size }), className)}
+      {...props}
+    />
+  )
+);
+Button.displayName = 'Button';
+
+export { Button, buttonVariants };
+```
+
+### Component Layout (Container Queries over Media Queries)
+Avoid `@media` queries for internal component styling. Use **CSS Container Queries (`@container`)** so components respond to their wrapper, not the viewport. This makes components truly reusable anywhere.
+```tsx
+// Example of a container-aware component using Tailwind v4
+<div className="@container">
+  <div className="flex flex-col @md:flex-row gap-4">
+    <div className="p-4 bg-surface rounded-xl">Fluid Card</div>
+  </div>
+</div>
+```
+
+### shadcn/ui Registry — Distributable Components (2026)
+
+shadcn/ui v2 introduces a **registry** system — distribute your components as a shareable library that others can `npx shadcn add` into their projects:
+
+```json
+// registry.json — defines your component library
+{
+  "$schema": "https://ui.shadcn.com/schema/registry.json",
+  "name": "my-ui",
+  "homepage": "https://ui.myapp.com",
+  "items": [
+    {
+      "name": "button",
+      "type": "registry:ui",
+      "title": "Button",
+      "description": "Multi-variant button component with CVA",
+      "files": [
+        { "path": "registry/ui/button.tsx", "type": "registry:ui" }
+      ],
+      "tailwind": {
+        "config": {
+          "theme": {
+            "extend": {
+              "colors": { "primary": "hsl(var(--primary))" }
+            }
+          }
+        }
+      }
+    }
+  ]
+}
+```
+
+```bash
+# Users install your components directly
+npx shadcn add https://ui.myapp.com/registry.json button
+npx shadcn add https://ui.myapp.com/registry.json card dialog
+```
+
+### Base UI 1.x — Unstyled Accessibility Primitives
+Base UI (from MUI team) is the 2026 alternative to Radix UI with React 19 native support:
+```typescript
+import { Dialog, Button, Select } from '@base-ui-components/react';
+
+// Fully unstyled — apply any className/Tailwind styles
+<Dialog.Root>
+  <Dialog.Trigger render={<Button />}>Open Dialog</Dialog.Trigger>
+  <Dialog.Portal>
+    <Dialog.Backdrop className="fixed inset-0 bg-black/50 animate-fade-in" />
+    <Dialog.Popup className="fixed inset-0 m-auto h-fit max-w-md rounded-xl bg-surface p-6 shadow-xl animate-slide-up">
+      <Dialog.Title className="text-lg font-semibold">Title</Dialog.Title>
+      <Dialog.Close className="absolute right-4 top-4">✕</Dialog.Close>
+    </Dialog.Popup>
+  </Dialog.Portal>
+</Dialog.Root>
+```
+
+### The 4 Pillars of UI Components Catalog
+
+#### 1. Input Controls (Buttons, Inputs, Selects)
+- **Visual States**: Explicitly define `default`, `hover`, `active`, `focus`, `disabled`, and `error`.
+- **Validation**: Display inline validation on blur using `aria-invalid` and `aria-describedby` (React Hook Form + Zod).
+- **Touch Targets**: Minimum 44×44px (WCAG 2.5.8), M3 recommends 48×48px.
+- **M3 Integration**: Use M3 button tiers (Filled, Tonal, Elevated, Outlined, Text) and FABs for primary actions.
+
+#### 2. Navigation (Navbars, Tabs, Command Palettes)
+- **Command Palette**: Add `⌘K` command menu via `cmdk`.
+- **Responsive Layout**: Bottom nav (<768px), collapsible rail (tablet), full sidebar (desktop).
+- **Smooth Page Transitions**: In Next.js 15, leverage `<Link viewTransition>` for layout morphing.
+- **Active State**: Clear high-contrast indicator with `role="navigation"` and `aria-current="page"`.
+
+#### 3. Information & Feedback (Toasts, Skeletons, Empty States)
+- **Toasts**: Use **Sonner**; cap at max 3 concurrent visible toasts. Auto-dismiss success, keep errors persistent.
+- **Loading UX**: Use layout-matching Skeletons over spinners to eliminate Cumulative Layout Shift (CLS).
+- **Empty States**: Clear illustration, contextual message, and primary CTA.
+
+#### 4. Containers & Layout (Cards, Modals, Sheets)
+- **Modals & Dialogs**: Radix UI / Base UI Dialog with automatic focus trapping and background scroll lock.
+- **Sheets / Drawers**: Bottom sheet for mobile secondary actions; side sheet on desktop.
+- **Cards**: Flat border or subtle shadow (`shadow-sm`); avoid heavy drop shadows in light mode.
+
+### WCAG 2.2 Accessibility Checklist
+- [ ] All interactive elements have visible focus indicators (`ring-2`).
+- [ ] Color contrast ≥ 4.5:1 (text), ≥ 3:1 (large text / UI components).
+- [ ] All images have `alt` text; decorative images have `alt=""`.
+- [ ] All form inputs have associated `<label>` elements.
+- [ ] Keyboard navigation works for all interactions (Tab, Enter, Space, Escape, Arrow keys).
+- [ ] `aria-label` or `aria-labelledby` on icon buttons.
+- [ ] Modals trap focus and restore it on close.
+- [ ] No content relies on color alone to convey information.
+- [ ] Touch targets ≥ 24×24px (WCAG 2.2 new requirement).
+
+---
+
+<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
+Panduan ahli untuk membangun dan memelihara design system UI yang skalabel. Mencakup design token dengan OKLCH dan `@theme` Tailwind v4, primitif komponen headless (Radix UI, **Base UI 1.x**), **registry shadcn/ui** untuk distribusi library komponen, CVA untuk varian type-safe, dan kepatuhan aksesibilitas WCAG 2.2.
+
+### Kondisi Pemicu
+- Membangun library komponen UI bersama dari awal.
+- Menyiapkan design token (warna, tipografi, spacing) dengan Tailwind v4.
+- Menerapkan prinsip Material Design 3 (M3) (https://m3.material.io/).
+- Menggunakan primitif headless (Radix UI, Base UI 1.x) dengan styling kustom.
+- Mendistribusikan komponen via format **registry shadcn/ui**.
+- Mengaudit library komponen untuk kepatuhan aksesibilitas WCAG 2.2.
+
+### Fondasi Design Token (Tailwind v4 + OKLCH)
+Definisikan semua token di CSS menggunakan direktif `@theme`. Gunakan warna OKLCH untuk tampilan P3 wide-gamut. Definisikan token semantik (`--color-primary`, `--color-surface`, `--color-border`) yang secara otomatis beradaptasi antara mode terang/gelap melalui `@variant dark`.
+
+### Integrasi Material Design 3 (M3)
+Jika diminta mengikuti **Material Design 3 (https://m3.material.io/)**, terapkan prinsip token M3 berikut:
+1. **Peran Warna (Color Roles)**: Petakan warna ke peran M3 (`Primary`, `Secondary`, `Tertiary`, `Error`, `Surface`, `Outline`). Gunakan warna `On-*` untuk teks di atasnya, dan `*-Container` / `On-*-Container` untuk penekanan lebih rendah.
+2. **Skala Tipografi**: Gunakan penamaan M3: `Display`, `Headline`, `Title`, `Body`, `Label` (dengan ukuran `Large`, `Medium`, `Small`).
+3. **Elevasi & Permukaan**: Gunakan tingkat Elevasi M3 (0 hingga 5) melalui bayangan halus dan warna tint permukaan (surface tint).
+4. **Bentuk (Shapes)**: Petakan `--radius-*` ke keluarga bentuk M3: `None`, `Extra Small`, `Small`, `Medium`, `Large`, `Extra Large`, `Full`.
+
+### Arsitektur Komponen
+Gunakan pola Headless + Styled: primitif headless (Base UI/Radix) untuk aksesibilitas, gaya melalui Tailwind + CVA (class-variance-authority) untuk varian type-safe.
+
+**Container Queries (`@container`)**: DILARANG keras menggunakan `@media` query (misal `md:`, `lg:`) untuk layout di dalam sebuah komponen. Gunakan **Container Queries (`@md:`, `@lg:`)** agar komponen dapat menyesuaikan diri dengan lebar pembungkusnya, bukan lebar layar secara keseluruhan. Ini membuat komponen Anda 100% *reusable*.
+
+### Registry shadcn/ui — Komponen yang Dapat Didistribusikan (2026)
+shadcn/ui v2 memperkenalkan sistem registry — distribusikan komponen Anda sebagai library yang dapat dibagikan sehingga orang lain dapat menginstalnya dengan `npx shadcn add [url] [komponen]`.
+
+### Base UI 1.x — Primitif Aksesibilitas Tanpa Gaya
+Base UI (dari tim MUI) adalah alternatif Radix UI untuk 2026 dengan dukungan native React 19. Sepenuhnya tanpa gaya — terapkan className/Tailwind apapun.
+
+### Katalog 4 Pilar Komponen UI
+1. **Input Controls (Tombol, Input, Select)**: Definisikan status visual (`default`, `hover`, `active`, `focus`, `disabled`, `error`). Tampilkan validasi inline on-blur (`aria-invalid`, `aria-describedby` via React Hook Form + Zod). Target sentuh minimal 44x44px.
+2. **Navigasi (Navbar, Tab, Command Palette)**: Sediakan menu perintah `⌘K` dengan `cmdk`. Layout responsif (navigasi bawah di mobile, rail di tablet, sidebar penuh di desktop). Transisi halaman halus via `<Link viewTransition>` di Next.js 15.
+3. **Informasi & Feedback (Toast, Skeleton, Empty State)**: Gunakan **Sonner** untuk toast (maksimal 3 bersamaan). Gunakan Skeleton sesuai tata letak untuk mencegah CLS dibanding spinner.
+4. **Wadah & Layout (Card, Modal, Sheet)**: Dialog/Modal dengan penguncian scroll dan focus trapping otomatis (Base UI/Radix). Gunakan bottom sheet di mobile dan side sheet di desktop.
+
+### Checklist Aksesibilitas WCAG 2.2
+- Semua elemen interaktif memiliki indikator fokus yang terlihat.
+- Kontras warna ≥ 4.5:1 (teks), ≥ 3:1 (komponen UI).
+- Semua input form memiliki elemen `<label>` terkait.
+- Navigasi keyboard berfungsi untuk semua interaksi.
+- Modal menjebak fokus dan memulihkannya saat ditutup.
+- Target sentuh ≥ 24×24px (persyaratan baru WCAG 2.2).
+
+
+## Orchestration & Integration
+- Integrates with frontend orchestrators, Tailwind v4, Base UI, and shadcn/ui.