ui-mirror-skill 1.0.0

package/skill/references/component-catalog.md

@@ -0,0 +1,758 @@
+# UI Mirror: Component Catalog (Reference Example)
+
+> **NOTE**: This catalog contains reference shadcn/ui component implementations as comparison baselines.
+> When using this skill, read the actual component source files from the current project.
+> Each entry includes a typical implementation, key CSS properties for comparison, and migration override templates.
+
+---
+
+## 1. Card
+
+### shadcn/ui Reference
+
+```tsx
+// src/components/ui/card.tsx
+import { cn } from "@/lib/utils"
+
+function Card({ className, ...props }: React.ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="card"
+      className={cn(
+        "bg-card text-card-foreground flex flex-col gap-2 rounded-lg border shadow-sm",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function CardHeader({ className, ...props }: React.ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="card-header"
+      className={cn(
+        "@container/card-header grid auto-rows-min grid-rows-[auto_auto] items-start gap-2 px-4 pt-4 has-data-[slot=card-action]:grid-cols-[1fr_auto] [.border-b]:pb-4",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function CardTitle({ className, ...props }: React.ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="card-title"
+      className={cn("leading-none font-semibold", className)}
+      {...props}
+    />
+  )
+}
+
+function CardDescription({ className, ...props }: React.ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="card-description"
+      className={cn("text-muted-foreground text-sm", className)}
+      {...props}
+    />
+  )
+}
+
+function CardContent({ className, ...props }: React.ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="card-content"
+      className={cn("px-4 pb-4", className)}
+      {...props}
+    />
+  )
+}
+
+function CardFooter({ className, ...props }: React.ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="card-footer"
+      className={cn("flex items-center px-4 pb-4 [.border-t]:pt-4", className)}
+      {...props}
+    />
+  )
+}
+```
+
+### Key CSS Properties for Comparison
+
+| Property | Default Value | What to Compare |
+|----------|-------------|-----------------|
+| `background` | `bg-card` (white) | Surface color |
+| `border` | `border` (1px solid --border) | Border presence and color |
+| `border-radius` | `rounded-lg` (--radius = 6px) | Corner rounding |
+| `box-shadow` | `shadow-sm` | Shadow depth |
+| `padding` (header) | `px-4 pt-4` (16px sides, 16px top) | Internal spacing |
+| `padding` (content) | `px-4 pb-4` (16px sides, 16px bottom) | Internal spacing |
+| `gap` (internal) | `gap-2` (8px) | Vertical spacing between sub-elements |
+| `color` | `text-card-foreground` (near-black) | Text color |
+
+### Migration Override Template
+
+```css
+/* Override card styling to match benchmark */
+@layer components {
+  [data-slot="card"] {
+    --card-radius: {{benchmark_radius}};
+    --card-shadow: {{benchmark_shadow}};
+    --card-border: {{benchmark_border}};
+    border-radius: var(--card-radius);
+    box-shadow: var(--card-shadow);
+    border: var(--card-border);
+  }
+  [data-slot="card-header"] {
+    padding: {{benchmark_header_padding}};
+  }
+  [data-slot="card-content"] {
+    padding: {{benchmark_content_padding}};
+  }
+}
+```
+
+---
+
+## 2. Button
+
+### shadcn/ui Reference
+
+```tsx
+// src/components/ui/button.tsx
+import { cva, type VariantProps } from "class-variance-authority"
+import { cn } from "@/lib/utils"
+
+const buttonVariants = cva(
+  "inline-flex items-center justify-center gap-2 whitespace-nowrap rounded-md text-sm font-medium transition-all disabled:pointer-events-none disabled:opacity-50 [&_svg]:pointer-events-none [&_svg:not([class*='size-'])]:size-4 shrink-0 [&_svg]:shrink-0 outline-none focus-visible:border-ring focus-visible:ring-ring/50 focus-visible:ring-[3px] aria-invalid:ring-destructive/20 aria-invalid:border-destructive",
+  {
+    variants: {
+      variant: {
+        default:
+          "bg-primary text-primary-foreground shadow-md shadow-primary/20 hover:bg-primary/90",
+        destructive:
+          "bg-destructive text-white hover:bg-destructive/90 focus-visible:ring-destructive/20",
+        outline:
+          "border bg-background shadow-xs hover:bg-accent hover:text-accent-foreground",
+        secondary:
+          "bg-secondary text-secondary-foreground hover:bg-secondary/80",
+        ghost:
+          "hover:bg-accent hover:text-accent-foreground",
+        link:
+          "text-primary underline-offset-4 hover:underline",
+      },
+      size: {
+        default: "h-9 px-4 py-2 has-[>svg]:px-3",
+        xs: "h-6 gap-1 rounded-md px-2 text-xs has-[>svg]:px-1.5 [&_svg:not([class*='size-'])]:size-3",
+        sm: "h-8 rounded-md gap-1.5 px-3 has-[>svg]:px-2.5",
+        lg: "h-10 rounded-md px-6 has-[>svg]:px-4",
+        icon: "size-9",
+        "icon-xs": "size-6 rounded-md [&_svg:not([class*='size-'])]:size-3",
+        "icon-sm": "size-8",
+        "icon-lg": "size-10",
+      },
+    },
+    defaultVariants: {
+      variant: "default",
+      size: "default",
+    },
+  }
+)
+```
+
+### Key CSS Properties for Comparison
+
+| Variant | Property | Default Value |
+|---------|----------|-------------|
+| **Base** | `border-radius` | `rounded-md` (~4px) |
+| **Base** | `font-size` | `text-sm` (14px) |
+| **Base** | `font-weight` | `font-medium` (500) |
+| **Base** | `height` | `h-9` (36px) |
+| **Base** | `padding` | `px-4 py-2` |
+| **Base** | `transition` | `transition-all` |
+| **Base** | `focus ring` | `ring-ring/50 ring-[3px]` |
+| **default** | `background` | `bg-primary` (#6866F1) |
+| **default** | `color` | `text-primary-foreground` (white) |
+| **default** | `box-shadow` | `shadow-md shadow-primary/20` |
+| **default** | `hover` | `bg-primary/90` |
+| **destructive** | `background` | `bg-destructive` (red) |
+| **outline** | `border` | `border` (1px) |
+| **outline** | `background` | `bg-background` |
+| **outline** | `box-shadow` | `shadow-xs` |
+| **secondary** | `background` | `bg-secondary` |
+| **ghost** | `background` | transparent |
+| **ghost** | `hover` | `bg-accent` |
+
+### Size Variants
+
+| Size | Height | Padding | Icon Size |
+|------|--------|---------|-----------|
+| `xs` | 24px (h-6) | px-2 | size-3 (12px) |
+| `sm` | 32px (h-8) | px-3 | size-4 (16px) |
+| `default` | 36px (h-9) | px-4 | size-4 (16px) |
+| `lg` | 40px (h-10) | px-6 | size-4 (16px) |
+| `icon` | 36px (size-9) | -- | size-4 |
+| `icon-xs` | 24px (size-6) | -- | size-3 |
+| `icon-sm` | 32px (size-8) | -- | size-4 |
+| `icon-lg` | 40px (size-10) | -- | size-4 |
+
+### Migration Override Template
+
+```css
+@layer components {
+  [data-slot="button"] {
+    border-radius: {{benchmark_radius}};
+    font-size: {{benchmark_font_size}};
+    font-weight: {{benchmark_font_weight}};
+  }
+  [data-slot="button"][data-variant="default"] {
+    box-shadow: {{benchmark_shadow}};
+  }
+  [data-slot="button"][data-size="default"] {
+    height: {{benchmark_height}};
+    padding-inline: {{benchmark_padding_x}};
+  }
+}
+```
+
+---
+
+## 3. Input
+
+### shadcn/ui Reference
+
+```tsx
+// src/components/ui/input.tsx
+function Input({ className, type, ...props }: React.ComponentProps<"input">) {
+  return (
+    <input
+      type={type}
+      data-slot="input"
+      className={cn(
+        "file:text-foreground placeholder:text-muted-foreground selection:bg-primary selection:text-primary-foreground border-input h-9 w-full min-w-0 rounded-md border bg-transparent px-3 py-1 text-base shadow-sm transition-[color,box-shadow] outline-none file:inline-flex file:h-7 file:border-0 file:bg-transparent file:text-sm file:font-medium disabled:pointer-events-none disabled:cursor-not-allowed disabled:opacity-50 md:text-sm",
+        "focus-visible:border-ring focus-visible:ring-ring/50 focus-visible:ring-[3px]",
+        "aria-invalid:ring-destructive/20 aria-invalid:border-destructive",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+```
+
+### Key CSS Properties for Comparison
+
+| Property | Default Value |
+|----------|-------------|
+| `height` | `h-9` (36px) |
+| `border-radius` | `rounded-md` (~4px) |
+| `border` | `border-input` (1px solid) |
+| `box-shadow` | `shadow-sm` |
+| `padding` | `px-3 py-1` |
+| `font-size` | `text-base` (16px mobile) / `md:text-sm` (14px desktop) |
+| `background` | `bg-transparent` |
+| `placeholder` | `text-muted-foreground` |
+| `focus` | `border-ring` + `ring-ring/50 ring-[3px]` |
+| `disabled` | `opacity-50` + `pointer-events-none` |
+| `error` | `ring-destructive/20` + `border-destructive` |
+
+### Migration Override Template
+
+```css
+@layer components {
+  [data-slot="input"] {
+    height: {{benchmark_height}};
+    border-radius: {{benchmark_radius}};
+    border-color: {{benchmark_border_color}};
+    box-shadow: {{benchmark_shadow}};
+    padding: {{benchmark_padding}};
+    font-size: {{benchmark_font_size}};
+    background: {{benchmark_bg}};
+  }
+  [data-slot="input"]:focus-visible {
+    border-color: {{benchmark_focus_border}};
+    box-shadow: {{benchmark_focus_shadow}};
+  }
+}
+```
+
+---
+
+## 4. Badge
+
+### shadcn/ui Reference
+
+```tsx
+// src/components/ui/badge.tsx
+const badgeVariants = cva(
+  "inline-flex items-center justify-center rounded-full border border-transparent px-2 py-0.5 text-xs font-medium w-fit whitespace-nowrap shrink-0 [&>svg]:size-3 gap-1 [&>svg]:pointer-events-none focus-visible:border-ring focus-visible:ring-ring/50 focus-visible:ring-[3px] aria-invalid:ring-destructive/20 aria-invalid:border-destructive transition-[color,box-shadow] overflow-hidden",
+  {
+    variants: {
+      variant: {
+        default: "bg-primary text-primary-foreground [a&]:hover:bg-primary/90",
+        secondary: "bg-secondary text-secondary-foreground [a&]:hover:bg-secondary/90",
+        destructive: "bg-destructive text-white [a&]:hover:bg-destructive/90 focus-visible:ring-destructive/20",
+        outline: "border-border text-foreground [a&]:hover:bg-accent [a&]:hover:text-accent-foreground",
+        ghost: "[a&]:hover:bg-accent [a&]:hover:text-accent-foreground",
+        link: "text-primary underline-offset-4 [a&]:hover:underline",
+      },
+    },
+    defaultVariants: { variant: "default" },
+  }
+)
+```
+
+### Key CSS Properties for Comparison
+
+| Property | Default Value |
+|----------|-------------|
+| `border-radius` | `rounded-full` (pill shape) |
+| `padding` | `px-2 py-0.5` |
+| `font-size` | `text-xs` (12px) |
+| `font-weight` | `font-medium` (500) |
+| `border` | `border border-transparent` (default) / `border-border` (outline) |
+| `icon size` | `size-3` (12px) |
+| `gap` | `gap-1` (4px) |
+
+### Variants Summary
+
+| Variant | Background | Text | Border |
+|---------|-----------|------|--------|
+| `default` | `bg-primary` | `text-primary-foreground` | transparent |
+| `secondary` | `bg-secondary` | `text-secondary-foreground` | transparent |
+| `destructive` | `bg-destructive` | `text-white` | transparent |
+| `outline` | transparent | `text-foreground` | `border-border` |
+| `ghost` | transparent | inherit | transparent |
+| `link` | transparent | `text-primary` | transparent |
+
+### Migration Override Template
+
+```css
+@layer components {
+  [data-slot="badge"] {
+    border-radius: {{benchmark_radius}};
+    padding: {{benchmark_padding}};
+    font-size: {{benchmark_font_size}};
+    font-weight: {{benchmark_font_weight}};
+  }
+  [data-slot="badge"][data-variant="default"] {
+    background: {{benchmark_default_bg}};
+    color: {{benchmark_default_text}};
+  }
+}
+```
+
+---
+
+## 5. Dialog
+
+### shadcn/ui Reference
+
+```tsx
+// src/components/ui/dialog.tsx — DialogContent (key component)
+function DialogContent({ className, children, showCloseButton = true, ...props }) {
+  return (
+    <DialogPortal>
+      <DialogOverlay
+        className="data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 fixed inset-0 z-50 bg-black/50"
+      />
+      <DialogPrimitive.Content
+        data-slot="dialog-content"
+        className={cn(
+          "bg-background data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-95 fixed top-[50%] left-[50%] z-50 grid w-full max-w-[calc(100%-2rem)] translate-x-[-50%] translate-y-[-50%] gap-4 rounded-lg border p-6 shadow-lg duration-200 outline-none sm:max-w-lg",
+          className
+        )}
+        {...props}
+      >
+        {children}
+        {showCloseButton && <CloseButton />}
+      </DialogPrimitive.Content>
+    </DialogPortal>
+  )
+}
+```
+
+### Key CSS Properties for Comparison
+
+| Property | Default Value |
+|----------|-------------|
+| `background` | `bg-background` |
+| `border-radius` | `rounded-lg` (6px) |
+| `border` | `border` (1px solid --border) |
+| `box-shadow` | `shadow-lg` |
+| `padding` | `p-6` (24px) |
+| `max-width` | `max-w-[calc(100%-2rem)]` mobile / `sm:max-w-lg` (512px) desktop |
+| `gap` (internal) | `gap-4` (16px) |
+| `z-index` | `z-50` |
+| **Overlay** | `bg-black/50` (50% opacity) |
+| **Enter animation** | `zoom-in-95` + `fade-in-0` |
+| **Exit animation** | `zoom-out-95` + `fade-out-0` |
+| **Duration** | `duration-200` |
+
+### Sub-components
+
+| Slot | Key Classes |
+|------|------------|
+| `dialog-header` | `flex flex-col gap-2 text-center sm:text-left` |
+| `dialog-footer` | `flex flex-col-reverse gap-2 sm:flex-row sm:justify-end` |
+| `dialog-title` | `text-lg leading-none font-semibold` |
+| `dialog-description` | `text-muted-foreground text-sm` |
+
+### Migration Override Template
+
+```css
+@layer components {
+  [data-slot="dialog-overlay"] {
+    background: {{benchmark_overlay_color}};
+  }
+  [data-slot="dialog-content"] {
+    border-radius: {{benchmark_radius}};
+    box-shadow: {{benchmark_shadow}};
+    padding: {{benchmark_padding}};
+    max-width: {{benchmark_max_width}};
+  }
+  [data-slot="dialog-title"] {
+    font-size: {{benchmark_title_size}};
+    font-weight: {{benchmark_title_weight}};
+  }
+}
+```
+
+---
+
+## 6. Navigation (Sidebar)
+
+### shadcn/ui Reference
+
+```tsx
+// src/components/ui/sidebar.tsx — key constants and patterns
+const SIDEBAR_WIDTH = "16rem"       // 256px
+const SIDEBAR_WIDTH_MOBILE = "18rem" // 288px
+const SIDEBAR_WIDTH_ICON = "3rem"    // 48px collapsed
+
+// SidebarMenuButton CVA
+const sidebarMenuButtonVariants = cva(
+  "peer/menu-button flex w-full items-center gap-2 overflow-hidden rounded-md p-2 text-left text-sm outline-none ring-sidebar-ring transition-[width,height,padding] hover:bg-sidebar-accent hover:text-sidebar-accent-foreground focus-visible:ring-2 active:bg-sidebar-accent active:text-sidebar-accent-foreground disabled:pointer-events-none disabled:opacity-50 data-[active=true]:bg-sidebar-accent data-[active=true]:font-medium data-[active=true]:text-sidebar-accent-foreground ...",
+  {
+    variants: {
+      variant: {
+        default: "hover:bg-sidebar-accent hover:text-sidebar-accent-foreground",
+        outline: "bg-background shadow-[0_0_0_1px_hsl(var(--sidebar-border))] ...",
+      },
+      size: {
+        default: "h-8 text-sm",
+        sm: "h-7 text-xs",
+        lg: "h-12 text-sm group-data-[collapsible=icon]:!p-0",
+      },
+    },
+  }
+)
+```
+
+### Key CSS Properties for Comparison
+
+| Property | Default Value |
+|----------|-------------|
+| `width` | 16rem (256px) desktop, 18rem mobile |
+| `background` | `bg-sidebar` (white) |
+| `position` | `fixed inset-y-0` (desktop), Sheet (mobile) |
+| `border` | `border-r` (left sidebar) |
+| **Menu item** | |
+| `height` | `h-8` (32px) default |
+| `padding` | `p-2` (8px) |
+| `border-radius` | `rounded-md` |
+| `font-size` | `text-sm` (14px) |
+| `hover` | `bg-sidebar-accent text-sidebar-accent-foreground` |
+| `active` | `bg-sidebar-accent font-medium` |
+| `icon size` | `size-4` (16px) |
+| `gap` | `gap-2` (8px) |
+
+### Structure
+
+```
+SidebarProvider
+  Sidebar (side="left" | "right", variant="sidebar" | "floating" | "inset")
+    SidebarHeader
+    SidebarContent
+      SidebarGroup
+        SidebarGroupLabel
+        SidebarGroupContent
+          SidebarMenu
+            SidebarMenuItem
+              SidebarMenuButton (isActive, tooltip)
+              SidebarMenuAction (showOnHover)
+              SidebarMenuBadge
+            SidebarMenuSub
+              SidebarMenuSubItem
+                SidebarMenuSubButton
+    SidebarFooter
+    SidebarRail
+  SidebarInset (main content area)
+```
+
+### Migration Override Template
+
+```css
+@layer components {
+  [data-sidebar="sidebar"] {
+    background: {{benchmark_sidebar_bg}};
+    width: {{benchmark_sidebar_width}};
+  }
+  [data-sidebar="menu-button"] {
+    height: {{benchmark_item_height}};
+    padding: {{benchmark_item_padding}};
+    border-radius: {{benchmark_item_radius}};
+    font-size: {{benchmark_item_font_size}};
+  }
+  [data-sidebar="menu-button"]:hover {
+    background: {{benchmark_item_hover_bg}};
+  }
+  [data-sidebar="menu-button"][data-active="true"] {
+    background: {{benchmark_item_active_bg}};
+    font-weight: {{benchmark_item_active_weight}};
+  }
+}
+```
+
+---
+
+## 7. Table
+
+### shadcn/ui Reference
+
+```tsx
+// src/components/ui/table.tsx
+function Table({ className, ...props }) {
+  return (
+    <div data-slot="table-container" className="relative w-full overflow-x-auto">
+      <table data-slot="table" className={cn("w-full caption-bottom text-sm", className)} {...props} />
+    </div>
+  )
+}
+
+function TableRow({ className, ...props }) {
+  return (
+    <tr
+      data-slot="table-row"
+      className={cn("hover:bg-muted/50 data-[state=selected]:bg-muted border-b transition-colors", className)}
+      {...props}
+    />
+  )
+}
+
+function TableHead({ className, ...props }) {
+  return (
+    <th
+      data-slot="table-head"
+      className={cn("text-foreground h-10 px-2 text-left align-middle font-medium whitespace-nowrap ...", className)}
+      {...props}
+    />
+  )
+}
+
+function TableCell({ className, ...props }) {
+  return (
+    <td
+      data-slot="table-cell"
+      className={cn("p-2 align-middle whitespace-nowrap ...", className)}
+      {...props}
+    />
+  )
+}
+```
+
+### Key CSS Properties for Comparison
+
+| Property | Default Value |
+|----------|-------------|
+| `font-size` | `text-sm` (14px) |
+| **Header** | |
+| `height` | `h-10` (40px) |
+| `padding` | `px-2` (8px horizontal) |
+| `font-weight` | `font-medium` (500) |
+| `color` | `text-foreground` |
+| `border` | `border-b` (via `[&_tr]:border-b` on thead) |
+| **Row** | |
+| `border` | `border-b` |
+| `hover` | `bg-muted/50` |
+| `selected` | `bg-muted` (via `data-[state=selected]`) |
+| `transition` | `transition-colors` |
+| **Cell** | |
+| `padding` | `p-2` (8px) |
+| `vertical-align` | `align-middle` |
+| `white-space` | `whitespace-nowrap` |
+| **Footer** | |
+| `background` | `bg-muted/50` |
+| `border` | `border-t` |
+
+### Migration Override Template
+
+```css
+@layer components {
+  [data-slot="table"] {
+    font-size: {{benchmark_font_size}};
+  }
+  [data-slot="table-head"] {
+    height: {{benchmark_head_height}};
+    padding: {{benchmark_head_padding}};
+    font-weight: {{benchmark_head_weight}};
+    background: {{benchmark_head_bg}};
+  }
+  [data-slot="table-row"]:hover {
+    background: {{benchmark_row_hover_bg}};
+  }
+  [data-slot="table-cell"] {
+    padding: {{benchmark_cell_padding}};
+  }
+}
+```
+
+---
+
+## 8. Form (react-hook-form + zod)
+
+### Typical Pattern
+
+```tsx
+// Typical form structure in a shadcn/ui project
+import { useForm } from "react-hook-form"
+import { zodResolver } from "@hookform/resolvers/zod"
+import { z } from "zod"
+import { Input } from "@/components/ui/input"
+import { Button } from "@/components/ui/button"
+import { Label } from "@/components/ui/label"
+
+const schema = z.object({
+  name: z.string().min(1, "Required"),
+  email: z.string().email("Invalid email"),
+})
+
+function MyForm() {
+  const form = useForm({
+    resolver: zodResolver(schema),
+    defaultValues: { name: "", email: "" },
+  })
+
+  return (
+    <form onSubmit={form.handleSubmit(onSubmit)} className="flex flex-col gap-4">
+      <div className="flex flex-col gap-2">
+        <Label htmlFor="name">Name</Label>
+        <Input
+          id="name"
+          {...form.register("name")}
+          aria-invalid={!!form.formState.errors.name}
+        />
+        {form.formState.errors.name && (
+          <p className="text-sm text-destructive">
+            {form.formState.errors.name.message}
+          </p>
+        )}
+      </div>
+      <Button type="submit" loading={form.formState.isSubmitting}>
+        Submit
+      </Button>
+    </form>
+  )
+}
+```
+
+### Key CSS Properties for Comparison
+
+| Element | Default Value |
+|---------|-------------|
+| Form gap | `gap-4` (16px) between fields |
+| Field gap | `gap-2` (8px) between label and input |
+| Label | `text-sm font-medium` (via Label component) |
+| Error text | `text-sm text-destructive` |
+| Error input | `aria-invalid` -> `ring-destructive/20 border-destructive` |
+| Submit button | Full-width or auto, `loading` prop for spinner |
+
+### Migration Override Template
+
+```css
+@layer components {
+  form [data-slot="label"] {
+    font-size: {{benchmark_label_size}};
+    font-weight: {{benchmark_label_weight}};
+    color: {{benchmark_label_color}};
+  }
+  form .text-destructive {
+    font-size: {{benchmark_error_size}};
+    color: {{benchmark_error_color}};
+  }
+}
+```
+
+---
+
+## General Migration Override Generation Strategy
+
+### Step 1: Identify Differences
+For each component, compare the benchmark's CSS against the project values listed above. Note every property that differs.
+
+### Step 2: Classify Each Difference
+
+| Classification | Action | Example |
+|---------------|--------|---------|
+| **Token-level** | Override CSS custom property in `:root` | `--primary` hue change |
+| **Component-level** | Add `@layer components` override using `data-slot` selectors | Card `border-radius` |
+| **Variant-level** | Add new CVA variant or modify existing | New button variant |
+| **Layout-level** | Structural JSX change required | Different sidebar pattern |
+
+### Step 3: Generate Override File
+
+```css
+/* {{benchmark-name}}-overrides.css */
+/* Import after globals.css, before component styles */
+
+/* Token overrides */
+:root {
+  /* Only override tokens that differ */
+  --primary: {{new_oklch_value}};
+  --radius: {{new_radius}};
+  /* ... */
+}
+
+/* Component overrides via data-slot selectors */
+@layer components {
+  [data-slot="card"] { /* ... */ }
+  [data-slot="button"] { /* ... */ }
+  [data-slot="input"] { /* ... */ }
+  [data-slot="badge"] { /* ... */ }
+  [data-slot="dialog-content"] { /* ... */ }
+  [data-slot="table-head"] { /* ... */ }
+}
+```
+
+### Step 4: Validate Against Design Rules
+
+Before applying any override, check it against design system rules rules:
+
+| Check | Rule | What Could Break |
+|-------|------|-----------------|
+| No hardcoded HEX | C1 | Use OKLCH in token overrides |
+| No dark mode | C2 | Skip any dark-mode tokens from benchmark |
+| Radius limit | R4 | Cannot use `rounded-xl` or above |
+| Shadow hierarchy | SH1-SH4 | Must maintain shadow depth ordering |
+| No framer-motion | A1 | Cannot adopt benchmark's animation library if it uses FM |
+| `data-slot` required | AC4 | All overridden components must keep `data-slot` |
+
+### Step 5: Scope the Override (optional)
+
+To apply benchmark styling only to specific sections:
+
+```css
+/* Scoped to a specific route or wrapper */
+[data-theme="{{benchmark-slug}}"] {
+  --primary: {{value}};
+  --radius: {{value}};
+}
+
+[data-theme="{{benchmark-slug}}"] [data-slot="card"] {
+  /* Component overrides within scope */
+}
+```