diff --git a/CHANGELOG.md b/CHANGELOG.md
index 4d159fd..e032a01 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -2,6 +2,52 @@
 
 ## Unreleased
 
+The vendored `@aestheticfunction/dspack-gen/core` bundle moves from the
+v0.1.2 release tag (`c5bfd6d`) to the v0.5.0 release tag (`5203569`), the
+current latest. **This changes what `validate-ui` rejects** — it is a
+behavior change to a published tool, not a maintenance bump:
+
+- Gate S2 now enforces sub-component **containment** (spec v0.4 §5.1): a
+  declared sub-component is valid only within its declaring compound's
+  subtree, so a `dialog-title` with no `dialog` ancestor is now a
+  vocabulary error. Previously accepted. (dspack-gen 0.3.0)
+- Gate S3 now evaluates **`requiredCategories`** on `required-composition`
+  rules (spec v0.4 §4.3), so a contract can require that a matching node
+  carry a descendant drawn from a named category. (dspack-gen 0.2.2)
+- `get-generation-context` serves a richer system prompt: each component's
+  vocabulary line now carries that component's `composition.notes` from the
+  contract, capped at two sentences. Prompt material only — no S-gate
+  changes with it. (dspack-gen 0.5.0)
+- Unchanged: `forbiddenCategories` was already evaluated at v0.1.2, and the
+  lookup tools and gate S1 are unaffected. Exactly four shipped `src/core`
+  files differ across the whole v0.1.2 -> v0.5.0 move: `lint/vocabulary.ts`
+  (S2 containment), `contract.ts` + `lint/rules.ts` (S3 requiredCategories),
+  and `compiler.ts` (the prompt change). dspack-gen 0.4.0/0.5.0's other work
+  — repair loop, casualty-free generation view, join-id view — lives in
+  `run/`, which ds-mcp does not vendor.
+
+Coupled updates that had to land in the same change:
+
+- `examples/shadcn-ui-v04.dspack.json` re-synced from the spec repo
+  (contract 2.3.0 -> 3.2.0: 8 -> 34 components, 8 -> 49 rules). It exercises
+  both new evaluations, and it is the file the quick start downloads.
+- `src/schema/dspack.v0.4.schema.json` re-synced from the spec repo, which
+  had added `requiredCategories` to `required-composition` (§4.3). Without
+  it the loader **rejected the spec's own example contract**. All four
+  schemas are now tracked in `scripts/check-sync.mjs`; v0.1-v0.3 were
+  already byte-exact.
+- The golden-context test now reads dspack-gen's contract fixture
+  (`src/tests/fixtures/shadcn.v0_4.contract.json`, newly drift-tracked)
+  instead of the shipped example. The golden is compiled from that contract,
+  and the two upstreams are no longer byte-equal — the spec repo moved to
+  3.2.0 while dspack-gen's fixture stayed at 2.3.0. The test now compares
+  compiler output against the compiler's own input, which is what it was
+  always meant to pin.
+- `rule.button-carries-text` (new in contract 3.2.0) requires a button's
+  own text, so the `textScope: subtree` fixture in
+  `generation-tools.test.ts` moves its label onto the button; the trigger
+  still carries no text of its own, which is what that test pins.
+
 - The v0.1 example `examples/shadcn-ui.dspack.json` is renamed to
   `examples/shadcn-ui-v01.dspack.json` (DX-1, D4): the old unversioned
   filename collided with the dspack repository's v0.4
diff --git a/README.md b/README.md
index 9dc5ffe..a10a886 100644
--- a/README.md
+++ b/README.md
@@ -164,16 +164,41 @@ the guarantee.
 dspack-gen is a **build-time** dependency: its `core` subpath is bundled
 into the published package (`dist/vendor/dspack-gen-core.js`) from a
 commit-pinned devDependency, so installing ds-mcp from npm pulls nothing
-from git. The default posture is **tag-pinned**: the pin is the commit of
-dspack-gen's latest release tag, so the vendored core corresponds exactly
-to a published dspack-gen version. CI watches this two ways:
-`scripts/check-core-pin.mjs` fails loudly when a newer dspack-gen release
-changes shipped `src/core` files (test files are excluded — the documented
-escape for intentional ahead-of-release pins), and the golden-context test
-byte-compares `get-generation-context` output against dspack-gen's own
-compiler golden. Updating governance semantics means re-pinning to the new
-release tag commit, `npm install`, `npm run build`, verifying the golden
-tests, and republishing ds-mcp.
+from git. The posture is **tag-pinned**: the pin is always the commit of a
+dspack-gen *release tag*, so the vendored core corresponds exactly to a
+published dspack-gen version.
+
+**Currently vendored: dspack-gen `v0.5.0`** (`5203569`), dspack-gen's
+latest release. Moving here from v0.1.2 widened what `validate-ui` rejects,
+in exactly two places. Gate S2 now enforces sub-component **containment**
+(spec v0.4 §5.1): a declared sub-component is valid only inside its
+declaring compound's subtree, so a `dialog-title` with no `dialog` ancestor
+is a vocabulary error rather than an accepted node. Gate S3 now evaluates
+**`requiredCategories`** on `required-composition` rules (§4.3), letting a
+contract require that a matching node have a descendant drawn from a named
+category. Surfaces that passed under the older core can fail under this one
+— that is the point of the move, and it is why re-pinning is a deliberate
+release step rather than an automatic follow. `forbiddenCategories` was
+already evaluated at v0.1.2 and is unchanged, as are the lookup tools.
+
+`get-generation-context` also serves a richer system prompt: from
+dspack-gen 0.5.0 each component's vocabulary line carries that component's
+`composition.notes` from the contract (capped at two sentences). Nothing
+about the S-gates changes with it — it is prompt material, and prompt
+steering is not enforcement.
+
+CI watches the vendoring three ways. `scripts/check-core-pin.mjs` fails
+loudly when a newer dspack-gen release changes shipped `src/core` files
+(test files are excluded — the documented escape for intentional
+ahead-of-release pins). `scripts/check-sync.mjs` byte-compares every copied
+artifact against its upstream, including the four dspack JSON Schemas the
+loader validates against — a stale schema copy is not cosmetic, it makes
+ds-mcp refuse contracts the spec considers valid. And the golden-context
+test byte-compares `get-generation-context` output against dspack-gen's own
+compiler golden, read against the contract dspack-gen compiled that golden
+from. Re-pinning means moving the devDependency to the new release tag
+commit, `npm install`, `npm run build`, `node scripts/check-sync.mjs
+--write`, verifying the golden tests, and republishing ds-mcp.
 
 ## Requirements
 
diff --git a/examples/shadcn-ui-v04.dspack.json b/examples/shadcn-ui-v04.dspack.json
index 6ebd8d7..1163a5f 100644
--- a/examples/shadcn-ui-v04.dspack.json
+++ b/examples/shadcn-ui-v04.dspack.json
@@ -3,7 +3,7 @@
   "dspack": "0.4",
   "name": "shadcn/ui",
   "description": "A collection of reusable components built with Radix UI and Tailwind CSS. Components are copied into your project, not installed as a dependency.",
-  "version": "2.3.0",
+  "version": "3.2.0",
   "metadata": {
     "source": "https://ui.shadcn.com",
     "license": "MIT"
@@ -171,6 +171,16 @@
             "category": "color-primitives",
             "token": "slate-950"
           }
+        },
+        "popover": {
+          "value": "hsl(0, 0%, 100%)",
+          "type": "color",
+          "description": "Surface color for floating panels (Popover, DropdownMenu, Tooltip content)."
+        },
+        "popover-foreground": {
+          "value": "hsl(222.2, 84%, 4.9%)",
+          "type": "color",
+          "description": "Text color on floating panel surfaces."
         }
       }
     },
@@ -237,12 +247,30 @@
           "type": "enum",
           "propRole": "choice",
           "values": [
-            { "value": "default", "description": "Standard button for primary page actions." },
-            { "value": "destructive", "description": "For irreversible actions like delete. Uses destructive color tokens." },
-            { "value": "outline", "description": "Bordered button for secondary actions that need clear affordance." },
-            { "value": "secondary", "description": "De-emphasized button for supplementary actions." },
-            { "value": "ghost", "description": "Minimal button for toolbar actions or inline controls. No background until hovered." },
-            { "value": "link", "description": "Renders as a text link. Use for inline navigation-like actions within prose." }
+            {
+              "value": "default",
+              "description": "Standard button for primary page actions."
+            },
+            {
+              "value": "destructive",
+              "description": "For irreversible actions like delete. Uses destructive color tokens."
+            },
+            {
+              "value": "outline",
+              "description": "Bordered button for secondary actions that need clear affordance."
+            },
+            {
+              "value": "secondary",
+              "description": "De-emphasized button for supplementary actions."
+            },
+            {
+              "value": "ghost",
+              "description": "Minimal button for toolbar actions or inline controls. No background until hovered."
+            },
+            {
+              "value": "link",
+              "description": "Renders as a text link. Use for inline navigation-like actions within prose."
+            }
           ],
           "default": "default",
           "description": "Visual treatment. Use destructive for irreversible actions, ghost for toolbar actions, link for inline text actions."
@@ -251,10 +279,22 @@
           "type": "enum",
           "propRole": "dimension",
           "values": [
-            { "value": "default", "description": "Standard size, suitable for most contexts." },
-            { "value": "sm", "description": "Compact size for dense UIs or inline actions." },
-            { "value": "lg", "description": "Large size for prominent calls to action." },
-            { "value": "icon", "description": "Square aspect ratio for icon-only buttons." }
+            {
+              "value": "default",
+              "description": "Standard size, suitable for most contexts."
+            },
+            {
+              "value": "sm",
+              "description": "Compact size for dense UIs or inline actions."
+            },
+            {
+              "value": "lg",
+              "description": "Large size for prominent calls to action."
+            },
+            {
+              "value": "icon",
+              "description": "Square aspect ratio for icon-only buttons."
+            }
           ],
           "default": "default",
           "description": "Button size. Use icon for square icon-only buttons."
@@ -275,8 +315,14 @@
       "accessibility": {
         "role": "button",
         "keyboardInteractions": [
-          { "key": "Enter", "description": "Activates the button." },
-          { "key": "Space", "description": "Activates the button." }
+          {
+            "key": "Enter",
+            "description": "Activates the button."
+          },
+          {
+            "key": "Space",
+            "description": "Activates the button."
+          }
         ],
         "labelRequirement": "required-accessible-name",
         "requiredAttributes": [
@@ -309,10 +355,28 @@
           "severity": "must"
         }
       ],
-      "tokens": ["primary", "primary-foreground", "secondary", "secondary-foreground", "destructive", "destructive-foreground", "border", "ring", "radius"],
-      "relatedComponents": ["toggle"],
-      "tags": ["interactive", "form", "action"],
-      "categories": ["interactive"]
+      "tokens": [
+        "primary",
+        "primary-foreground",
+        "secondary",
+        "secondary-foreground",
+        "destructive",
+        "destructive-foreground",
+        "border",
+        "ring",
+        "radius"
+      ],
+      "relatedComponents": [
+        "toggle"
+      ],
+      "tags": [
+        "interactive",
+        "form",
+        "action"
+      ],
+      "categories": [
+        "interactive"
+      ]
     },
     "alert-dialog": {
       "name": "Alert Dialog",
@@ -345,10 +409,22 @@
           }
         ],
         "keyboardInteractions": [
-          { "key": "Tab", "description": "Moves focus between focusable elements within the dialog. Focus is trapped inside." },
-          { "key": "Escape", "description": "Does NOT close the dialog. User must select an explicit action." },
-          { "key": "Enter", "description": "Activates the focused button." },
-          { "key": "Space", "description": "Activates the focused button." }
+          {
+            "key": "Tab",
+            "description": "Moves focus between focusable elements within the dialog. Focus is trapped inside."
+          },
+          {
+            "key": "Escape",
+            "description": "Does NOT close the dialog. User must select an explicit action."
+          },
+          {
+            "key": "Enter",
+            "description": "Activates the focused button."
+          },
+          {
+            "key": "Space",
+            "description": "Activates the focused button."
+          }
         ],
         "focusManagement": "On open, focus moves to the cancel button (least destructive action). On close, focus returns to the trigger element. Focus is trapped within the dialog while open.",
         "labelRequirement": "required-visible"
@@ -362,7 +438,9 @@
             "required": true,
             "slot": "trigger",
             "acceptsChildren": "components",
-            "categories": ["interactive"]
+            "categories": [
+              "interactive"
+            ]
           },
           {
             "id": "alert-dialog-content",
@@ -406,7 +484,9 @@
             "description": "The button that confirms the destructive action.",
             "required": true,
             "acceptsChildren": "text",
-            "categories": ["interactive"]
+            "categories": [
+              "interactive"
+            ]
           },
           {
             "id": "alert-dialog-cancel",
@@ -414,7 +494,9 @@
             "description": "The button that cancels and closes the dialog.",
             "required": true,
             "acceptsChildren": "text",
-            "categories": ["interactive"]
+            "categories": [
+              "interactive"
+            ]
           }
         ],
         "notes": "AlertDialogContent must contain AlertDialogTitle and AlertDialogDescription for accessibility. AlertDialogAction and AlertDialogCancel must appear in AlertDialogFooter. Place cancel before confirm in reading order."
@@ -436,10 +518,29 @@
           "severity": "must-not"
         }
       ],
-      "tokens": ["background", "foreground", "primary", "primary-foreground", "destructive", "destructive-foreground", "border", "radius"],
-      "relatedComponents": ["dialog", "button"],
-      "tags": ["modal", "confirmation", "destructive", "accessibility"],
-      "categories": ["overlay"]
+      "tokens": [
+        "background",
+        "foreground",
+        "primary",
+        "primary-foreground",
+        "destructive",
+        "destructive-foreground",
+        "border",
+        "radius"
+      ],
+      "relatedComponents": [
+        "dialog",
+        "button"
+      ],
+      "tags": [
+        "modal",
+        "confirmation",
+        "destructive",
+        "accessibility"
+      ],
+      "categories": [
+        "overlay"
+      ]
     },
     "dialog": {
       "name": "Dialog",
@@ -474,9 +575,18 @@
           }
         ],
         "keyboardInteractions": [
-          { "key": "Tab", "description": "Moves focus between focusable elements within the dialog. Focus is trapped inside." },
-          { "key": "Escape", "description": "Closes the dialog and returns focus to the trigger." },
-          { "key": "Enter", "description": "Activates the focused interactive element." }
+          {
+            "key": "Tab",
+            "description": "Moves focus between focusable elements within the dialog. Focus is trapped inside."
+          },
+          {
+            "key": "Escape",
+            "description": "Closes the dialog and returns focus to the trigger."
+          },
+          {
+            "key": "Enter",
+            "description": "Activates the focused interactive element."
+          }
         ],
         "focusManagement": "On open, focus moves to the first focusable element inside the dialog. On close, focus returns to the trigger element. Focus is trapped within the dialog while open.",
         "labelRequirement": "required-visible"
@@ -489,7 +599,9 @@
             "description": "The element that opens the dialog.",
             "slot": "trigger",
             "acceptsChildren": "components",
-            "categories": ["interactive"]
+            "categories": [
+              "interactive"
+            ]
           },
           {
             "id": "dialog-content",
@@ -531,7 +643,9 @@
             "name": "DialogClose",
             "description": "A button that closes the dialog.",
             "acceptsChildren": "text",
-            "categories": ["interactive"]
+            "categories": [
+              "interactive"
+            ]
           }
         ]
       },
@@ -547,10 +661,23 @@
           "severity": "must-not"
         }
       ],
-      "tokens": ["background", "foreground", "border", "radius"],
-      "relatedComponents": ["alert-dialog"],
-      "tags": ["modal", "overlay", "form"],
-      "categories": ["overlay"]
+      "tokens": [
+        "background",
+        "foreground",
+        "border",
+        "radius"
+      ],
+      "relatedComponents": [
+        "alert-dialog"
+      ],
+      "tags": [
+        "modal",
+        "overlay",
+        "form"
+      ],
+      "categories": [
+        "overlay"
+      ]
     },
     "card": {
       "name": "Card",
@@ -614,9 +741,22 @@
           "severity": "should-not"
         }
       ],
-      "tokens": ["background", "foreground", "border", "radius", "muted", "muted-foreground"],
-      "relatedComponents": ["button"],
-      "tags": ["layout", "container", "surface"]
+      "tokens": [
+        "background",
+        "foreground",
+        "border",
+        "radius",
+        "muted",
+        "muted-foreground"
+      ],
+      "relatedComponents": [
+        "button"
+      ],
+      "tags": [
+        "layout",
+        "container",
+        "surface"
+      ]
     },
     "input": {
       "name": "Input",
@@ -665,10 +805,22 @@
           "severity": "should-not"
         }
       ],
-      "tokens": ["background", "foreground", "border", "ring", "radius-sm"],
+      "tokens": [
+        "background",
+        "foreground",
+        "border",
+        "ring",
+        "radius-sm"
+      ],
       "relatedComponents": [],
-      "tags": ["form", "input", "text"],
-      "categories": ["interactive"]
+      "tags": [
+        "form",
+        "input",
+        "text"
+      ],
+      "categories": [
+        "interactive"
+      ]
     },
     "badge": {
       "name": "Badge",
@@ -681,10 +833,22 @@
           "type": "enum",
           "propRole": "choice",
           "values": [
-            { "value": "default", "description": "Standard badge for general categorization." },
-            { "value": "secondary", "description": "De-emphasized badge for supplementary metadata." },
-            { "value": "outline", "description": "Bordered badge for subtle labeling." },
-            { "value": "destructive", "description": "Indicates errors or critical status." }
+            {
+              "value": "default",
+              "description": "Standard badge for general categorization."
+            },
+            {
+              "value": "secondary",
+              "description": "De-emphasized badge for supplementary metadata."
+            },
+            {
+              "value": "outline",
+              "description": "Bordered badge for subtle labeling."
+            },
+            {
+              "value": "destructive",
+              "description": "Indicates errors or critical status."
+            }
           ],
           "default": "default",
           "description": "Visual treatment. Use destructive to indicate errors or critical status."
@@ -694,9 +858,21 @@
         "labelRequirement": "none",
         "notes": "Badge is a presentational element. If the badge conveys status that is not also communicated through surrounding text, use aria-label on the badge or ensure the status is programmatically determinable through other means."
       },
-      "tokens": ["primary", "primary-foreground", "secondary", "secondary-foreground", "destructive", "destructive-foreground", "border"],
+      "tokens": [
+        "primary",
+        "primary-foreground",
+        "secondary",
+        "secondary-foreground",
+        "destructive",
+        "destructive-foreground",
+        "border"
+      ],
       "relatedComponents": [],
-      "tags": ["display", "status", "label"]
+      "tags": [
+        "display",
+        "status",
+        "label"
+      ]
     },
     "dropdown-menu": {
       "name": "Dropdown Menu",
@@ -725,11 +901,26 @@
       "accessibility": {
         "role": "menu",
         "keyboardInteractions": [
-          { "key": "Arrow Down", "description": "Moves focus to the next menu item." },
-          { "key": "Arrow Up", "description": "Moves focus to the previous menu item." },
-          { "key": "Enter", "description": "Activates the focused menu item." },
-          { "key": "Space", "description": "Activates the focused menu item." },
-          { "key": "Escape", "description": "Closes the menu and returns focus to the trigger." }
+          {
+            "key": "Arrow Down",
+            "description": "Moves focus to the next menu item."
+          },
+          {
+            "key": "Arrow Up",
+            "description": "Moves focus to the previous menu item."
+          },
+          {
+            "key": "Enter",
+            "description": "Activates the focused menu item."
+          },
+          {
+            "key": "Space",
+            "description": "Activates the focused menu item."
+          },
+          {
+            "key": "Escape",
+            "description": "Closes the menu and returns focus to the trigger."
+          }
         ],
         "focusManagement": "On open, focus moves to the first menu item. On close, focus returns to the trigger. Arrow keys cycle through items.",
         "labelRequirement": "required-accessible-name"
@@ -743,7 +934,9 @@
             "required": true,
             "slot": "trigger",
             "acceptsChildren": "components",
-            "categories": ["interactive"]
+            "categories": [
+              "interactive"
+            ]
           },
           {
             "id": "dropdown-menu-content",
@@ -758,14 +951,18 @@
             "name": "DropdownMenuItem",
             "description": "A single actionable item in the menu.",
             "acceptsChildren": "text",
-            "categories": ["interactive"]
+            "categories": [
+              "interactive"
+            ]
           },
           {
             "id": "dropdown-menu-checkbox-item",
             "name": "DropdownMenuCheckboxItem",
             "description": "A menu item that can be toggled on/off.",
             "acceptsChildren": "text",
-            "categories": ["interactive"]
+            "categories": [
+              "interactive"
+            ]
           },
           {
             "id": "dropdown-menu-radio-group",
@@ -778,7 +975,9 @@
             "name": "DropdownMenuRadioItem",
             "description": "A radio-style menu item for single selection within a group.",
             "acceptsChildren": "text",
-            "categories": ["interactive"]
+            "categories": [
+              "interactive"
+            ]
           },
           {
             "id": "dropdown-menu-label",
@@ -809,7 +1008,9 @@
             "name": "DropdownMenuSubTrigger",
             "description": "The item that opens a sub-menu on hover or keyboard navigation.",
             "acceptsChildren": "text",
-            "categories": ["interactive"]
+            "categories": [
+              "interactive"
+            ]
           },
           {
             "id": "dropdown-menu-sub-content",
@@ -819,10 +1020,27 @@
           }
         ]
       },
-      "tokens": ["background", "foreground", "accent", "muted", "muted-foreground", "border", "radius"],
-      "relatedComponents": ["button"],
-      "tags": ["interactive", "menu", "overlay"],
-      "categories": ["interactive", "overlay"]
+      "tokens": [
+        "background",
+        "foreground",
+        "accent",
+        "muted",
+        "muted-foreground",
+        "border",
+        "radius"
+      ],
+      "relatedComponents": [
+        "button"
+      ],
+      "tags": [
+        "interactive",
+        "menu",
+        "overlay"
+      ],
+      "categories": [
+        "interactive",
+        "overlay"
+      ]
     },
     "table": {
       "name": "Table",
@@ -941,242 +1159,7736 @@
           "severity": "must"
         }
       ],
-      "tokens": ["background", "foreground", "muted", "muted-foreground", "border"],
-      "relatedComponents": ["badge", "button", "dropdown-menu"],
-      "tags": ["data", "table", "tabular", "display"]
-    }
-  },
-  "categories": {
-    "interactive": {
-      "name": "Interactive",
-      "description": "Receives pointer or keyboard activation: buttons, inputs, menu items, and trigger/action/cancel sub-components. Category-based composition rules select by this instead of enumerating ids."
-    },
-    "overlay": {
-      "name": "Overlay",
-      "description": "Renders content in a layer above the page with its own focus and dismiss semantics: dialogs, alert dialogs, dropdown menus."
-    }
-  },
-  "patterns": [
-    {
-      "id": "destructive-action-confirmation",
-      "name": "Destructive Action Confirmation",
-      "description": "A confirmation flow for actions that are irreversible or have significant consequences, using AlertDialog to require explicit user acknowledgment.",
-      "intent": "Prevent accidental data loss or irreversible state changes by requiring the user to explicitly confirm before proceeding.",
-      "context": "Use whenever an action cannot be undone: deleting a record, removing a team member, clearing form data, revoking access, or any operation the user might regret if triggered accidentally.",
-      "components": ["alert-dialog", "button"],
-      "guidance": "Use AlertDialog, not Dialog, for destructive confirmations. The trigger should clearly indicate the destructive nature of the action. Inside the AlertDialog, provide a clear title stating what will happen, a description of the consequences, and two actions: a cancel option and a confirm option. The confirm button MUST use the destructive variant. Place the cancel action before the confirm action in the footer. The description should state specifically what will be affected (e.g., 'This will permanently delete 3 projects and all associated data').",
-      "relatedPatterns": [],
-      "tags": ["confirmation", "destructive", "modal", "safety"]
-    },
-    {
-      "id": "form-field-layout",
-      "name": "Form Field Layout",
-      "description": "Standard arrangement of form controls within a Card container, providing consistent structure for data entry interfaces.",
-      "intent": "Give forms a consistent visual structure that groups related inputs, separates them from surrounding content, and provides clear hierarchy through Card sub-components.",
-      "context": "Use for settings panels, profile editors, checkout flows, or any interface where the user enters structured data across multiple fields.",
-      "components": ["card", "input", "button"],
-      "guidance": "Wrap the form in a Card. Use CardHeader with CardTitle and CardDescription to introduce the form's purpose. Place inputs inside CardContent with consistent vertical spacing (space-y-4 or equivalent). Group related fields together. Place primary actions (submit, save) in CardFooter. Labels should be associated with inputs for accessibility. Required fields should be visually indicated.",
-      "relatedPatterns": ["destructive-action-confirmation"],
-      "tags": ["form", "layout", "data-entry"]
-    },
-    {
-      "id": "contextual-actions-menu",
-      "name": "Contextual Actions Menu",
-      "description": "A pattern for exposing a set of context-sensitive actions through a dropdown menu triggered by an icon button.",
-      "intent": "Keep interfaces clean by collecting secondary or overflow actions behind a single trigger, while maintaining discoverability through a familiar interaction pattern.",
-      "context": "Use for row-level actions in tables or lists, overflow menus in toolbars, or any place where multiple actions apply to a single item but showing all of them inline would be visually noisy.",
-      "components": ["dropdown-menu", "button"],
-      "guidance": "Use a Button with the ghost variant and icon size as the DropdownMenuTrigger. A vertical ellipsis icon is the conventional trigger for contextual menus. Group related actions with DropdownMenuGroup and separate groups with DropdownMenuSeparator. Place destructive actions (delete, remove) at the end of the menu, visually distinguished. Include keyboard shortcuts in DropdownMenuItem when available.",
-      "relatedPatterns": ["destructive-action-confirmation"],
-      "tags": ["actions", "menu", "overflow"]
-    },
-    {
-      "id": "data-table-with-row-actions",
-      "name": "Data Table with Row Actions",
-      "description": "An enterprise data table that presents records with a sortable header, a status column, and a trailing column of per-row actions — including destructive ones routed through a confirmation. Composes the Table primitives with Badge for status, a DropdownMenu (via the contextual-actions-menu pattern) for the actions column, and AlertDialog (via the destructive-action-confirmation pattern) for destructive actions.",
-      "intent": "Let users scan and act on a list of records — reviewing each row's status and reaching its actions — without sacrificing the semantics, keyboard access, or safety guarantees that the underlying components provide.",
-      "context": "Use for access-management and administrative surfaces: a members table, a users-and-roles list, an API-keys table, or any view where each row is an entity with a status and a set of actions, some of which (remove, revoke access) are destructive.",
-      "components": ["table", "badge", "button", "dropdown-menu", "alert-dialog"],
-      "guidance": "Build the table from the Table primitives: a TableHeader row of TableHead cells, a TableBody of one TableRow per record, and a TableCaption (or aria-label) naming the table. Make sortable columns real controls — render a ghost Button inside the TableHead and set aria-sort on that TableHead to ascending, descending, or none, with only one column sorted at a time. Render the status column with a Badge whose variant reflects state (for example default or secondary for active and pending, destructive for suspended or revoked); because Badge is presentational, keep the status readable as text so it is announced by assistive technology, not conveyed by color alone. Put per-row actions in a trailing TableCell as a contextual-actions-menu: a ghost icon Button (a vertical ellipsis) as the DropdownMenuTrigger opening a DropdownMenu of actions, with an aria-label on the trigger. Route every destructive row action — remove, revoke access — through the destructive-action-confirmation pattern using AlertDialog, never Dialog, so the action cannot be dismissed by accident; the AlertDialogDescription should name the specific record affected (for example 'This revokes Jordan Lee's access to the Acme workspace'). Do not make the entire TableRow a single clickable target while it also contains its own action controls — that is the nested-interactive-elements anti-pattern, which produces ambiguous click targets and unpredictable behavior for keyboard and screen-reader users; if rows need a primary navigation, expose it as a distinct link or cell control rather than wrapping the row.",
-      "relatedPatterns": ["contextual-actions-menu", "destructive-action-confirmation"],
-      "tags": ["table", "data", "actions", "access-management", "destructive"]
-    }
-  ],
-  "antiPatterns": [
-    {
-      "id": "dialog-for-destructive-actions",
-      "name": "Using Dialog for Destructive Confirmations",
-      "description": "Using the dismissible Dialog component instead of AlertDialog when confirming a destructive or irreversible action.",
-      "reason": "Dialog can be dismissed by clicking the overlay or pressing Escape, which means a user can accidentally bypass the confirmation without making a conscious choice. AlertDialog forces the user to select an explicit action (confirm or cancel), providing a stronger safeguard against accidental destructive operations. This distinction also matters for accessibility: screen readers announce AlertDialog with greater urgency.",
-      "severity": "must-not",
-      "insteadUse": "destructive-action-confirmation",
-      "components": ["dialog", "alert-dialog"],
-      "tags": ["modal", "destructive", "accessibility"]
-    },
-    {
-      "id": "nested-interactive-elements",
-      "name": "Nesting Interactive Elements",
-      "description": "Placing a clickable or focusable element (Button, Link, Input) inside another clickable element (a clickable Card, a Button, or a Link).",
-      "reason": "Nested interactive elements create ambiguous click targets and are a significant accessibility violation. Screen readers cannot determine user intent when interactive elements are nested, and the resulting behavior varies unpredictably across browsers. The outer element may intercept clicks intended for the inner element, or both may fire, leading to unexpected navigation or duplicate actions.",
-      "severity": "must-not",
-      "components": ["button", "card", "input"],
-      "tags": ["accessibility", "interaction", "html-semantics"]
-    },
-    {
-      "id": "div-as-button",
-      "name": "Using a Styled Div as a Button",
-      "description": "Creating a clickable element by adding an onClick handler and visual styles to a <div> or <span> instead of using the Button component or a native <button> element.",
-      "reason": "A styled div lacks keyboard accessibility (not focusable by default, does not respond to Enter or Space), is not announced as a button by screen readers, and does not participate in form submission. The Button component handles all of these concerns. Using a div requires manually re-implementing focus management, keyboard handling, and ARIA attributes — work that is error-prone and already solved by the component.",
-      "severity": "must-not",
-      "components": ["button"],
-      "tags": ["accessibility", "semantics", "component-misuse"]
-    }
-  ],
-  "intents": [
-    {
-      "id": "destructive-action",
-      "name": "Destructive action",
-      "description": "The requested UI performs an irreversible or high-consequence operation: deleting records or accounts, revoking access, removing members.",
-      "relatedPatterns": ["destructive-action-confirmation"]
-    },
-    {
-      "id": "record-collection",
-      "name": "Record collection",
-      "description": "Surfaces that present many records of the same kind — support tickets, orders, members — for scanning and action. Records share uniform fields, so the collection renders as a semantic data table built from the Table primitives; status stays readable as text (badges are appropriate, color is never the only signal). Per-row actions and destructive confirmations follow the data-table-with-row-actions pattern as guidance until the dropdown-menu item vocabulary is specified.",
-      "relatedPatterns": ["data-table-with-row-actions"]
-    }
-  ],
-  "rules": [
-    {
-      "id": "rule.destructive-requires-alertdialog",
-      "type": "component-choice",
-      "severity": "must",
-      "appliesTo": { "intents": ["destructive-action"] },
-      "require": ["alert-dialog"],
-      "forbid": ["dialog"],
-      "rationale": "Dialog can be dismissed by clicking the overlay or pressing Escape, so a user can bypass a destructive confirmation without making a conscious choice. AlertDialog forces an explicit confirm/cancel decision and is announced with greater urgency by screen readers.",
-      "examples": ["ex.delete-account-confirmation"],
-      "tags": ["safety", "accessibility"]
-    },
-    {
-      "id": "rule.alertdialog-requires-cancel",
-      "type": "required-composition",
-      "severity": "must",
-      "component": "alert-dialog",
-      "requiredSubComponents": [
-        { "id": "alert-dialog-cancel", "min": 1 },
-        { "id": "alert-dialog-title", "min": 1 }
+      "tokens": [
+        "background",
+        "foreground",
+        "muted",
+        "muted-foreground",
+        "border"
       ],
-      "rationale": "A confirmation without an explicit cancel action and a title naming the consequence funnels the user toward the destructive action; the title is also required for aria-labelledby.",
-      "examples": ["ex.delete-account-confirmation"],
-      "tags": ["safety", "accessibility"]
-    },
-    {
-      "id": "rule.button-no-interactive-descendants",
-      "type": "forbidden-composition",
-      "severity": "must",
-      "component": "button",
-      "forbiddenDescendants": ["button", "input"],
-      "rationale": "Nested interactive elements create ambiguous click targets and are an accessibility violation: screen readers cannot determine intent and click handling varies across browsers.",
-      "examples": ["ex.delete-account-confirmation"],
-      "tags": ["accessibility", "interaction"]
-    },
-    {
-      "id": "rule.trigger-carries-label",
-      "type": "required-props",
-      "severity": "must",
-      "component": "alert-dialog-trigger",
-      "requiredText": true,
-      "textScope": "subtree",
-      "rationale": "The trigger must present an accessible label: non-empty text somewhere under the trigger. Protocol projections lift the label from the trigger's subtree (preferring a label-bearing button; lifts are audited) — a trigger with no label text anywhere yields a control with no accessible name and an instance downstream emitters must refuse.",
-      "examples": ["ex.delete-account-confirmation"],
-      "tags": ["accessibility", "projection"]
-    },
-    {
-      "id": "rule.alertdialog-no-nested-overlays",
-      "type": "forbidden-composition",
-      "severity": "must",
-      "component": "alert-dialog",
-      "forbiddenCategories": ["overlay"],
-      "rationale": "An alert dialog is a single focused interruption. Stacking another overlay (dialog, dropdown menu, another alert dialog) inside it breaks focus containment and dismiss semantics and buries the confirmation decision under a second layer.",
-      "tags": ["accessibility", "interaction"]
-    },
-    {
-      "id": "rule.record-collection-requires-table",
-      "type": "component-choice",
-      "severity": "must",
-      "appliesTo": { "intents": ["record-collection"] },
-      "require": ["table"],
-      "rationale": "The data-table-with-row-actions pattern: a record collection is built from the Table primitives, not prose or ad-hoc stacks. Records share uniform fields; a semantic table is how they stay scannable, sortable, and navigable by assistive technology.",
-      "examples": ["ex.support-ticket-queue"],
-      "tags": ["structure"]
-    },
-    {
-      "id": "rule.table-carries-structure",
-      "type": "required-composition",
-      "severity": "must",
-      "appliesTo": { "intents": ["record-collection"] },
-      "component": "table",
-      "requiredSubComponents": [
-        { "id": "table-header", "min": 1 },
-        { "id": "table-body", "min": 1 }
+      "relatedComponents": [
+        "badge",
+        "button",
+        "dropdown-menu"
       ],
-      "rationale": "The table's own constraints demand semantic structure: header cells as th within a TableHeader so screen readers can associate columns, and records inside a TableBody. A table without both is a grid of divs wearing table styling.",
-      "examples": ["ex.support-ticket-queue"],
-      "tags": ["structure", "accessibility"]
+      "tags": [
+        "data",
+        "table",
+        "tabular",
+        "display"
+      ]
     },
-    {
-      "id": "rule.table-carries-caption",
-      "type": "required-composition",
-      "severity": "must",
-      "appliesTo": { "intents": ["record-collection"] },
-      "component": "table",
-      "requiredSubComponents": [{ "id": "table-caption", "min": 1 }],
-      "rationale": "The data-table-with-row-actions pattern requires an accessible name via TableCaption or an aria-label. The pattern permits either; the contract can only govern the declarative form, so the caption is the enforceable floor — an aria-label alternative is legitimate but inexpressible in current rule types and remains guidance.",
-      "examples": ["ex.support-ticket-queue"],
-      "tags": ["accessibility"]
-    }
-  ],
-  "examples": [
-    {
-      "id": "ex.delete-account-confirmation",
-      "intent": "destructive-action",
-      "name": "Delete account confirmation",
-      "prompt": "a screen to delete my account",
-      "description": "Card with a destructive entry point; AlertDialog confirmation with explicit consequence text, cancel-before-confirm, destructive confirm variant.",
-      "surface": {
-        "dspackSurface": "0.1",
-        "system": "shadcn/ui",
-        "intent": "destructive-action",
-        "root": {
-          "component": "card",
-          "children": [
-            {
-              "component": "alert-dialog",
-              "children": [
-                {
-                  "component": "alert-dialog-trigger",
-                  "children": [
-                    {
-                      "component": "button",
-                      "props": { "variant": "destructive" },
-                      "text": "Delete account"
-                    }
-                  ]
-                },
-                {
-                  "component": "alert-dialog-content",
-                  "children": [
-                    { "component": "alert-dialog-title", "text": "Delete your account?" },
-                    {
-                      "component": "alert-dialog-description",
-                      "text": "This will permanently delete your account and all associated data. This action cannot be undone."
-                    },
-                    {
-                      "component": "alert-dialog-footer",
+    "popover": {
+      "name": "Popover",
+      "description": "A non-modal floating panel anchored to a trigger, rendered in a portal. Built on Radix UI Popover. The content element carries role=\"dialog\" and the trigger carries aria-haspopup=\"dialog\", aria-expanded, and aria-controls. Unlike Dialog, it is non-modal by default: focus is not trapped, the page behind stays scrollable and interactive, and the rest of the page is not hidden from assistive technology.",
+      "status": "stable",
+      "whenToUse": "Use for rich, interactive content that belongs to a specific control and should appear next to it: a date picker, a column-visibility menu, a filter builder, a small edit form, a combobox surface. Reach for Popover when the content is transient, contains focusable elements, and the user should be able to keep working with the page around it.",
+      "whenNotToUse": "Do not use for plain descriptive text on hover — use Tooltip, which is announced via aria-describedby and costs no interaction. Do not use for content that must be dealt with before the user continues; use Dialog, which is modal and traps focus. Do not use for a list of commands or actions; use DropdownMenu, which implements the menu pattern with roving focus and typeahead. Do not use for large or edge-anchored panels such as navigation or detail drawers; use Sheet.",
+      "props": {
+        "open": {
+          "type": "boolean",
+          "propRole": "state",
+          "description": "On Popover (root). Controlled open state. Pair with onOpenChange; omit both to let the component manage its own state."
+        },
+        "defaultOpen": {
+          "type": "boolean",
+          "propRole": "state",
+          "default": false,
+          "description": "On Popover (root). Initial open state for uncontrolled usage. Do not combine with open."
+        },
+        "onOpenChange": {
+          "type": "function",
+          "propRole": "handler",
+          "description": "On Popover (root). Callback fired when the open state changes, including when the popover closes via Escape or an outside pointer press."
+        },
+        "modal": {
+          "type": "boolean",
+          "propRole": "flag",
+          "default": false,
+          "description": "On Popover (root). When false (the default) focus is not trapped, outside pointer events pass through, and the page keeps scrolling. When true, focus is trapped inside the content, outside pointer events are disabled, the rest of the page is marked aria-hidden, and scroll is locked. Set true only when the popover's task must be completed or abandoned before anything else."
+        },
+        "side": {
+          "type": "enum",
+          "propRole": "choice",
+          "values": [
+            {
+              "value": "top",
+              "description": "Open above the anchor. Use when the trigger sits near the bottom of the viewport or above a long form."
+            },
+            {
+              "value": "right",
+              "description": "Open to the right of the anchor. Use for triggers in a left rail or the start of a row."
+            },
+            {
+              "value": "bottom",
+              "description": "Open below the anchor. The default, and the right choice for toolbar and field-adjacent triggers."
+            },
+            {
+              "value": "left",
+              "description": "Open to the left of the anchor. Use for triggers in a right rail or the end of a row."
+            }
+          ],
+          "default": "bottom",
+          "description": "On PopoverContent. Preferred edge of the anchor to open against. This is a preference, not a guarantee — with avoidCollisions left on, the popover flips to the opposite side when the preferred side would overflow the viewport."
+        },
+        "align": {
+          "type": "enum",
+          "propRole": "choice",
+          "values": [
+            {
+              "value": "start",
+              "description": "Align the content's start edge with the anchor's start edge. Use for wide content hanging off a narrow left-aligned trigger."
+            },
+            {
+              "value": "center",
+              "description": "Center the content on the anchor. The shadcn default."
+            },
+            {
+              "value": "end",
+              "description": "Align the content's end edge with the anchor's end edge. Use for right-aligned triggers so the panel does not overhang the viewport."
+            }
+          ],
+          "default": "center",
+          "description": "On PopoverContent. Alignment along the perpendicular axis of side. shadcn's PopoverContent sets this to center explicitly, matching the Radix default."
+        },
+        "sideOffset": {
+          "type": "number",
+          "propRole": "dimension",
+          "default": 4,
+          "description": "On PopoverContent. Distance in pixels between the anchor and the content along the side axis. shadcn overrides the Radix default of 0 to 4 so the panel's shadow reads as separate from the trigger."
+        },
+        "alignOffset": {
+          "type": "number",
+          "propRole": "dimension",
+          "default": 0,
+          "description": "On PopoverContent. Offset in pixels along the alignment axis. Use to nudge the panel into optical alignment with an icon trigger; prefer changing align first."
+        },
+        "avoidCollisions": {
+          "type": "boolean",
+          "propRole": "flag",
+          "default": true,
+          "description": "On PopoverContent. When true the popover flips and shifts to stay inside the viewport. Leave enabled; disabling it will let the panel render partly offscreen on small viewports."
+        },
+        "collisionPadding": {
+          "type": "number",
+          "propRole": "dimension",
+          "default": 0,
+          "description": "On PopoverContent. Minimum distance in pixels to keep from the collision boundary. Raise it when a sticky header or bottom bar would otherwise sit on top of the panel."
+        },
+        "asChild": {
+          "type": "boolean",
+          "propRole": "flag",
+          "default": false,
+          "description": "On PopoverTrigger and PopoverAnchor. Merges props and behavior onto the single child element instead of rendering the default element. Use asChild on PopoverTrigger to make a Button the trigger without nesting a button inside a button."
+        }
+      },
+      "accessibility": {
+        "role": "dialog",
+        "requiredAttributes": [
+          {
+            "attribute": "aria-labelledby",
+            "condition": "always, on PopoverContent",
+            "description": "Radix Popover has no Title part, so nothing is wired automatically. Give PopoverTitle an id and reference it from PopoverContent's aria-labelledby, or supply aria-label on PopoverContent when there is no visible title. Without one of these the panel is announced only as \"dialog\"."
+          },
+          {
+            "attribute": "aria-describedby",
+            "condition": "when PopoverDescription is present",
+            "description": "Also unwired by default. Give PopoverDescription an id and reference it from PopoverContent so the supporting copy is announced on open."
+          },
+          {
+            "attribute": "aria-label",
+            "condition": "when the trigger is icon-only",
+            "description": "Name the trigger by the panel it opens, for example \"Filter options\", not by the icon."
+          }
+        ],
+        "keyboardInteractions": [
+          {
+            "key": "Enter",
+            "description": "On the trigger, opens the popover. Inside the content, activates the focused control."
+          },
+          {
+            "key": "Space",
+            "description": "On the trigger, opens the popover."
+          },
+          {
+            "key": "Tab",
+            "description": "Moves to the next focusable element. When non-modal (the default) focus leaves the popover and continues into the page; when modal, focus wraps within the content."
+          },
+          {
+            "key": "Shift + Tab",
+            "description": "Moves to the previous focusable element, with the same non-modal versus modal difference as Tab."
+          },
+          {
+            "key": "Escape",
+            "description": "Closes the popover and returns focus to PopoverTrigger."
+          }
+        ],
+        "focusManagement": "On open, focus moves into the content. On close, focus returns to PopoverTrigger. Focus is trapped only when modal is true; in the default non-modal mode Tab walks out of the panel into the rest of the page, which is why the panel must not hold a task that has to be finished before the user moves on.",
+        "labelRequirement": "required-accessible-name",
+        "notes": "PopoverHeader, PopoverTitle, and PopoverDescription are plain presentational elements in shadcn's implementation — a div, a div, and a p. They are not Radix parts and carry no ARIA wiring, unlike DialogTitle and DialogDescription. Rendering a PopoverTitle therefore does not give the panel an accessible name; the aria-labelledby link must be authored by hand. Because the default mode is non-modal, screen reader users can navigate away from an open popover with no warning; do not rely on the panel holding their attention."
+      },
+      "composition": {
+        "subComponents": [
+          {
+            "id": "popover-trigger",
+            "name": "PopoverTrigger",
+            "description": "The control that toggles the popover. Renders a button and receives aria-haspopup=\"dialog\", aria-expanded, and aria-controls automatically. Use asChild to project this behavior onto a Button.",
+            "required": true,
+            "slot": "trigger",
+            "acceptsChildren": "any",
+            "categories": [
+              "interactive"
+            ]
+          },
+          {
+            "id": "popover-content",
+            "name": "PopoverContent",
+            "description": "The floating panel, portalled to the document body and positioned against the anchor. Owns side, align, sideOffset, alignOffset, and the collision props, and is the element that must carry aria-labelledby or aria-label.",
+            "required": true,
+            "slot": "content",
+            "acceptsChildren": "any"
+          },
+          {
+            "id": "popover-anchor",
+            "name": "PopoverAnchor",
+            "description": "An optional alternative positioning reference. When present, PopoverContent positions against the anchor instead of the trigger. Use it when the visual origin of the panel differs from the control that opens it — anchoring a combobox list to the whole input while a chevron button triggers it, for example. Must be a descendant of the same Popover root.",
+            "slot": "anchor",
+            "acceptsChildren": "any"
+          },
+          {
+            "id": "popover-header",
+            "name": "PopoverHeader",
+            "description": "Groups the title and description at the top of the panel. A presentational div with no ARIA semantics.",
+            "slot": "header",
+            "acceptsChildren": "components"
+          },
+          {
+            "id": "popover-title",
+            "name": "PopoverTitle",
+            "description": "The panel's visible title. A presentational element, not a Radix part — give it an id and reference it from PopoverContent's aria-labelledby to make it the accessible name.",
+            "acceptsChildren": "text"
+          },
+          {
+            "id": "popover-description",
+            "name": "PopoverDescription",
+            "description": "Supporting copy beneath the title. A presentational p element — reference its id from PopoverContent's aria-describedby to have it announced.",
+            "acceptsChildren": "text"
+          }
+        ],
+        "requiredChildren": [
+          "popover-trigger",
+          "popover-content"
+        ],
+        "notes": "Positioning props live on PopoverContent, never on the Popover root; open state props live on the root, never on the content. PopoverContent portals itself, so no explicit Portal sub-component is exported or needed. PopoverAnchor, when used, replaces the trigger as the positioning reference but not as the control — the trigger still opens the panel. PopoverHeader, PopoverTitle, and PopoverDescription were added to the shadcn registry after the original three-part API; older installs may only export Popover, PopoverTrigger, PopoverContent, and PopoverAnchor."
+      },
+      "constraints": [
+        {
+          "context": "Transient interactive content anchored to a specific control, such as a date picker or filter panel",
+          "rule": "Use Popover",
+          "severity": "should"
+        },
+        {
+          "context": "Any PopoverContent",
+          "rule": "Give the panel an accessible name by wiring aria-labelledby to the PopoverTitle's id, or by setting aria-label — Radix Popover does not wire this automatically",
+          "severity": "must"
+        },
+        {
+          "context": "Plain descriptive text shown on hover or focus",
+          "rule": "Use Tooltip instead of Popover",
+          "severity": "should-not"
+        },
+        {
+          "context": "Content the user must act on before continuing, or that would leave the app in an inconsistent state if abandoned",
+          "rule": "Use Dialog instead of Popover, or set modal on Popover — the default non-modal popover lets focus and pointer input leave freely",
+          "severity": "must-not"
+        },
+        {
+          "context": "A list of commands or actions",
+          "rule": "Use DropdownMenu instead of Popover so the menu pattern, roving focus, and typeahead come for free",
+          "severity": "should"
+        },
+        {
+          "context": "Positioning a popover with side, align, sideOffset, or the collision props",
+          "rule": "Set these on PopoverContent, not on the Popover root, where they have no effect",
+          "severity": "must"
+        },
+        {
+          "context": "An icon-only PopoverTrigger",
+          "rule": "Give the trigger an aria-label naming the panel it opens",
+          "severity": "must"
+        },
+        {
+          "context": "A trigger that is already a Button or other interactive element",
+          "rule": "Use asChild on PopoverTrigger rather than nesting the control inside it, which would produce a button within a button",
+          "severity": "must"
+        },
+        {
+          "context": "Small viewports where the panel would overflow",
+          "rule": "Leave avoidCollisions enabled and consider Sheet for content that cannot fit as a floating panel",
+          "severity": "should"
+        }
+      ],
+      "tokens": [
+        "popover",
+        "popover-foreground",
+        "border",
+        "radius"
+      ],
+      "relatedComponents": [
+        "tooltip",
+        "dropdown-menu",
+        "dialog",
+        "sheet",
+        "button"
+      ],
+      "tags": [
+        "overlay",
+        "floating",
+        "anchored",
+        "non-modal",
+        "portal"
+      ],
+      "categories": [
+        "overlay"
+      ],
+      "notes": "Overlap to disambiguate later: Popover, Dialog, Sheet, DropdownMenu, and Tooltip all render portalled content above the page, and nothing in the type system stops an author from using any of them for the same job. The distinctions that matter are modality (Popover is non-modal by default, Dialog and Sheet are modal), anchoring (Popover and Tooltip position against a trigger; Dialog and Sheet position against the viewport), and interactivity (Tooltip content is unreachable, Popover content is fully interactive). A governance rule should later select on those axes rather than on component identity — for example, flagging interactive controls inside Tooltip content, and flagging a Popover carrying a form with a submit action that ought to be a Dialog. Token note: this entry references popover and popover-foreground, which are real shadcn theme variables (--popover, --popover-foreground) but are not yet present in this pack's token registry; they should be registered rather than substituted with background and foreground, which would misdescribe the component."
+    },
+    "tooltip": {
+      "name": "Tooltip",
+      "description": "A small text label that appears on hover or keyboard focus to describe the control it is attached to. Built on Radix UI Tooltip. The content carries role=\"tooltip\" and is linked to the trigger with aria-describedby while open. It is supplementary by definition: it does not receive focus, it closes on click and on pointer-down, and it never opens from touch input.",
+      "status": "stable",
+      "whenToUse": "Use to name or clarify a control whose purpose is not fully carried by its visible presentation — an icon-only button, a truncated cell, an abbreviated column header, a disabled control whose reason for being disabled needs explaining. Keep the content to a short phrase.",
+      "whenNotToUse": "Do not use for anything the user actually needs. Tooltip content is unreachable on touch devices and disappears on click, so information that is required to complete a task must live in the page, in a Popover, or in helper text. Do not put links, buttons, form fields, or any focusable element inside a tooltip — they cannot be reached. Do not use a tooltip as a control's only accessible name if the control is not the trigger itself.",
+      "props": {
+        "delayDuration": {
+          "type": "number",
+          "propRole": "dimension",
+          "default": 0,
+          "description": "On TooltipProvider and Tooltip (root). Milliseconds of hover before the tooltip opens. shadcn overrides the Radix default of 700 to 0 on its TooltipProvider, so tooltips appear immediately. Set a non-zero value on the provider when instant tooltips feel noisy across a dense UI; set it on an individual Tooltip to override the provider for one case."
+        },
+        "skipDelayDuration": {
+          "type": "number",
+          "propRole": "dimension",
+          "default": 300,
+          "description": "On TooltipProvider. Milliseconds during which moving to another trigger opens its tooltip with no delay. This is what makes sweeping across a toolbar feel continuous rather than stuttering."
+        },
+        "disableHoverableContent": {
+          "type": "boolean",
+          "propRole": "flag",
+          "default": false,
+          "description": "On TooltipProvider and Tooltip (root). When true the tooltip closes as soon as the pointer leaves the trigger, instead of staying open while the pointer travels onto the content. Leave false so users can move onto long content to read it."
+        },
+        "open": {
+          "type": "boolean",
+          "propRole": "state",
+          "description": "On Tooltip (root). Controlled open state. Use sparingly — forcing a tooltip open bypasses the hover and focus semantics screen reader and touch users depend on."
+        },
+        "defaultOpen": {
+          "type": "boolean",
+          "propRole": "state",
+          "default": false,
+          "description": "On Tooltip (root). Initial open state for uncontrolled usage."
+        },
+        "onOpenChange": {
+          "type": "function",
+          "propRole": "handler",
+          "description": "On Tooltip (root). Callback fired when the open state changes."
+        },
+        "side": {
+          "type": "enum",
+          "propRole": "choice",
+          "values": [
+            {
+              "value": "top",
+              "description": "Open above the trigger. The default, and the safest choice because it does not cover the content below the control."
+            },
+            {
+              "value": "right",
+              "description": "Open to the right. Use for triggers in a collapsed left navigation rail."
+            },
+            {
+              "value": "bottom",
+              "description": "Open below the trigger. Use for controls in a top app bar where a top-side tooltip would clip."
+            },
+            {
+              "value": "left",
+              "description": "Open to the left. Use for triggers at the right edge of a row or toolbar."
+            }
+          ],
+          "default": "top",
+          "description": "On TooltipContent. Preferred edge of the trigger to open against. With avoidCollisions on, the tooltip flips to the opposite side rather than overflowing the viewport."
+        },
+        "align": {
+          "type": "enum",
+          "propRole": "choice",
+          "values": [
+            {
+              "value": "start",
+              "description": "Align to the trigger's start edge. Use when the label is much wider than a small trigger at the start of a row."
+            },
+            {
+              "value": "center",
+              "description": "Center on the trigger. The default and the right choice for icon buttons."
+            },
+            {
+              "value": "end",
+              "description": "Align to the trigger's end edge. Use for triggers near the end of a row."
+            }
+          ],
+          "default": "center",
+          "description": "On TooltipContent. Alignment along the perpendicular axis of side."
+        },
+        "sideOffset": {
+          "type": "number",
+          "propRole": "dimension",
+          "default": 0,
+          "description": "On TooltipContent. Distance in pixels from the trigger. shadcn sets 0 because its TooltipContent renders a built-in arrow that visually bridges the gap."
+        },
+        "alignOffset": {
+          "type": "number",
+          "propRole": "dimension",
+          "default": 0,
+          "description": "On TooltipContent. Offset in pixels along the alignment axis."
+        },
+        "avoidCollisions": {
+          "type": "boolean",
+          "propRole": "flag",
+          "default": true,
+          "description": "On TooltipContent. When true the tooltip flips and shifts to stay inside the viewport. Leave enabled."
+        },
+        "aria-label": {
+          "type": "string",
+          "propRole": "content",
+          "description": "On TooltipContent. Replaces the visible content in the accessibility tree with this string, rendered into a visually hidden element that carries role=\"tooltip\". Use only when the visible content does not read well when announced — for example a formatted value where the spoken form should differ. Setting it removes role=\"tooltip\" from the visible element."
+        },
+        "asChild": {
+          "type": "boolean",
+          "propRole": "flag",
+          "default": false,
+          "description": "On TooltipTrigger. Merges the trigger behavior onto the single child element instead of rendering a button. Use it to attach a tooltip to an existing Button without nesting one button inside another."
+        }
+      },
+      "accessibility": {
+        "role": "tooltip",
+        "requiredAttributes": [
+          {
+            "attribute": "aria-describedby",
+            "condition": "wired automatically by Radix while the tooltip is open",
+            "description": "Radix sets aria-describedby on the trigger, pointing at the content id. This makes the tooltip a description, not a name — an icon-only button still needs its own accessible name from aria-label or visually hidden text."
+          },
+          {
+            "attribute": "aria-label",
+            "condition": "on an icon-only trigger",
+            "description": "Name the control itself. Do not rely on the tooltip to supply the name: description and name are announced differently, and the tooltip is entirely absent for touch users."
+          }
+        ],
+        "keyboardInteractions": [
+          {
+            "key": "Tab",
+            "description": "Moving focus to the trigger opens the tooltip immediately, bypassing delayDuration. Moving focus away closes it."
+          },
+          {
+            "key": "Escape",
+            "description": "Closes the tooltip while leaving focus on the trigger."
+          },
+          {
+            "key": "Space",
+            "description": "Closes the tooltip, because activating the trigger dismisses it."
+          },
+          {
+            "key": "Enter",
+            "description": "Closes the tooltip, because activating the trigger dismisses it."
+          }
+        ],
+        "focusManagement": "The tooltip never takes focus — focus stays on the trigger the whole time it is open, and the content is not in the tab order. This is exactly why interactive content inside a tooltip is unreachable. The trigger must itself be focusable: a natively disabled button fires no focus or pointer events, so wrap it in a focusable element or mark it aria-disabled with the control still focusable if the tooltip needs to explain why it is unavailable.",
+        "labelRequirement": "required-accessible-name",
+        "notes": "Radix explicitly ignores pointer events whose pointerType is \"touch\", so a tooltip never opens from a tap or a touch hover — on phones and tablets the content simply does not exist. Pointer-down and click also close it. Treat every tooltip as decoration over information already available elsewhere. Because the content is linked with aria-describedby, it is announced after the control's name and role; a control whose name comes only from its tooltip will be announced as unnamed to some users and as nothing at all on touch."
+      },
+      "composition": {
+        "subComponents": [
+          {
+            "id": "tooltip-provider",
+            "name": "TooltipProvider",
+            "description": "Supplies shared timing context — delayDuration, skipDelayDuration, disableHoverableContent — to every Tooltip beneath it. Mount it once near the application root. It is not optional: a Tooltip rendered outside a provider throws, because Radix creates the provider context with no default value.",
+            "required": true,
+            "slot": "provider",
+            "acceptsChildren": "any"
+          },
+          {
+            "id": "tooltip-trigger",
+            "name": "TooltipTrigger",
+            "description": "The control the tooltip describes. Renders a button and receives aria-describedby while open. Use asChild to attach the behavior to an existing Button or other focusable control.",
+            "required": true,
+            "slot": "trigger",
+            "acceptsChildren": "any",
+            "categories": [
+              "interactive"
+            ]
+          },
+          {
+            "id": "tooltip-content",
+            "name": "TooltipContent",
+            "description": "The floating label, portalled to the document body and carrying role=\"tooltip\". shadcn's implementation renders a built-in arrow inside it, so no separate Arrow sub-component is exported. Accepts short text only — it is not reachable by keyboard or touch.",
+            "required": true,
+            "slot": "content",
+            "acceptsChildren": "text"
+          }
+        ],
+        "requiredChildren": [
+          "tooltip-trigger",
+          "tooltip-content"
+        ],
+        "requiredParent": "tooltip-provider",
+        "notes": "TooltipProvider is an ancestor, not a sibling: wrap the application once rather than wrapping each Tooltip, so skipDelayDuration can do its job across adjacent triggers. Positioning props live on TooltipContent; timing props live on TooltipProvider or the Tooltip root. shadcn's TooltipContent already includes the Radix Arrow, so do not add one."
+      },
+      "constraints": [
+        {
+          "context": "Clarifying an icon-only button, a truncated label, or an abbreviated header",
+          "rule": "Use Tooltip with short text content",
+          "severity": "should"
+        },
+        {
+          "context": "Any application rendering a Tooltip",
+          "rule": "Mount a single TooltipProvider at the application root — Tooltip throws when rendered outside one",
+          "severity": "must"
+        },
+        {
+          "context": "Links, buttons, form fields, or any focusable element inside tooltip content",
+          "rule": "Move the interactive content into a Popover — tooltip content never receives focus and closes on click, so those controls are unreachable",
+          "severity": "must-not"
+        },
+        {
+          "context": "Information a user needs in order to complete a task",
+          "rule": "Do not put it only in a Tooltip — it is entirely absent on touch devices; put it in the page, in helper text, or in a Popover",
+          "severity": "must-not"
+        },
+        {
+          "context": "An icon-only control with a tooltip",
+          "rule": "Give the control its own accessible name with aria-label or visually hidden text; the tooltip supplies aria-describedby, which is a description and not a name",
+          "severity": "must"
+        },
+        {
+          "context": "A tooltip on a disabled control",
+          "rule": "Keep the trigger focusable — use aria-disabled with the control still in the tab order, or wrap it, because a natively disabled button emits no pointer or focus events and the tooltip will never open",
+          "severity": "must"
+        },
+        {
+          "context": "Tooltip content longer than a short phrase",
+          "rule": "Use a Popover instead, so the content can be read at the user's pace and reached by keyboard",
+          "severity": "should"
+        },
+        {
+          "context": "A trigger that is already a Button or other interactive element",
+          "rule": "Use asChild on TooltipTrigger rather than nesting the control inside it",
+          "severity": "must"
+        }
+      ],
+      "tokens": [
+        "foreground",
+        "background",
+        "radius"
+      ],
+      "relatedComponents": [
+        "popover",
+        "button",
+        "dropdown-menu"
+      ],
+      "tags": [
+        "overlay",
+        "hint",
+        "description",
+        "hover",
+        "non-modal",
+        "portal"
+      ],
+      "categories": [
+        "overlay"
+      ],
+      "notes": "Overlap to disambiguate later: Tooltip and Popover are both trigger-anchored portalled overlays and are frequently interchanged by mistake. The dividing line is reachability, not size — tooltip content cannot be focused, is dismissed by click, and is never shown to touch users, so anything load-bearing or interactive belongs in a Popover. A governance rule should later assert that TooltipContent's subtree contains no interactive-category component and no focusable element, and should flag a Tooltip whose content is the only place a piece of information appears. Token note: shadcn's TooltipContent inverts the surface, using bg-foreground with text-background rather than a dedicated tooltip token pair, so the tokens listed here are deliberately the base semantic colors and not a popover-style pair."
+    },
+    "sheet": {
+      "name": "Sheet",
+      "description": "A modal panel that slides in from an edge of the viewport. Built on the same Radix UI Dialog primitive as Dialog — same modality, same focus trap, same dismissal behavior — differing only in that its content is pinned to a viewport edge rather than centered, and sized to that edge. Renders an overlay and, by default, a close button in the corner of the panel.",
+      "status": "stable",
+      "whenToUse": "Use for a focused task or detail view that needs more room than a Popover and benefits from staying visually connected to the edge it came from: mobile navigation, a filters panel, a record's detail or edit view, a settings drawer. The left and right sides suit navigation and long forms; the bottom side suits mobile action panels.",
+      "whenNotToUse": "Do not use for confirming a destructive action — use AlertDialog, which cannot be dismissed by accident. Do not use for a short message or a small form that fits in a centered window; Dialog is the more conventional choice and demands less travel from the user's eye. Do not use for content anchored to a specific control, such as a picker or a small menu; use Popover or DropdownMenu. Do not use for brief status feedback; use a toast.",
+      "props": {
+        "open": {
+          "type": "boolean",
+          "propRole": "state",
+          "description": "On Sheet (root). Controlled open state. Pair with onOpenChange."
+        },
+        "defaultOpen": {
+          "type": "boolean",
+          "propRole": "state",
+          "default": false,
+          "description": "On Sheet (root). Initial open state for uncontrolled usage."
+        },
+        "onOpenChange": {
+          "type": "function",
+          "propRole": "handler",
+          "description": "On Sheet (root). Callback fired when the open state changes, including dismissal via Escape, the overlay, or the close button. Use it to reset panel state so a reopened sheet does not show stale input."
+        },
+        "modal": {
+          "type": "boolean",
+          "propRole": "flag",
+          "default": true,
+          "description": "On Sheet (root). When true (the default) focus is trapped in the panel, the rest of the page is hidden from assistive technology, and outside pointer events are blocked. Setting it false breaks the expectation the overlay sets — the page still looks dimmed and unavailable while remaining interactive."
+        },
+        "side": {
+          "type": "enum",
+          "propRole": "choice",
+          "values": [
+            {
+              "value": "right",
+              "description": "Slide in from the right edge, full height, capped near 24rem on larger viewports. The default, and the conventional place for detail and edit panels in left-to-right layouts."
+            },
+            {
+              "value": "left",
+              "description": "Slide in from the left edge, full height. Use for navigation, which users expect on the side the primary nav already occupies."
+            },
+            {
+              "value": "top",
+              "description": "Slide down from the top edge, height sized to content. Use sparingly — it collides with system and browser chrome and with sticky headers."
+            },
+            {
+              "value": "bottom",
+              "description": "Slide up from the bottom edge, height sized to content. The most reachable option on phones, where the top of the screen is far from the thumb."
+            }
+          ],
+          "default": "right",
+          "description": "On SheetContent. Which viewport edge the panel is pinned to and animates from. Left and right panels are full height; top and bottom panels size to their content."
+        },
+        "showCloseButton": {
+          "type": "boolean",
+          "propRole": "flag",
+          "default": true,
+          "description": "On SheetContent. Renders the built-in close button in the panel's top-right corner, an icon button with visually hidden \"Close\" text. Set false only when supplying an explicit SheetClose elsewhere in the panel — never to remove the visible dismissal affordance entirely."
+        },
+        "onEscapeKeyDown": {
+          "type": "function",
+          "propRole": "handler",
+          "description": "On SheetContent. Fires when Escape is pressed. Call preventDefault to keep the sheet open — do this only to confirm discarding unsaved work, never to make the panel undismissable."
+        },
+        "onInteractOutside": {
+          "type": "function",
+          "propRole": "handler",
+          "description": "On SheetContent. Fires when the user interacts outside the panel, including on the overlay. Call preventDefault to suppress accidental dismissal of a partially completed form, and pair it with a confirmation path."
+        },
+        "asChild": {
+          "type": "boolean",
+          "propRole": "flag",
+          "default": false,
+          "description": "On SheetTrigger and SheetClose. Merges props and behavior onto the single child element. Use it to make an existing Button open or close the sheet without nesting a button inside a button."
+        }
+      },
+      "accessibility": {
+        "role": "dialog",
+        "requiredAttributes": [
+          {
+            "attribute": "aria-labelledby",
+            "condition": "satisfied by rendering SheetTitle",
+            "description": "SheetTitle is Radix's Dialog.Title, so rendering it wires aria-labelledby automatically. A sheet without one is announced unnamed, and Radix logs a development warning. When the design has no visible title, still render SheetTitle inside a visually hidden wrapper."
+          },
+          {
+            "attribute": "aria-describedby",
+            "condition": "satisfied by rendering SheetDescription, or explicitly opted out",
+            "description": "SheetDescription is Radix's Dialog.Description and wires aria-describedby automatically. If the panel genuinely has no description, pass aria-describedby={undefined} to SheetContent to silence the Radix warning rather than adding filler text."
+          }
+        ],
+        "keyboardInteractions": [
+          {
+            "key": "Enter",
+            "description": "On the trigger, opens the sheet. Inside the panel, activates the focused control."
+          },
+          {
+            "key": "Space",
+            "description": "On the trigger, opens the sheet."
+          },
+          {
+            "key": "Tab",
+            "description": "Moves focus to the next focusable element inside the panel. Focus is trapped and wraps at the end."
+          },
+          {
+            "key": "Shift + Tab",
+            "description": "Moves focus to the previous focusable element inside the panel, wrapping at the start."
+          },
+          {
+            "key": "Escape",
+            "description": "Closes the sheet and returns focus to SheetTrigger."
+          }
+        ],
+        "focusManagement": "On open, focus moves into the panel — to the first focusable element, which is usually the built-in close button. On close, focus returns to SheetTrigger. Focus is trapped inside the panel and the rest of the page is marked aria-hidden while open, so a screen reader user cannot wander out of it. When the sheet is opened programmatically rather than by a trigger, set focus deliberately on close, because there is no trigger to return to.",
+        "labelRequirement": "required-visible",
+        "notes": "Because a Sheet is a Radix Dialog, all of Dialog's accessibility obligations apply unchanged. The panel is a scroll container in its own right; long content must scroll inside the panel rather than the page, and a footer with the primary action should stay reachable without scrolling past it. On small viewports a left or right sheet occupies three quarters of the width, so it is effectively full screen — check that the close affordance is inside the safe area."
+      },
+      "composition": {
+        "subComponents": [
+          {
+            "id": "sheet-trigger",
+            "name": "SheetTrigger",
+            "description": "The control that opens the sheet. Renders a button; use asChild to project the behavior onto an existing Button.",
+            "slot": "trigger",
+            "acceptsChildren": "any",
+            "categories": [
+              "interactive"
+            ]
+          },
+          {
+            "id": "sheet-content",
+            "name": "SheetContent",
+            "description": "The sliding panel. Renders its own portal and overlay internally, owns the side and showCloseButton props, and lays out as a flex column so SheetFooter can be pushed to the bottom.",
+            "required": true,
+            "slot": "content",
+            "acceptsChildren": "components"
+          },
+          {
+            "id": "sheet-header",
+            "name": "SheetHeader",
+            "description": "Groups the title and description at the top of the panel. A presentational div that supplies padding and spacing.",
+            "slot": "header",
+            "acceptsChildren": "components"
+          },
+          {
+            "id": "sheet-title",
+            "name": "SheetTitle",
+            "description": "The panel's title. This is Radix's Dialog.Title, so rendering it gives the sheet its accessible name via aria-labelledby. Required for an accessible sheet — hide it visually rather than omitting it.",
+            "required": true,
+            "acceptsChildren": "text"
+          },
+          {
+            "id": "sheet-description",
+            "name": "SheetDescription",
+            "description": "Supporting copy beneath the title. This is Radix's Dialog.Description and wires aria-describedby automatically. Omit it only alongside aria-describedby={undefined} on SheetContent.",
+            "acceptsChildren": "text"
+          },
+          {
+            "id": "sheet-footer",
+            "name": "SheetFooter",
+            "description": "Holds the panel's actions. A presentational div with an auto top margin, so it settles at the bottom of the panel regardless of content height.",
+            "slot": "footer",
+            "acceptsChildren": "components"
+          },
+          {
+            "id": "sheet-close",
+            "name": "SheetClose",
+            "description": "A control that closes the sheet. Use it for an explicit Cancel or Done button in SheetFooter, with asChild to wrap a Button. Distinct from the built-in corner close button that SheetContent renders when showCloseButton is true.",
+            "acceptsChildren": "any",
+            "categories": [
+              "interactive"
+            ]
+          }
+        ],
+        "requiredChildren": [
+          "sheet-content",
+          "sheet-title"
+        ],
+        "allowedChildren": [
+          "sheet-trigger",
+          "sheet-content"
+        ],
+        "notes": "SheetContent renders the portal and overlay itself; shadcn defines SheetPortal and SheetOverlay in the same file but does not export them, so they cannot be composed or overridden from outside. SheetTitle and SheetDescription belong inside SheetHeader, and SheetClose inside SheetFooter, though neither nesting is enforced. Because SheetContent is a flex column with a footer that has margin-top auto, scrolling regions should be placed as a middle child rather than wrapping the whole panel. The side prop lives on SheetContent, not on the Sheet root."
+      },
+      "constraints": [
+        {
+          "context": "A focused task or detail view needing more room than a Popover, such as mobile navigation, filters, or a record editor",
+          "rule": "Use Sheet",
+          "severity": "should"
+        },
+        {
+          "context": "Any SheetContent",
+          "rule": "Render a SheetTitle, visually hidden if the design has no visible title, so the panel has an accessible name",
+          "severity": "must"
+        },
+        {
+          "context": "A sheet with no description",
+          "rule": "Pass aria-describedby={undefined} to SheetContent rather than adding filler description text",
+          "severity": "should"
+        },
+        {
+          "context": "Confirming a destructive or irreversible action",
+          "rule": "Use AlertDialog instead of Sheet",
+          "severity": "must-not"
+        },
+        {
+          "context": "Content anchored to a specific control, such as a picker, filter panel, or action list",
+          "rule": "Use Popover or DropdownMenu instead of Sheet",
+          "severity": "should-not"
+        },
+        {
+          "context": "Choosing the edge for a mobile action panel",
+          "rule": "Use side=\"bottom\" so the panel and its actions fall within thumb reach",
+          "severity": "should"
+        },
+        {
+          "context": "Primary navigation revealed on small viewports",
+          "rule": "Use side=\"left\" or side=\"right\" to match the side the navigation occupies on larger viewports",
+          "severity": "should"
+        },
+        {
+          "context": "Suppressing dismissal with onEscapeKeyDown or onInteractOutside",
+          "rule": "Do this only to confirm discarding unsaved work, and always leave a visible way to close the panel",
+          "severity": "must"
+        },
+        {
+          "context": "Hiding the built-in close button with showCloseButton={false}",
+          "rule": "Provide an explicit SheetClose elsewhere in the panel",
+          "severity": "must"
+        },
+        {
+          "context": "A sheet whose content exceeds the panel height",
+          "rule": "Scroll inside the panel and keep the footer actions reachable, rather than letting the page behind scroll",
+          "severity": "should"
+        }
+      ],
+      "tokens": [
+        "background",
+        "foreground",
+        "muted-foreground",
+        "secondary",
+        "border",
+        "ring",
+        "radius"
+      ],
+      "relatedComponents": [
+        "dialog",
+        "alert-dialog",
+        "popover",
+        "button"
+      ],
+      "tags": [
+        "overlay",
+        "modal",
+        "drawer",
+        "panel",
+        "navigation",
+        "portal"
+      ],
+      "categories": [
+        "overlay"
+      ],
+      "notes": "Overlap to disambiguate later: Sheet is the Radix Dialog primitive with edge-anchored positioning — the sub-component sets are one-to-one (Trigger, Content, Header, Title, Description, Footer, Close) and the accessibility contract is identical, so nothing structural distinguishes a Sheet from a Dialog. The choice between them is presentational and contextual: viewport size, how much room the task needs, and whether the panel should read as attached to a page edge. AlertDialog is the one genuine behavioral distinction in this family, because it refuses dismissal by Escape or overlay. A governance rule should later encode: destructive confirmation must be AlertDialog, never Sheet or Dialog; a modal overlay carrying navigation or a long form should prefer Sheet; a short confirmation or small form should prefer Dialog; and an author should not nest a Sheet inside a Dialog or another Sheet, since stacked focus traps have no defined return path. Because Sheet, Dialog, and AlertDialog share prop names and sub-component shapes, that rule should key on intent and content, not on prop values."
+    },
+    "field": {
+      "name": "Field",
+      "description": "The family of layout and labeling primitives shadcn ships for composing form fields: Field wraps one control with its label, helper text, and validation message; FieldSet and FieldLegend give a set of related controls real fieldset/legend semantics; FieldGroup stacks fields and establishes the container query that the responsive orientation reads. Field renders a div with role=\"group\" and data-orientation; the rest are thin wrappers over label, legend, fieldset, and p. The family holds no form state, generates no ids, and performs no validation — the label/control/error association is written by hand (htmlFor plus id, aria-invalid, data-invalid) or driven by a form library's controller.",
+      "status": "stable",
+      "whenToUse": "Use for every hand-composed form field: pair FieldLabel with an Input, Textarea, Select, Checkbox, Switch, or Slider and add FieldDescription and FieldError as needed. Use FieldSet with FieldLegend when several controls answer one question (a checkbox group, a radio group, an address block), FieldGroup to stack related fields with consistent spacing and to enable responsive orientation, and orientation=\"horizontal\" for controls that read better beside their label such as switches and checkboxes. This is also the layer shadcn's current form guides build on — drive it with react-hook-form's Controller, TanStack Form, or Formisch.",
+      "whenNotToUse": "Do not use Field as a general-purpose layout box: it renders role=\"group\", which assistive technology announces, so non-form content wrapped in it is misdescribed. Do not use FieldSet and FieldLegend around a single control — the legend announces a grouping that does not exist. Do not expect Field to wire anything: if you want ids, aria-describedby, and aria-invalid applied for you inside a react-hook-form codebase, that is the older Form family (FormItem/FormControl). Do not mix the two families within one field.",
+      "props": {
+        "orientation": {
+          "type": "enum",
+          "propRole": "choice",
+          "values": [
+            {
+              "value": "vertical",
+              "description": "Stacks label, control, description, and error in a column and stretches each to full width. The default, and the right choice for text inputs, textareas, and mobile-first layouts."
+            },
+            {
+              "value": "horizontal",
+              "description": "Places the label beside the control on one row. Use for switches, checkboxes, and radio items where the control is small and the label reads as a sentence. Pair with FieldContent when the field also has a description, so the description stays aligned under the label rather than stretching across the row."
+            },
+            {
+              "value": "responsive",
+              "description": "Starts vertical and becomes horizontal once the surrounding FieldGroup is wide enough. It resolves against the @container/field-group container query that FieldGroup establishes, so a Field with this orientation outside a FieldGroup never switches."
+            }
+          ],
+          "default": "vertical",
+          "description": "How the label and control are arranged. Also exposed on the element as data-orientation, which FieldDescription reads to balance long helper text in horizontal layouts."
+        },
+        "data-invalid": {
+          "type": "boolean",
+          "propRole": "state",
+          "description": "Switches the whole field block into the error treatment, including the label and description. It is styling only and is never exposed to assistive technology, so it does not replace aria-invalid on the control itself — set both. With react-hook-form this is data-invalid={fieldState.invalid}."
+        }
+      },
+      "accessibility": {
+        "role": "group",
+        "labelRequirement": "required-visible",
+        "requiredAttributes": [
+          {
+            "attribute": "id",
+            "condition": "on every control placed inside a Field",
+            "description": "Give the control a stable, unique id and point the FieldLabel's htmlFor at it. Field does not generate or assign ids, so without this the control has no accessible name."
+          },
+          {
+            "attribute": "htmlFor",
+            "condition": "on every FieldLabel",
+            "description": "Must equal the id of the control the label names. This holds even in the choice-card pattern where FieldLabel wraps the whole Field: the htmlFor still targets the control's id, not the Field."
+          },
+          {
+            "attribute": "aria-invalid",
+            "condition": "on the control when the field fails validation",
+            "description": "Marks the control invalid for assistive technology. Field's data-invalid only restyles the block, so aria-invalid on the control is what actually communicates the error state."
+          },
+          {
+            "attribute": "aria-describedby",
+            "condition": "on the control whenever a FieldDescription or FieldError describes it",
+            "description": "The Field family does not associate helper text or errors with the control. Give the FieldDescription and FieldError elements ids and reference them from the control's aria-describedby, so the guidance is announced with the field rather than only when the FieldError alert fires."
+          }
+        ],
+        "keyboardInteractions": [
+          {
+            "key": "Tab",
+            "description": "Moves to the next focusable control. Field adds no keyboard behavior of its own — the wrappers are not focus stops, so tab order is exactly the order of the controls you place inside them."
+          },
+          {
+            "key": "Shift+Tab",
+            "description": "Moves to the previous focusable control."
+          }
+        ],
+        "focusManagement": "Field never moves focus. FieldError renders with role=\"alert\", so a message that appears after a failed submit is announced without stealing focus. Moving focus to the first invalid control after a failed submit is the form library's job — react-hook-form does it by default.",
+        "notes": "Clicking a FieldLabel focuses or toggles the control it names, because FieldLabel renders a real label element (Radix Label) — this only works when htmlFor matches the control's id, or when the label wraps the control. FieldSet plus FieldLegend is the only construct in the family that gives a set of controls a shared accessible name; a bare FieldGroup is a layout wrapper with no semantics. FieldTitle is styled like a label but is a plain div, so it names nothing on its own: use it only inside a choice card whose surrounding FieldLabel carries the htmlFor. Placeholder text is never a label."
+      },
+      "composition": {
+        "subComponents": [
+          {
+            "id": "field-content",
+            "name": "FieldContent",
+            "description": "A flex column that keeps the label, title, description, and error together when the control sits beside them — the layout you need for horizontal and responsive fields. Omit it in a plain vertical field with no description.",
+            "slot": "content",
+            "acceptsChildren": "components",
+            "categories": [
+              "form"
+            ]
+          },
+          {
+            "id": "field-label",
+            "name": "FieldLabel",
+            "description": "The label for a field, rendered as a real label element (Radix Label), so clicking it focuses or toggles the control named by its htmlFor. It also accepts asChild. Beyond labeling a single control it doubles as the choice-card wrapper: wrapping a whole Field in a FieldLabel makes the entire card a click target for the radio, checkbox, or switch inside it, and the checked state restyles the card.",
+            "slot": "label",
+            "acceptsChildren": "any",
+            "categories": [
+              "form"
+            ]
+          },
+          {
+            "id": "field-title",
+            "name": "FieldTitle",
+            "description": "Label-styled heading text for use inside FieldContent, typically as the headline of a choice card above its FieldDescription. It renders a div, not a label, so it provides no label association — the accessible name must still come from the surrounding FieldLabel or from the control.",
+            "slot": "title",
+            "acceptsChildren": "any",
+            "categories": [
+              "form"
+            ]
+          },
+          {
+            "id": "field-description",
+            "name": "FieldDescription",
+            "description": "Helper text rendered as a p, muted and line-balanced in horizontal layouts. It may hold links. It is not automatically associated with the control: give it an id and reference it from the control's aria-describedby. It also serves as the description under a FieldLegend inside a FieldSet.",
+            "slot": "description",
+            "acceptsChildren": "any",
+            "categories": [
+              "form"
+            ]
+          },
+          {
+            "id": "field-error",
+            "name": "FieldError",
+            "description": "The validation message container, rendered as a div with role=\"alert\" so a message that appears after submit is announced. It takes either children or an errors array of objects with a message property — the shape react-hook-form's fieldState.error and Standard Schema issues (Zod, Valibot, ArkType) already have. Given several messages it de-duplicates them and renders a bulleted list; given nothing it renders nothing.",
+            "slot": "error",
+            "acceptsChildren": "any",
+            "categories": [
+              "form"
+            ]
+          }
+        ],
+        "notes": "The nesting the docs prescribe is FieldSet > FieldLegend + FieldGroup > Field, and inside a Field: FieldLabel, the control, FieldDescription, FieldError — in that reading order, with FieldError immediately after the control it describes. FieldSet and FieldGroup are top-level components in this contract (they wrap Fields, they do not live inside one); upstream also allows a set-level FieldDescription, which this contract deliberately narrows to Field scope — every shipped example uses it there, and a set-level summary belongs to the legend. When the label sits beside the control, wrap the label, description, and error in FieldContent so they stay aligned. Any labelable control belongs inside a Field: Input, Textarea, Select, Checkbox, RadioGroupItem, Switch, Slider, InputGroup, or your own. No sub-component is marked required, deliberately: in the documented choice-card and radio patterns FieldLabel is an ancestor of Field rather than a descendant, so a structural must-contain rule would be false — the labeling requirement is carried as a constraint instead. FieldGroup is required in practice only for orientation=\"responsive\", which resolves against the container query FieldGroup establishes."
+      },
+      "constraints": [
+        {
+          "context": "A control that needs a label, helper text, and a validation message",
+          "rule": "Compose Field with FieldLabel, the control, FieldDescription, and FieldError rather than hand-rolling wrapper divs",
+          "severity": "should"
+        },
+        {
+          "context": "The association between a FieldLabel and its control",
+          "rule": "Set htmlFor on the FieldLabel to the control's id — Field generates and wires nothing",
+          "severity": "must"
+        },
+        {
+          "context": "A field that has failed validation",
+          "rule": "Set aria-invalid on the control and data-invalid on the Field; data-invalid is styling only and is not announced",
+          "severity": "must"
+        },
+        {
+          "context": "A FieldDescription or FieldError that explains a control",
+          "rule": "Give it an id and reference it from the control's aria-describedby, because the family does not associate them automatically",
+          "severity": "should"
+        },
+        {
+          "context": "Several controls that together answer one question, such as a checkbox or radio group",
+          "rule": "Wrap them in a FieldSet with a FieldLegend instead of repeating a label on each control",
+          "severity": "should"
+        },
+        {
+          "context": "A single standalone control",
+          "rule": "Do not wrap it in FieldSet and FieldLegend — the legend announces a group that does not exist",
+          "severity": "should-not"
+        },
+        {
+          "context": "Page or section layout of non-form content",
+          "rule": "Do not use Field, FieldGroup, or FieldSet as layout boxes; Field renders role=\"group\" and FieldSet renders a fieldset",
+          "severity": "must-not"
+        },
+        {
+          "context": "A Field using orientation=\"responsive\"",
+          "rule": "Place it inside a FieldGroup, which establishes the container query the responsive orientation resolves against",
+          "severity": "must"
+        },
+        {
+          "context": "Multiple validation messages from a schema validator",
+          "rule": "Pass the issues to FieldError's errors array and let it de-duplicate and list them rather than concatenating strings",
+          "severity": "should"
+        }
+      ],
+      "tokens": [
+        "foreground",
+        "muted-foreground",
+        "destructive",
+        "border",
+        "primary",
+        "background",
+        "radius"
+      ],
+      "relatedComponents": [
+        "form",
+        "label",
+        "input",
+        "textarea",
+        "select",
+        "checkbox",
+        "radio-group",
+        "switch",
+        "separator"
+      ],
+      "tags": [
+        "form",
+        "field",
+        "label",
+        "validation",
+        "grouping",
+        "accessibility"
+      ],
+      "categories": [
+        "form"
+      ]
+    },
+    "field-set": {
+      "name": "FieldSet",
+      "description": "A semantic fieldset that groups controls answering one question — a checkbox group, a radio group, an address block. Pair it with a FieldLegend so the group has an accessible name, and put the individual Fields in a FieldGroup inside it.",
+      "status": "stable",
+      "props": {},
+      "categories": [
+        "form"
+      ],
+      "tags": [
+        "form",
+        "grouping"
+      ],
+      "composition": {
+        "subComponents": [
+          {
+            "id": "field-legend",
+            "name": "FieldLegend",
+            "description": "The legend element that names a FieldSet and is announced with each control inside it. Takes a variant prop of \"legend\" (default, section-sized) or \"label\" (label-sized, for nested fieldsets or when the group reads as a single field, such as a checkbox group).",
+            "slot": "legend",
+            "acceptsChildren": "text",
+            "categories": [
+              "form"
+            ]
+          }
+        ]
+      }
+    },
+    "field-group": {
+      "name": "FieldGroup",
+      "description": "A layout wrapper that stacks Fields with consistent spacing and establishes the @container/field-group container query that orientation=\"responsive\" resolves against. It carries no semantics, so it never substitutes for FieldSet. Add data-slot=\"checkbox-group\" when it holds a checkbox group so the spacing tightens.",
+      "status": "stable",
+      "props": {},
+      "categories": [
+        "form"
+      ],
+      "tags": [
+        "form",
+        "grouping"
+      ],
+      "composition": {
+        "subComponents": [
+          {
+            "id": "field-separator",
+            "name": "FieldSeparator",
+            "description": "A divider between sections of a FieldGroup, optionally with inline text such as \"Or continue with\". Use it sparingly — every separator is a section boundary a screen reader user has to interpret.",
+            "acceptsChildren": "text",
+            "categories": [
+              "form"
+            ]
+          }
+        ]
+      }
+    },
+    "form": {
+      "name": "Form",
+      "description": "The react-hook-form wrapper family. Form is a re-export of react-hook-form's FormProvider, FormField wraps its Controller and publishes the field name on context, and FormItem generates one React id per field from which every other id is derived: the control gets `${id}-form-item`, the description `${id}-form-item-description`, the message `${id}-form-item-message`. FormControl is a Radix Slot that clones the single control inside it and stamps on id, aria-describedby, and aria-invalid, so the label/description/error association is generated rather than hand-written. Form itself renders no DOM — you still write the native form element and pass form.handleSubmit(onSubmit) to its onSubmit.",
+      "status": "stable",
+      "whenToUse": "Use in codebases already built on react-hook-form that want the field wiring generated: unique ids per field, htmlFor bound to the control, aria-describedby pointing at the description and, once the field errors, at the message, aria-invalid reflecting the field's error state, and the error text pulled straight out of formState without touching it.",
+      "whenNotToUse": "Do not use without react-hook-form: every part reads context from FormProvider and FormField, so outside them useFormField throws or produces ids like \"undefined-form-item\". Do not use it for new work in preference to Field — shadcn still ships form in the registry, but the component no longer has a documentation page and the current form guides compose Field with Controller instead, which also gives you horizontal and responsive layouts, fieldset grouping, and support for TanStack Form and Formisch. Do not reach for it when you need a field layout the family does not have: FormItem is a plain vertical stack.",
+      "props": {
+        "control": {
+          "type": "object",
+          "propRole": "state",
+          "required": true,
+          "description": "The control object returned by useForm(). In practice you never pass it alone: Form is react-hook-form's FormProvider, which takes the entire useForm() result, so the idiom is <Form {...form}>. FormField's Controller and every useFormField() consumer read the field's state through it."
+        },
+        "formState": {
+          "type": "object",
+          "propRole": "state",
+          "description": "Validation and submission state from useForm(): errors, isSubmitting, isDirty, isValid. FormLabel and FormMessage reach the current field's error through it via useFormField(), which is why neither takes an error prop."
+        },
+        "handleSubmit": {
+          "type": "function",
+          "propRole": "handler",
+          "description": "The submit wrapper from useForm(), carried on context along with the rest of the hook result. It belongs on the native form element as onSubmit={form.handleSubmit(onSubmit)} — Form renders no element, so it cannot receive an onSubmit of its own."
+        }
+      },
+      "accessibility": {
+        "labelRequirement": "required-visible",
+        "requiredAttributes": [
+          {
+            "attribute": "id",
+            "condition": "applied automatically by FormControl to the control it wraps",
+            "description": "FormControl sets id to the FormItem's generated form item id. Do not set your own id on a control inside FormControl: FormLabel's htmlFor targets the generated value, and overriding it silently breaks the label association."
+          },
+          {
+            "attribute": "htmlFor",
+            "condition": "applied automatically by FormLabel",
+            "description": "FormLabel renders a Radix Label with htmlFor bound to the same generated form item id, so clicking the label focuses the control. This resolves only if the control is wrapped in FormControl and both live inside the same FormItem."
+          },
+          {
+            "attribute": "aria-describedby",
+            "condition": "applied automatically by FormControl",
+            "description": "FormControl always references the FormDescription id, and appends the FormMessage id as soon as the field has an error. Render FormDescription and FormMessage inside the same FormItem, otherwise the reference points at an element that does not exist."
+          },
+          {
+            "attribute": "aria-invalid",
+            "condition": "applied automatically by FormControl when the field has an error",
+            "description": "Reflects the field's error state from formState. Do not set aria-invalid by hand on a control inside FormControl — FormControl owns it and will overwrite or contradict yours depending on prop order."
+          },
+          {
+            "attribute": "aria-labelledby",
+            "condition": "on the native form element when a page contains more than one form",
+            "description": "Name each form so the two are distinguishable when navigating by form; reference an existing visible heading, or use aria-label when no such heading exists."
+          }
+        ],
+        "keyboardInteractions": [
+          {
+            "key": "Tab",
+            "description": "Moves to the next control. The Form parts add no keyboard behavior of their own — FormItem is a div and FormControl renders no element, so tab order is the order of the controls."
+          },
+          {
+            "key": "Shift+Tab",
+            "description": "Moves to the previous control."
+          },
+          {
+            "key": "Enter",
+            "description": "Submits the form from a single-line text control, which is native form behavior and requires a submit button in the form. It runs the resolver first, so an invalid form errors instead of submitting."
+          }
+        ],
+        "focusManagement": "On a failed submit react-hook-form moves focus to the first invalid field (shouldFocusError defaults to true), which works because the control keeps the ref that Controller passes through FormControl. Note that FormMessage returns null while the field is valid, so the element aria-describedby points at exists only once the field errors — and it is a plain p, not a live region, so the message is announced when the control is next read rather than at the moment it appears. If you need immediate announcement, use the Field family's FieldError, which renders with role=\"alert\".",
+        "notes": "The family declares no ARIA role of its own: Form and FormField render nothing, FormControl renders nothing, and FormItem is a plain div — form semantics come from the native form element you write. Every part depends on both contexts: FormField supplies the field name, FormItem supplies the generated id. A FormLabel or FormControl outside a FormItem still renders, but its ids collapse to \"undefined-form-item\", so every such field on the page collides on the same id. A control that is not wrapped in FormControl receives no id, no aria-describedby, and no aria-invalid — the wiring is the whole point of the wrapper, and skipping it leaves an unlabeled field that looks correct on screen. FormLabel must carry visible text; a placeholder is not a label."
+      },
+      "composition": {
+        "subComponents": [
+          {
+            "id": "form-field",
+            "name": "FormField",
+            "description": "Wraps react-hook-form's Controller and publishes the field name on context so the parts beneath it can resolve their state. It takes name, control, and a render prop — the field's UI is returned from render({ field, fieldState }), not passed as children — and renders no element itself.",
+            "required": true,
+            "acceptsChildren": "none",
+            "categories": [
+              "form"
+            ]
+          },
+          {
+            "id": "form-item",
+            "name": "FormItem",
+            "description": "The per-field container, a div that calls React.useId() and publishes it on context. Every id in the field derives from it, so there must be exactly one FormItem per field: two controls under one FormItem would share the same id, label, and message references.",
+            "required": true,
+            "slot": "item",
+            "acceptsChildren": "components",
+            "categories": [
+              "form"
+            ]
+          },
+          {
+            "id": "form-label",
+            "name": "FormLabel",
+            "description": "The field's label, rendered as a Radix Label with htmlFor bound to the generated control id and data-error set when the field is invalid, which is what turns the label text destructive. It takes no error prop — it reads the field's error from context.",
+            "required": true,
+            "slot": "label",
+            "acceptsChildren": "text",
+            "categories": [
+              "form"
+            ]
+          },
+          {
+            "id": "form-control",
+            "name": "FormControl",
+            "description": "A Radix Slot that must wrap exactly one control and renders no element of its own. It merges id, aria-describedby, and aria-invalid onto that child, which is what makes the association automatic. The child must forward props and ref — every shadcn control does; a plain function component that drops them silently loses the wiring.",
+            "required": true,
+            "slot": "control",
+            "acceptsChildren": "components",
+            "categories": [
+              "form"
+            ]
+          },
+          {
+            "id": "form-description",
+            "name": "FormDescription",
+            "description": "Helper text rendered as a p carrying the generated description id. FormControl references that id from aria-describedby unconditionally, so include a FormDescription in any FormItem where guidance helps — and know that omitting it leaves the reference pointing at nothing.",
+            "slot": "description",
+            "acceptsChildren": "any",
+            "categories": [
+              "form"
+            ]
+          },
+          {
+            "id": "form-message",
+            "name": "FormMessage",
+            "description": "The validation message, rendered as a p carrying the generated message id. It prints the field's error message when there is one, falls back to its children when there is not, and returns null when there is neither — so the element exists only while the field is invalid. Author it in every FormItem: FormControl adds its id to aria-describedby the moment the field errors.",
+            "required": true,
+            "slot": "message",
+            "acceptsChildren": "text",
+            "categories": [
+              "form"
+            ]
+          }
+        ],
+        "requiredChildren": [
+          "form-field",
+          "form-item",
+          "form-control"
+        ],
+        "notes": "The shape is fixed: <Form {...form}> around a native <form onSubmit={form.handleSubmit(onSubmit)}>, then one FormField per field whose render returns a FormItem containing FormLabel, FormControl wrapping the control, an optional FormDescription, and FormMessage. Form is FormProvider and FormField is Controller, so neither emits markup — the native form element is yours to write, as are the submit Button and any layout between fields. useFormField is a hook, not a component: it is what every part calls to reach the field name, the generated ids, and the field's error. It throws outside a Form, because there is no react-hook-form context to read, and it misbehaves outside a FormField or a FormItem, where the field name and the generated id are undefined. Do not mix this family with the Field family inside one field; both want to own the association, and only one of them can."
+      },
+      "constraints": [
+        {
+          "context": "A form in a codebase already built on react-hook-form",
+          "rule": "Use the Form family so ids, htmlFor, aria-describedby, and aria-invalid are generated instead of hand-written",
+          "severity": "should"
+        },
+        {
+          "context": "A new form, or a form built on TanStack Form, Formisch, or no form library",
+          "rule": "Compose the Field family with the library's own controller instead — shadcn's current form guides build on Field, and Form is react-hook-form-only",
+          "severity": "should"
+        },
+        {
+          "context": "The control inside a field",
+          "rule": "Wrap it in exactly one FormControl; an unwrapped control gets no id, no aria-describedby, and no aria-invalid",
+          "severity": "must"
+        },
+        {
+          "context": "Attributes on a control inside FormControl",
+          "rule": "Do not set your own id or aria-invalid — FormControl owns them and FormLabel's htmlFor targets the generated id",
+          "severity": "must-not"
+        },
+        {
+          "context": "Each field rendered from a FormField's render prop",
+          "rule": "Render exactly one FormItem and keep FormLabel, FormControl, FormDescription, and FormMessage inside it, so they all resolve the same generated id",
+          "severity": "must"
+        },
+        {
+          "context": "Submitting the form",
+          "rule": "Put onSubmit={form.handleSubmit(onSubmit)} on the native form element — Form is FormProvider and renders no DOM to receive it",
+          "severity": "must"
+        },
+        {
+          "context": "The accessible name of each control",
+          "rule": "Provide a FormLabel with visible text; a placeholder is not a label",
+          "severity": "must"
+        },
+        {
+          "context": "A single field",
+          "rule": "Do not combine Form parts with Field parts — both own the label and error association, and mixing them produces duplicate or dangling references",
+          "severity": "must-not"
+        },
+        {
+          "context": "Client-side validation",
+          "rule": "Define the rules once as a schema and pass it through a resolver to useForm, rather than validating inside the field components",
+          "severity": "should"
+        }
+      ],
+      "tokens": [
+        "foreground",
+        "muted-foreground",
+        "destructive"
+      ],
+      "relatedComponents": [
+        "field",
+        "label",
+        "input",
+        "button"
+      ],
+      "tags": [
+        "form",
+        "validation",
+        "react-hook-form",
+        "accessibility"
+      ],
+      "categories": [
+        "form"
+      ]
+    },
+    "separator": {
+      "name": "Separator",
+      "description": "A one-pixel rule that divides content. Built on Radix UI Separator. It stretches to the full width of its container when horizontal and to its full height when vertical, and it is hidden from assistive technology by default — shadcn's wrapper sets decorative to true.",
+      "status": "stable",
+      "whenToUse": "Use to mark a boundary between groups of related content: between sections of a sidebar or a settings page, between a card's header and its body, between inline metadata in a row. Reach for it when spacing alone leaves the grouping ambiguous.",
+      "whenNotToUse": "Do not use a Separator to create breathing room — that is what margin and padding are for. Do not use one to draw a line under a container that already has its own border. Inside a DropdownMenu, Select, or Command list, use that component's own separator part so the divider inherits the menu's spacing and semantics.",
+      "props": {
+        "orientation": {
+          "type": "enum",
+          "propRole": "choice",
+          "values": [
+            {
+              "value": "horizontal",
+              "description": "A full-width rule between stacked sections. The ordinary case."
+            },
+            {
+              "value": "vertical",
+              "description": "A full-height rule between items laid out along a row — toolbars, inline stat groups, button clusters. Needs a container that resolves a height (a flex row with items-stretch, or an explicit height), or it renders as nothing."
+            }
+          ],
+          "default": "horizontal",
+          "description": "The axis the rule divides across. Horizontal separates stacked content; vertical separates content sitting side by side."
+        },
+        "decorative": {
+          "type": "boolean",
+          "propRole": "flag",
+          "default": true,
+          "description": "Whether the rule is purely visual. At the default of true the element renders role=\"none\" and assistive technology skips it entirely. Set it to false when the divider marks a real boundary — the element then renders role=\"separator\", and a vertical one also carries aria-orientation=\"vertical\"."
+        }
+      },
+      "accessibility": {
+        "role": "separator",
+        "labelRequirement": "none",
+        "requiredAttributes": [
+          {
+            "attribute": "decorative",
+            "condition": "when the divider communicates a grouping that is not already conveyed by a heading, a landmark, or list structure",
+            "description": "Pass decorative={false} so the element is exposed as role=\"separator\" instead of role=\"none\". shadcn defaults it to true, which removes the rule from the accessibility tree — correct for ornament, wrong for a real boundary."
+          },
+          {
+            "attribute": "aria-orientation",
+            "condition": "on a vertical separator that is not decorative",
+            "description": "Emitted by the primitive from the orientation prop. Set orientation=\"vertical\" and leave the ARIA attribute alone rather than writing it by hand."
+          }
+        ],
+        "focusManagement": "Separator is never focusable and never enters the tab order; it has no keyboard behaviour of its own.",
+        "notes": "role=\"separator\" without a tabindex is a static separator, not a splitter — never attach drag-to-resize behaviour to it. A divider the user can move is a different control with its own value semantics; use a Resizable handle for that."
+      },
+      "constraints": [
+        {
+          "context": "A boundary between groups of content that is not already conveyed by a heading, landmark, or list",
+          "rule": "Pass decorative={false} so the separator is announced",
+          "severity": "should"
+        },
+        {
+          "context": "A rule that only restates a boundary already conveyed by a heading, a Card edge, or spacing",
+          "rule": "Leave decorative at its default of true so assistive technology skips it",
+          "severity": "should"
+        },
+        {
+          "context": "A vertical separator",
+          "rule": "Give it a container that resolves a height — a flex row with items-stretch, or an explicit height; a vertical separator in an auto-height parent collapses to zero pixels",
+          "severity": "must"
+        },
+        {
+          "context": "Creating visual breathing room between elements",
+          "rule": "Use spacing utilities instead of a Separator",
+          "severity": "must-not"
+        },
+        {
+          "context": "Dividing items inside a DropdownMenu, Select, or Command list",
+          "rule": "Use that component's own separator part instead of a standalone Separator",
+          "severity": "should"
+        },
+        {
+          "context": "A divider the user can drag to resize the panes on either side",
+          "rule": "Use a Resizable handle instead of a Separator, which is neither focusable nor operable",
+          "severity": "must-not"
+        }
+      ],
+      "tokens": [
+        "border"
+      ],
+      "relatedComponents": [
+        "card",
+        "dropdown-menu"
+      ],
+      "tags": [
+        "layout",
+        "divider",
+        "structure",
+        "presentational"
+      ],
+      "categories": [
+        "layout"
+      ]
+    },
+    "avatar": {
+      "name": "Avatar",
+      "description": "A compact, rounded stand-in for a person or entity. Built on Radix UI Avatar: AvatarImage mounts only once the image has actually loaded, and AvatarFallback fills the same box while it is loading or whenever it is missing or broken — so the slot is never empty and the layout never shifts.",
+      "status": "stable",
+      "whenToUse": "Use to identify a person, organisation, or account at a glance: comment authors, assignees in a table row, members in a list, the signed-in user behind a menu trigger. Use AvatarGroup when several participants have to share one slot.",
+      "whenNotToUse": "Do not use Avatar for imagery that is not standing in for an identity — thumbnails, cover art, product photos belong in an AspectRatio or a plain image. Do not make the Avatar itself clickable; wrap it in a Button, a link, or a DropdownMenuTrigger so the control is focusable and named. Do not use an avatar alone to carry status.",
+      "props": {
+        "size": {
+          "type": "enum",
+          "propRole": "dimension",
+          "values": [
+            {
+              "value": "sm",
+              "description": "24px. For dense table rows, inline mentions, and compact toolbars."
+            },
+            {
+              "value": "default",
+              "description": "32px. The standard avatar for lists, comments, and row-level identity."
+            },
+            {
+              "value": "lg",
+              "description": "40px. For profile headers and cards where the person is the subject of the surface."
+            }
+          ],
+          "default": "default",
+          "description": "Preset avatar diameter. AvatarBadge and AvatarGroupCount scale from this value, so change the size here rather than overriding the box with utility classes."
+        }
+      },
+      "accessibility": {
+        "role": "img",
+        "labelRequirement": "required-accessible-name",
+        "requiredAttributes": [
+          {
+            "attribute": "alt",
+            "condition": "on every AvatarImage",
+            "description": "AvatarImage renders a native img. Name the person or entity when the avatar is the only thing identifying them; pass an empty string when their name is already visible beside it, so the identity is not announced twice. The attribute itself is never optional — a missing alt leaves the file name as the accessible name."
+          },
+          {
+            "attribute": "aria-label",
+            "condition": "when the Avatar is the visual for a control — inside a Button, a link, or a DropdownMenuTrigger",
+            "description": "Name the control by what it does (\"Open account menu\"), not by the picture. The wrapping control owns the accessible name; the Avatar inside it should be decorative."
+          }
+        ],
+        "focusManagement": "Avatar is not focusable and takes no part in the tab order. When it is the visual for a control, the wrapping element owns focus and must show the focus ring — the avatar's own rounding should not clip it.",
+        "notes": "AvatarFallback is not a nicety: it is what most users on slow or blocked connections actually see, and what renders whenever the URL 404s. Give it initials or an identifying icon, never an empty box. Initials are a weak identity on their own, so keep the person's name in adjacent text or in the image's alt."
+      },
+      "composition": {
+        "subComponents": [
+          {
+            "id": "avatar-image",
+            "name": "AvatarImage",
+            "description": "The photograph itself, rendered as a native img from the src and alt you pass. Radix keeps it unmounted until the image has loaded successfully, so a slow or broken URL never paints a blank circle; onLoadingStatusChange reports idle, loading, loaded, or error when you need to react to that.",
+            "required": false,
+            "slot": "image",
+            "acceptsChildren": "none",
+            "categories": [
+              "content"
+            ]
+          },
+          {
+            "id": "avatar-fallback",
+            "name": "AvatarFallback",
+            "description": "What occupies the avatar's box while the image loads and whenever it is absent or fails. Holds one or two initials, or an icon. Its delayMs prop holds the fallback back for a moment so a fast image does not flash initials first.",
+            "required": true,
+            "slot": "fallback",
+            "acceptsChildren": "any",
+            "categories": [
+              "content"
+            ]
+          },
+          {
+            "id": "avatar-badge",
+            "name": "AvatarBadge",
+            "description": "A small indicator pinned to the bottom-right of the avatar for presence or status — online, away, verified. It sizes itself from the parent Avatar's size prop. Purely visual: it exposes no accessible name of its own, so the state it signals has to exist in text too.",
+            "required": false,
+            "slot": "badge",
+            "acceptsChildren": "any",
+            "categories": [
+              "content"
+            ]
+          },
+          {
+            "id": "avatar-group",
+            "name": "AvatarGroup",
+            "description": "A row of overlapping Avatars representing several people in a single slot. It inverts the usual nesting — it is a wrapper around Avatar instances rather than a child of one — and applies the overlap and ring treatment to each avatar it holds.",
+            "required": false,
+            "slot": "group",
+            "acceptsChildren": "components",
+            "categories": [
+              "layout"
+            ]
+          },
+          {
+            "id": "avatar-group-count",
+            "name": "AvatarGroupCount",
+            "description": "The trailing counter that closes an AvatarGroup and stands in for the participants not shown, typically written as \"+3\". Matches the size of the avatars beside it and takes text or an icon.",
+            "required": false,
+            "slot": "group-count",
+            "acceptsChildren": "any",
+            "categories": [
+              "content"
+            ]
+          }
+        ],
+        "notes": "An Avatar holds an AvatarImage and an AvatarFallback, optionally followed by an AvatarBadge. The fallback is the required part, not the image: an avatar with no image is ordinary, an avatar with nothing to show when the image fails is a bug. AvatarGroup sits outside this nesting — it is a parent that contains several Avatars, optionally closed by an AvatarGroupCount — so treat it as a sibling concern rather than a slot inside Avatar."
+      },
+      "constraints": [
+        {
+          "context": "Every Avatar",
+          "rule": "Include an AvatarFallback with initials or an identifying icon; the image may never arrive",
+          "severity": "must"
+        },
+        {
+          "context": "An AvatarImage",
+          "rule": "Always pass alt — the person's or entity's name when the avatar identifies them, an empty string when that name is already visible beside it",
+          "severity": "must"
+        },
+        {
+          "context": "An avatar that opens a menu or navigates somewhere",
+          "rule": "Wrap the Avatar in a Button, link, or DropdownMenuTrigger and name that control; do not attach the handler to the Avatar",
+          "severity": "must"
+        },
+        {
+          "context": "Changing the avatar's diameter",
+          "rule": "Use the size prop rather than overriding the box with utility classes, so AvatarBadge and AvatarGroupCount stay in proportion",
+          "severity": "should"
+        },
+        {
+          "context": "Presence or status shown with an AvatarBadge",
+          "rule": "State the status in text as well; the badge is a coloured dot with no accessible name",
+          "severity": "must"
+        },
+        {
+          "context": "Thumbnails, cover art, product photos, or any imagery that is not an identity",
+          "rule": "Use AspectRatio with an image instead of Avatar",
+          "severity": "should-not"
+        },
+        {
+          "context": "More participants than fit the row",
+          "rule": "Cap the visible avatars in an AvatarGroup and close it with an AvatarGroupCount instead of shrinking them all",
+          "severity": "should"
+        }
+      ],
+      "tokens": [
+        "muted",
+        "muted-foreground",
+        "primary",
+        "primary-foreground",
+        "background",
+        "border"
+      ],
+      "relatedComponents": [
+        "badge",
+        "dropdown-menu",
+        "aspect-ratio"
+      ],
+      "tags": [
+        "identity",
+        "media",
+        "display",
+        "user"
+      ],
+      "categories": [
+        "content"
+      ]
+    },
+    "accordion": {
+      "name": "Accordion",
+      "description": "A stack of headings that each reveal a panel of content. Built on Radix UI Accordion. The root decides whether one section or several can be open at a time; each item pairs a trigger — a button inside a heading — with the region that trigger controls.",
+      "status": "stable",
+      "whenToUse": "Use to compress a long page of self-contained sections into a list of headings someone can scan and open selectively: FAQs, grouped settings, order or invoice details, reference documentation. It works when the headings alone are enough to decide what to open, and when the sections are peers rather than steps.",
+      "whenNotToUse": "Do not hide content the reader needs in order to act — pricing, validation errors, required form fields, or anything they must compare across sections. For a single region that shows and hides, use Collapsible; there is no heading list to justify an accordion of one. For mutually exclusive views of the same subject, use Tabs. For content that merely overflows its box, use ScrollArea. For an ordered, multi-step task, use a stepper rather than an accordion.",
+      "props": {
+        "type": {
+          "type": "enum",
+          "propRole": "choice",
+          "required": true,
+          "values": [
+            {
+              "value": "single",
+              "description": "One section open at a time; opening one closes the last. Use when the panels are long enough that two open at once would be hard to read. Pair it with collapsible so the reader can also close everything."
+            },
+            {
+              "value": "multiple",
+              "description": "Sections open and close independently and any number can be open at once. Use when the reader may want to hold several panels open together, such as a settings page or a comparison."
+            }
+          ],
+          "description": "Whether the accordion is a one-at-a-time disclosure or a set of independent ones. Radix requires it — there is no default. It also decides the shape of value and defaultValue: a string when single, an array of strings when multiple."
+        },
+        "collapsible": {
+          "type": "boolean",
+          "propRole": "flag",
+          "default": false,
+          "description": "Only meaningful when type is \"single\". At the default of false one section is always open and clicking the open trigger does nothing; set it to true so the reader can collapse the last open section. It has no effect when type is \"multiple\", where every item can already close."
+        },
+        "defaultValue": {
+          "type": "string | string[]",
+          "propRole": "state",
+          "description": "The item value or values open on first render, for an uncontrolled accordion. A string when type is \"single\", an array when it is \"multiple\". Use it to open the section that answers the reader's most likely question."
+        },
+        "value": {
+          "type": "string | string[]",
+          "propRole": "state",
+          "description": "The open item value or values when you drive the accordion yourself. Pair it with onValueChange. Prefer defaultValue unless something outside the accordion has to open or close sections."
+        },
+        "onValueChange": {
+          "type": "function",
+          "propRole": "handler",
+          "description": "Fires with the new open value or values whenever a section opens or closes. Required for a controlled accordion, and useful on an uncontrolled one for analytics."
+        },
+        "disabled": {
+          "type": "boolean",
+          "propRole": "flag",
+          "default": false,
+          "description": "Disables every trigger in the accordion. When only one section is unavailable, set disabled on that AccordionItem instead."
+        },
+        "orientation": {
+          "type": "enum",
+          "propRole": "choice",
+          "values": [
+            {
+              "value": "vertical",
+              "description": "Stacked headings — the ordinary arrangement. Arrow Up and Arrow Down move between triggers."
+            },
+            {
+              "value": "horizontal",
+              "description": "Triggers arranged along a row. Arrow Left and Arrow Right move between them. Rare: the prop sets the ARIA orientation and the arrow-key mapping, but the visual arrangement is still yours to build, and shadcn's default styles assume vertical."
+            }
+          ],
+          "default": "vertical",
+          "description": "The axis the triggers are arranged along, which decides which arrow keys navigate between them and what aria-orientation the root reports."
+        },
+        "dir": {
+          "type": "enum",
+          "propRole": "choice",
+          "values": [
+            {
+              "value": "ltr",
+              "description": "Left-to-right reading order."
+            },
+            {
+              "value": "rtl",
+              "description": "Right-to-left reading order, which swaps the meaning of Arrow Left and Arrow Right in a horizontal accordion."
+            }
+          ],
+          "default": "ltr",
+          "description": "Reading direction. Inherit it from a DirectionProvider at the root of the app rather than setting it per accordion."
+        }
+      },
+      "accessibility": {
+        "role": "region",
+        "labelRequirement": "required-visible",
+        "requiredAttributes": [
+          {
+            "attribute": "value",
+            "condition": "on every AccordionItem",
+            "description": "A unique, stable string identifying the section. It is the vocabulary value, defaultValue, and onValueChange speak in, and the primitive derives the trigger and panel id wiring from it. Use meaningful slugs rather than positional indexes, so the open section survives reordering and filtering."
+          },
+          {
+            "attribute": "aria-expanded",
+            "condition": "supplied by the primitive on every trigger",
+            "description": "Radix sets it from the open state, alongside aria-controls on the trigger and aria-labelledby on the panel. Do not write these by hand — overriding them desynchronises what is announced from what is visible."
+          }
+        ],
+        "keyboardInteractions": [
+          {
+            "key": "Enter",
+            "description": "When focus is on a trigger, toggles that section."
+          },
+          {
+            "key": "Space",
+            "description": "When focus is on a trigger, toggles that section."
+          },
+          {
+            "key": "Arrow Down",
+            "description": "Moves focus to the next trigger in a vertical accordion."
+          },
+          {
+            "key": "Arrow Up",
+            "description": "Moves focus to the previous trigger in a vertical accordion."
+          },
+          {
+            "key": "Arrow Right",
+            "description": "Moves focus to the next trigger in a horizontal accordion."
+          },
+          {
+            "key": "Arrow Left",
+            "description": "Moves focus to the previous trigger in a horizontal accordion."
+          },
+          {
+            "key": "Home",
+            "description": "Moves focus to the first trigger."
+          },
+          {
+            "key": "End",
+            "description": "Moves focus to the last trigger."
+          },
+          {
+            "key": "Tab",
+            "description": "Moves focus to the next focusable element in the document — the first focusable child of an open panel when there is one, otherwise the next trigger."
+          },
+          {
+            "key": "Shift + Tab",
+            "description": "Moves focus to the previous focusable element."
+          }
+        ],
+        "focusManagement": "Focus stays on the trigger when a section expands or collapses; the panel is never auto-focused, so the reader chooses when to enter it with Tab. Only triggers participate in arrow-key navigation. A closed panel is unmounted, so nothing inside it can hold focus — which is also why in-page anchors and browser find-in-page cannot reach it.",
+        "notes": "The accordion root carries no ARIA role of its own; the semantics live in its parts. Each AccordionTrigger is a button wrapped in Radix's Header, which renders an h3, and each AccordionContent is exposed as a region labelled by its trigger. Because that heading level is fixed at h3 in shadcn's generated component, place the accordion beneath an h2 so the document outline stays ordered. The trigger label is the only thing a screen-reader user has to decide on, so it must describe the panel, not gesture at it."
+      },
+      "composition": {
+        "subComponents": [
+          {
+            "id": "accordion-item",
+            "name": "AccordionItem",
+            "description": "One section: a trigger and the panel it controls. Its required value prop is the section's identity — unique within the accordion and stable across renders. Set disabled here to make a single section unavailable without disabling the whole accordion.",
+            "required": true,
+            "slot": "item",
+            "acceptsChildren": "components",
+            "categories": [
+              "layout"
+            ]
+          },
+          {
+            "id": "accordion-trigger",
+            "name": "AccordionTrigger",
+            "description": "The heading button that opens and closes its section. shadcn renders it inside Radix's Header and appends the chevron that rotates with the open state, so a text label is all it needs from you. Write the label so the reader can decide whether to open the panel from that text alone.",
+            "required": true,
+            "slot": "trigger",
+            "acceptsChildren": "text",
+            "categories": [
+              "interactive"
+            ]
+          },
+          {
+            "id": "accordion-content",
+            "name": "AccordionContent",
+            "description": "The panel a trigger reveals, exposed as a region labelled by that trigger. It is unmounted while closed, so what is inside is invisible to find-in-page, to deep links, and to print. Takes prose, controls, or whole layouts.",
+            "required": true,
+            "slot": "content",
+            "acceptsChildren": "any",
+            "categories": [
+              "content"
+            ]
+          }
+        ],
+        "notes": "An Accordion contains one or more AccordionItems and nothing else directly. Each item holds exactly one AccordionTrigger followed by one AccordionContent, in that order. The heading wrapper around the trigger is rendered for you — do not add your own heading inside AccordionTrigger, and do not nest a button, link, or form control in it, since the trigger is itself a button."
+      },
+      "constraints": [
+        {
+          "context": "Every Accordion",
+          "rule": "Set type explicitly — single when the panels are long and only one should be open, multiple when the sections are independent",
+          "severity": "must"
+        },
+        {
+          "context": "An accordion with type=\"single\"",
+          "rule": "Set collapsible so the reader can close the open section; without it one section is always open",
+          "severity": "should"
+        },
+        {
+          "context": "An accordion with type=\"multiple\"",
+          "rule": "Do not pass collapsible — it has no effect, because every item can already be closed",
+          "severity": "must-not"
+        },
+        {
+          "context": "Every AccordionItem",
+          "rule": "Give it a unique, stable value; positional values break as soon as items are reordered or filtered",
+          "severity": "must"
+        },
+        {
+          "context": "The children of an AccordionItem",
+          "rule": "Include exactly one AccordionTrigger followed by one AccordionContent",
+          "severity": "must"
+        },
+        {
+          "context": "Every AccordionTrigger",
+          "rule": "Give it a visible text label that says what the panel contains",
+          "severity": "must"
+        },
+        {
+          "context": "Buttons, links, or form controls inside an AccordionTrigger",
+          "rule": "Move them into the panel; the trigger is already a button and nested interactive elements are invalid and unreachable",
+          "severity": "must-not"
+        },
+        {
+          "context": "Content that must be reachable by find-in-page, deep link, or print",
+          "rule": "Keep it outside the accordion; closed panels are unmounted",
+          "severity": "must-not"
+        },
+        {
+          "context": "A single region that shows and hides",
+          "rule": "Use Collapsible instead of an accordion with one item",
+          "severity": "should"
+        },
+        {
+          "context": "Mutually exclusive views of the same subject",
+          "rule": "Use Tabs instead of a single-type Accordion",
+          "severity": "should"
+        },
+        {
+          "context": "An accordion placed under a page or section heading",
+          "rule": "Put an h2 above it so the outline stays ordered; the triggers render as h3",
+          "severity": "should"
+        }
+      ],
+      "tokens": [
+        "border",
+        "foreground",
+        "muted-foreground",
+        "ring",
+        "radius"
+      ],
+      "relatedComponents": [
+        "collapsible",
+        "tabs",
+        "card"
+      ],
+      "tags": [
+        "disclosure",
+        "progressive-disclosure",
+        "faq",
+        "content",
+        "interactive"
+      ],
+      "categories": [
+        "interactive"
+      ]
+    },
+    "scroll-area": {
+      "name": "Scroll Area",
+      "description": "A bounded region that scrolls with a styled scrollbar that looks the same in every browser. Built on Radix UI ScrollArea: the content sits in a native overflow viewport, so scrolling itself stays native, while the visible scrollbar is a custom element that overlays the content instead of taking width from it.",
+      "status": "stable",
+      "whenToUse": "Use where a fixed-size box has to hold more content than fits and the platform scrollbar would be intrusive or inconsistent: a sidebar of navigation links, a long list inside a popover or dialog, a log or code panel, a horizontal row of cards. The bounded height or width is what makes it scroll.",
+      "whenNotToUse": "Do not use it for the page itself — the document's own scrolling carries scroll restoration, anchor navigation, browser chrome behaviour, and the scrollbar people expect. Do not use it to tuck away content you would rather not lay out: if the content matters, give it room. For very long or virtualised lists, point the virtualiser at the viewport element or use a native overflow container, since the custom scrollbar has to measure content it does not own.",
+      "props": {
+        "type": {
+          "type": "enum",
+          "propRole": "choice",
+          "values": [
+            {
+              "value": "hover",
+              "description": "Scrollbars appear while the pointer is over the area and fade out after scrolling stops. The default and the quietest — but it tells a reader nothing until they hover."
+            },
+            {
+              "value": "scroll",
+              "description": "Scrollbars appear while the user is scrolling and fade out afterwards. Use when hovering should not reveal chrome, as on a dense dashboard."
+            },
+            {
+              "value": "auto",
+              "description": "Scrollbars are visible whenever the content overflows on that axis, like a traditional desktop scrollbar. Use when the fact that there is more content must always be discoverable."
+            },
+            {
+              "value": "always",
+              "description": "Scrollbars are visible whether or not the content overflows. Use to keep the layout identical across empty, short, and long states."
+            }
+          ],
+          "default": "hover",
+          "description": "When the custom scrollbars are shown. Anything other than auto or always hides the strongest signal that there is more content, so pair hover or scroll with another cue."
+        },
+        "scrollHideDelay": {
+          "type": "number",
+          "propRole": "dimension",
+          "default": 600,
+          "description": "Milliseconds to wait after scrolling stops or the pointer leaves before hiding the scrollbars. Applies only when type is \"hover\" or \"scroll\"."
+        },
+        "dir": {
+          "type": "enum",
+          "propRole": "choice",
+          "values": [
+            {
+              "value": "ltr",
+              "description": "Left-to-right: the vertical scrollbar sits on the right and horizontal content starts at the left edge."
+            },
+            {
+              "value": "rtl",
+              "description": "Right-to-left: the vertical scrollbar moves to the left and horizontal scrolling starts from the right edge."
+            }
+          ],
+          "default": "ltr",
+          "description": "Reading direction, which decides which side the vertical scrollbar sits on and where horizontal scrolling begins. Inherit it from a DirectionProvider where you can."
+        }
+      },
+      "accessibility": {
+        "role": "region",
+        "labelRequirement": "required-accessible-name",
+        "requiredAttributes": [
+          {
+            "attribute": "aria-label",
+            "condition": "when the scroll area holds a distinct body of content — a log, a list, a panel of links — and no visible heading names it",
+            "description": "Props you pass to ScrollArea land on its root element, so name the region there and pair the name with role=\"region\". Without a name, a keyboard user who lands in the scroller is told only that they are in a group."
+          },
+          {
+            "attribute": "aria-labelledby",
+            "condition": "when a visible heading already names the region",
+            "description": "Reference that heading's id instead of repeating the name in aria-label. Use one or the other, never both."
+          },
+          {
+            "attribute": "tabindex",
+            "condition": "when the scrollable content contains no focusable elements of its own and you must support browsers that do not focus scroll containers",
+            "description": "Chrome 127+ and Firefox let the keyboard focus a scroll container with no focusable children — which is why shadcn styles a focus ring on the viewport. Where you cannot rely on that, the viewport needs an explicit tabIndex={0}, and setting it means editing the generated component: props passed to ScrollArea go to the root, not to the viewport that actually scrolls."
+          }
+        ],
+        "keyboardInteractions": [
+          {
+            "key": "Arrow Up / Arrow Down",
+            "description": "Scrolls the viewport by a line when the scroll container has focus. Handled natively by the browser — Radix adds no key handling of its own."
+          },
+          {
+            "key": "Page Up / Page Down",
+            "description": "Scrolls by roughly one viewport height when the scroll container has focus."
+          },
+          {
+            "key": "Home / End",
+            "description": "Jumps to the start or the end of the scrollable content when the scroll container has focus."
+          },
+          {
+            "key": "Tab",
+            "description": "Moves focus through focusable content inside the viewport; the browser scrolls each newly focused element into view."
+          }
+        ],
+        "focusManagement": "The scrollbar and its thumb are pointer-only affordances: they take no focus and answer no keys, so they must never be the only way to reach content. Keyboard scrolling comes from the browser acting on the focused element's scroll container — either something inside the viewport holds focus, or the viewport itself does.",
+        "notes": "Radix deliberately leaves the viewport, scrollbar, thumb, and corner without ARIA roles: the scrolling is native and the bar is decoration over it. That also means an overflowing ScrollArea offers no built-in hint that content continues, so keep an edge fade, a count, or a heading nearby. Never suppress native scrolling in favour of the custom bar."
+      },
+      "composition": {
+        "subComponents": [
+          {
+            "id": "scroll-area-scrollbar",
+            "name": "ScrollBar",
+            "description": "The visible scrollbar track for one axis, exported alongside ScrollArea. A vertical one is rendered inside every ScrollArea for you; add a second as a direct child with orientation=\"horizontal\" when the content scrolls sideways. It renders its own thumb and takes no children.",
+            "required": false,
+            "slot": "scrollbar",
+            "acceptsChildren": "none",
+            "categories": [
+              "interactive"
+            ]
+          },
+          {
+            "id": "scroll-area-thumb",
+            "name": "ScrollAreaThumb",
+            "description": "The draggable indicator inside a scrollbar, sized from the ratio of visible to total content. Every ScrollBar renders one automatically; it is not exported from the generated component and is never authored by hand. Pointer-only — it takes no focus and answers no keys.",
+            "required": false,
+            "slot": "thumb",
+            "acceptsChildren": "none",
+            "categories": [
+              "interactive"
+            ]
+          }
+        ],
+        "notes": "ScrollArea puts whatever you give it inside Radix's Viewport — the element that actually scrolls — and renders a vertical ScrollBar and a Corner beside it. Neither the viewport nor the corner is exported, so the only part you write yourself is an extra ScrollBar with orientation=\"horizontal\". Size comes from the ScrollArea itself: with no bounded box there is no overflow and nothing scrolls."
+      },
+      "constraints": [
+        {
+          "context": "Every ScrollArea",
+          "rule": "Constrain its box — a height for vertical scrolling, a width for horizontal; an area free to grow never overflows and never scrolls",
+          "severity": "must"
+        },
+        {
+          "context": "Content that scrolls horizontally",
+          "rule": "Add a ScrollBar with orientation=\"horizontal\" as a child of the ScrollArea; only the vertical one is rendered for you",
+          "severity": "must"
+        },
+        {
+          "context": "A scrollable region whose content holds no focusable elements",
+          "rule": "Make the region keyboard focusable and give it an accessible name, so its content is reachable without a pointer",
+          "severity": "must"
+        },
+        {
+          "context": "The page's main scroll",
+          "rule": "Use the document's own scrolling instead of wrapping the page in a ScrollArea",
+          "severity": "must-not"
+        },
+        {
+          "context": "A hover or scroll type where noticing the extra content matters",
+          "rule": "Use type=\"auto\", or pair it with another cue such as an edge fade or a visible boundary",
+          "severity": "should"
+        },
+        {
+          "context": "Very long or virtualised lists",
+          "rule": "Point the virtualiser at the viewport element, or use a native overflow container instead",
+          "severity": "should"
+        },
+        {
+          "context": "A ScrollArea nested inside another ScrollArea",
+          "rule": "Restructure so only one region scrolls; nested scroll chains fight over the same wheel and touch gestures",
+          "severity": "should-not"
+        },
+        {
+          "context": "The ScrollBar and its thumb",
+          "rule": "Do not treat them as controls or hang behaviour on them; they are pointer-only decoration over native scrolling",
+          "severity": "must-not"
+        }
+      ],
+      "tokens": [
+        "border",
+        "background",
+        "ring",
+        "radius"
+      ],
+      "relatedComponents": [
+        "table",
+        "separator",
+        "dropdown-menu"
+      ],
+      "tags": [
+        "layout",
+        "overflow",
+        "scrolling",
+        "container"
+      ],
+      "categories": [
+        "layout"
+      ]
+    },
+    "aspect-ratio": {
+      "name": "Aspect Ratio",
+      "description": "A box that holds a fixed width-to-height ratio at any width. Built on Radix UI AspectRatio, which reserves the space up front rather than waiting for the content, so an image, video, or map keeps its slot from the first paint and nothing below it jumps when the asset arrives.",
+      "status": "stable",
+      "whenToUse": "Use to reserve space for media whose intrinsic size you do not control or do not yet know: remote images, video and map embeds, iframes, and the skeletons that stand in for them. Use it across a grid or list so every tile crops to the same shape.",
+      "whenNotToUse": "Do not wrap text or anything that has to grow with its content — a fixed ratio clips or stretches it. Do not use it for media whose intrinsic dimensions are known and stable; set width and height on the element and let the browser reserve the space. For a plain fixed ratio in a modern browser, the CSS aspect-ratio utility (Tailwind's aspect-video, aspect-square) does the same job without a wrapper element.",
+      "props": {
+        "ratio": {
+          "type": "number",
+          "propRole": "dimension",
+          "default": 1,
+          "description": "Width divided by height. Write it as a division — 16 / 9 for video, 4 / 3 for classic photography, 1 for a square, 9 / 16 for portrait — so the intent survives review. Left unset the box is square, which is rarely what the design meant."
+        }
+      },
+      "accessibility": {
+        "labelRequirement": "none",
+        "notes": "AspectRatio is a presentational box: it renders no ARIA role and contributes nothing to the accessibility tree. The content inside keeps its own obligations — an img still needs alt, an iframe still needs a title, a video still needs captions. Because content is usually fitted with object-cover, check that the crop never removes information the reader needs, such as text baked into an image; where it would, use object-contain and accept the letterboxing."
+      },
+      "constraints": [
+        {
+          "context": "Every AspectRatio",
+          "rule": "Set ratio explicitly rather than relying on the 1:1 default",
+          "severity": "should"
+        },
+        {
+          "context": "Media placed inside an AspectRatio",
+          "rule": "Make it fill the box — full height and width with object-cover, or object-contain where cropping would lose meaning; otherwise the reserved space and the media disagree",
+          "severity": "must"
+        },
+        {
+          "context": "Text or any content that must grow with its length",
+          "rule": "Lay it out normally instead of wrapping it in an AspectRatio, which clips at the fixed ratio",
+          "severity": "must-not"
+        },
+        {
+          "context": "Media with known, stable intrinsic dimensions",
+          "rule": "Set width and height on the element and let the browser reserve the space, instead of adding an AspectRatio wrapper",
+          "severity": "should-not"
+        },
+        {
+          "context": "A single fixed ratio in a browser that supports the CSS aspect-ratio property",
+          "rule": "Use the aspect-video or aspect-square utility instead of an AspectRatio wrapper",
+          "severity": "should"
+        },
+        {
+          "context": "An iframe or video embed inside an AspectRatio",
+          "rule": "Keep the embed's own accessible name — a title on the iframe — since AspectRatio supplies none",
+          "severity": "must"
+        },
+        {
+          "context": "An image inside an AspectRatio",
+          "rule": "Give it alt text; the wrapper is invisible to assistive technology",
+          "severity": "must"
+        }
+      ],
+      "relatedComponents": [
+        "avatar",
+        "card"
+      ],
+      "tags": [
+        "layout",
+        "media",
+        "image",
+        "presentational"
+      ],
+      "categories": [
+        "layout"
+      ]
+    },
+    "tabs": {
+      "name": "Tabs",
+      "description": "A set of layered content panels where only one is visible at a time, selected by a trigger in a tablist. Built on Radix UI Tabs: the root generates the ids that pair each trigger with its panel, wires aria-controls and aria-labelledby between them, applies a roving tabindex across the tablist, and reflects the selection with data-state=\"active\". shadcn adds styling, plus a variant prop on TabsList.",
+      "status": "stable",
+      "whenToUse": "Use when one subject has several peer views that a user switches between and rarely needs side by side: sections of a settings page, an entity's Overview / Activity / Members, a code-and-preview toggle. Tabs suit a small, stable set of short labels that fit on one line, over panels whose content is already loaded or cheap to fetch.",
+      "whenNotToUse": "Do not use Tabs to move between routes or pages. A tablist is a widget, not site navigation: use links, NavigationMenu, or a sidebar so history, the back button, and open-in-new-tab keep working. Do not use Tabs for ordered steps in a flow (use a stepper) or for content the reader must compare or read together (lay it out together). When labels wrap, when the set outgrows a single row, or when panels hold long-form prose, prefer Accordion, a Select, or in-page navigation.",
+      "props": {
+        "value": {
+          "type": "string",
+          "propRole": "state",
+          "description": "The value of the selected tab in controlled mode. While this is set the component never changes panels on its own; the app must respond to onValueChange."
+        },
+        "defaultValue": {
+          "type": "string",
+          "propRole": "state",
+          "description": "The tab selected on first render in uncontrolled mode. Supply this or value: with neither, nothing is selected and every panel stays hidden."
+        },
+        "onValueChange": {
+          "type": "function",
+          "propRole": "handler",
+          "description": "Called with the newly selected tab's value whenever the selection changes. Required alongside value in controlled mode."
+        },
+        "orientation": {
+          "type": "enum",
+          "propRole": "choice",
+          "values": [
+            {
+              "value": "horizontal",
+              "description": "Triggers sit in a row above their panels and Left/Right arrows move between them. The default, and the right choice for most tab sets."
+            },
+            {
+              "value": "vertical",
+              "description": "Triggers stack in a column beside the panel, Up/Down arrows move between them, and the tablist is exposed with aria-orientation=\"vertical\". Use for a side rail of sections next to a wide panel."
+            }
+          ],
+          "default": "horizontal",
+          "description": "Layout axis of the tablist. This also decides which arrow keys traverse the triggers, so it must match how the triggers are actually laid out."
+        },
+        "dir": {
+          "type": "enum",
+          "propRole": "choice",
+          "values": [
+            {
+              "value": "ltr",
+              "description": "Left-to-right: Arrow Right advances to the next trigger."
+            },
+            {
+              "value": "rtl",
+              "description": "Right-to-left: Arrow Left advances to the next trigger."
+            }
+          ],
+          "description": "Reading direction of the tablist, which determines which arrow key advances. Inherited from an ancestor Radix DirectionProvider when omitted; set it explicitly only when this tab set reads in a different direction from the page."
+        },
+        "activationMode": {
+          "type": "enum",
+          "propRole": "choice",
+          "values": [
+            {
+              "value": "automatic",
+              "description": "Moving focus with the arrow keys selects that tab immediately. Correct whenever panels appear without noticeable latency; this is the behavior the WAI-ARIA tabs pattern recommends."
+            },
+            {
+              "value": "manual",
+              "description": "Arrow keys move focus without changing the panel, and the user presses Enter or Space to select. Use when selecting a tab is expensive, such as a fetch or a heavy mount, so traversing the tablist does not fire one request per tab."
+            }
+          ],
+          "default": "automatic",
+          "description": "Whether arrow-key focus also selects. Switch to manual only when automatic selection would be slow enough to punish keyboard traversal."
+        },
+        "asChild": {
+          "type": "boolean",
+          "propRole": "flag",
+          "default": false,
+          "description": "Merges the root's props onto its single child element instead of rendering a div. Rarely needed; the root carries no semantics of its own."
+        }
+      },
+      "accessibility": {
+        "role": "tablist",
+        "requiredAttributes": [
+          {
+            "attribute": "aria-label",
+            "condition": "on TabsList when no visible heading names the tab set",
+            "description": "Name the tablist so its purpose is announced when a screen reader user reaches it. Name what the tabs are for; the tablist role is already announced, so do not repeat the word \"tabs\"."
+          },
+          {
+            "attribute": "aria-labelledby",
+            "condition": "on TabsList when a visible heading already names the tab set",
+            "description": "Reference the id of that heading rather than duplicating its text in aria-label. Use one or the other, never both."
+          },
+          {
+            "attribute": "aria-label",
+            "condition": "on a TabsTrigger whose content is an icon with no visible text",
+            "description": "Give the trigger a text name. An icon-only trigger is otherwise announced as an unnamed tab."
+          }
+        ],
+        "keyboardInteractions": [
+          {
+            "key": "Tab",
+            "description": "Moves focus into the tablist, landing on the selected trigger: the whole tablist is one tab stop, not one per tab. From the selected trigger, Tab moves into the active panel, which Radix makes focusable so panels holding no controls of their own are still reachable."
+          },
+          {
+            "key": "Arrow Right",
+            "description": "Moves focus to the next trigger in a horizontal tablist (the previous one when dir is rtl), wrapping at the end while TabsList loop is true. In automatic activation mode the panel changes with focus."
+          },
+          {
+            "key": "Arrow Left",
+            "description": "Moves focus to the previous trigger in a horizontal tablist (the next one when dir is rtl), wrapping at the start while TabsList loop is true."
+          },
+          {
+            "key": "Arrow Down",
+            "description": "Moves focus to the next trigger in a vertical tablist, wrapping at the end while TabsList loop is true."
+          },
+          {
+            "key": "Arrow Up",
+            "description": "Moves focus to the previous trigger in a vertical tablist, wrapping at the start while TabsList loop is true."
+          },
+          {
+            "key": "Home",
+            "description": "Moves focus to the first trigger in the tablist."
+          },
+          {
+            "key": "End",
+            "description": "Moves focus to the last trigger in the tablist."
+          },
+          {
+            "key": "Enter",
+            "description": "Selects the focused trigger. Only meaningful when activationMode is manual; under automatic activation the tab is already selected."
+          },
+          {
+            "key": "Space",
+            "description": "Selects the focused trigger. Only meaningful when activationMode is manual; under automatic activation the tab is already selected."
+          }
+        ],
+        "focusManagement": "The tablist is a single tab stop with roving tabindex: only the selected trigger is reachable with Tab, and arrow keys move focus among the others. Triggers marked disabled are skipped by arrow traversal. Radix gives the active TabsContent tabindex=\"0\", so Tab from the selected trigger lands inside the panel even when the panel contains nothing focusable, and Shift+Tab from the panel returns to the selected trigger. The selection lives in component state and not in the URL, so a reload or a shared link returns to defaultValue unless the app lifts the value into routing state.",
+        "labelRequirement": "required-accessible-name",
+        "notes": "Radix generates the id, aria-controls, and aria-labelledby pairing between each trigger and its panel from the shared value; do not hand-author or override those attributes. Unselected panels are unmounted (or, with forceMount, present but hidden), so their content is absent from the accessibility tree, from in-page find, and from print output. Content that must be findable, printable, or comparable does not belong behind a tab."
+      },
+      "composition": {
+        "subComponents": [
+          {
+            "id": "tabs-list",
+            "name": "TabsList",
+            "description": "The tablist: the single-tab-stop container that holds the triggers. Renders Radix Tabs.List with role=\"tablist\" and aria-orientation taken from the root's orientation, and carries the accessible name for the tab set.",
+            "required": true,
+            "slot": "tablist",
+            "acceptsChildren": "components",
+            "props": {
+              "variant": {
+                "type": "enum",
+                "propRole": "choice",
+                "values": [
+                  {
+                    "value": "default",
+                    "description": "A filled, segmented control on a muted background. Use inside cards and panels where the tab set needs a contained shape."
+                  },
+                  {
+                    "value": "line",
+                    "description": "Transparent triggers with an underline marking the selection. Use at the top of a page or section where a filled control would read as too heavy."
+                  }
+                ],
+                "default": "default",
+                "description": "Visual treatment of the tablist, applied to the triggers through a data attribute."
+              },
+              "loop": {
+                "type": "boolean",
+                "propRole": "flag",
+                "default": true,
+                "description": "Whether arrow-key focus wraps from the last trigger to the first and back. Leave it on unless the ends of the tablist must feel like hard stops."
+              },
+              "asChild": {
+                "type": "boolean",
+                "propRole": "flag",
+                "default": false,
+                "description": "Merges the tablist's props and role onto its single child element instead of rendering a div."
+              }
+            }
+          },
+          {
+            "id": "tabs-trigger",
+            "name": "TabsTrigger",
+            "description": "One tab. Renders a real button with role=\"tab\", aria-selected, and aria-controls pointing at the panel whose value matches its own. The value prop is the join key with TabsContent.",
+            "required": true,
+            "slot": "trigger",
+            "acceptsChildren": "any",
+            "categories": [
+              "interactive"
+            ],
+            "props": {
+              "value": {
+                "type": "string",
+                "propRole": "state",
+                "required": true,
+                "description": "Identifies this tab and joins it to the TabsContent carrying the same value. Must be unique within the tab set."
+              },
+              "disabled": {
+                "type": "boolean",
+                "propRole": "flag",
+                "default": false,
+                "description": "Makes the tab unselectable and removes it from arrow-key traversal. Prefer omitting a tab entirely over showing a permanently disabled one; a disabled tab with no explanation is a dead end."
+              },
+              "asChild": {
+                "type": "boolean",
+                "propRole": "flag",
+                "default": false,
+                "description": "Merges the trigger's props, role, and behavior onto its single child element instead of rendering a button. The child must still be a control that can receive focus."
+              }
+            }
+          },
+          {
+            "id": "tabs-content",
+            "name": "TabsContent",
+            "description": "The panel belonging to one tab. Renders with role=\"tabpanel\" and aria-labelledby pointing back at its trigger, and is mounted only while its value is selected unless forceMount is set.",
+            "required": true,
+            "slot": "content",
+            "acceptsChildren": "any",
+            "props": {
+              "value": {
+                "type": "string",
+                "propRole": "state",
+                "required": true,
+                "description": "Joins this panel to the TabsTrigger carrying the same value. A panel whose value matches no trigger never renders."
+              },
+              "forceMount": {
+                "type": "boolean",
+                "propRole": "flag",
+                "description": "Keeps the panel mounted while it is hidden instead of unmounting it on switch. Use it to preserve state that would otherwise be lost, such as a partly filled form or a scroll position, or to hand an animation library control of the exit."
+              },
+              "asChild": {
+                "type": "boolean",
+                "propRole": "flag",
+                "default": false,
+                "description": "Merges the panel's props and role onto its single child element instead of rendering a div."
+              }
+            }
+          }
+        ],
+        "requiredChildren": [
+          "tabs-list",
+          "tabs-trigger",
+          "tabs-content"
+        ],
+        "allowedChildren": [
+          "tabs-list",
+          "tabs-content"
+        ],
+        "notes": "TabsContent is a sibling of TabsList inside the root, never a child of it: the tablist holds only triggers. Every TabsTrigger value must match exactly one TabsContent value, and vice versa; an unmatched trigger selects nothing and an unmatched panel never appears. Keep the DOM order of the panels aligned with the order of their triggers so tab order and reading order agree."
+      },
+      "constraints": [
+        {
+          "context": "One subject with several peer views the user switches between",
+          "rule": "Use Tabs",
+          "severity": "should"
+        },
+        {
+          "context": "Moving between routes, pages, or views the user should be able to link to, bookmark, or reach with the back button",
+          "rule": "Use links or NavigationMenu instead of Tabs",
+          "severity": "must-not"
+        },
+        {
+          "context": "Any Tabs root",
+          "rule": "Supply defaultValue, or value together with onValueChange; with neither, no tab is selected and every panel is hidden",
+          "severity": "must"
+        },
+        {
+          "context": "Every TabsTrigger and TabsContent pair",
+          "rule": "Give them the same value, unique within the tab set, so the trigger's aria-controls resolves to a real panel",
+          "severity": "must"
+        },
+        {
+          "context": "The tab set has no visible heading that names it",
+          "rule": "Give TabsList an accessible name with aria-label, or point aria-labelledby at the heading that names it",
+          "severity": "must"
+        },
+        {
+          "context": "Selecting a tab starts a network request or mounts an expensive view",
+          "rule": "Set activationMode=\"manual\" so arrow-key traversal does not fire one request per tab",
+          "severity": "should"
+        },
+        {
+          "context": "Content that must be reachable by in-page search, printable, or comparable side by side",
+          "rule": "Do not place it in a tab panel; unselected panels are unmounted, and forceMount only keeps them hidden",
+          "severity": "must-not"
+        },
+        {
+          "context": "Panel state that must survive switching away and back, such as a partly filled form",
+          "rule": "Set forceMount on that TabsContent so the panel stays mounted while hidden",
+          "severity": "should"
+        },
+        {
+          "context": "Ordered steps in a flow the user works through once",
+          "rule": "Use a stepper or wizard rather than Tabs",
+          "severity": "should-not"
+        },
+        {
+          "context": "A Tabs root placed inside another Tabs panel",
+          "rule": "Avoid a second level of tabs; restructure the page or use an Accordion inside the panel",
+          "severity": "should-not"
+        },
+        {
+          "context": "The tablist is laid out vertically",
+          "rule": "Set orientation=\"vertical\" so arrow-key traversal and aria-orientation match what is on screen",
+          "severity": "must"
+        }
+      ],
+      "tokens": [
+        "background",
+        "foreground",
+        "muted",
+        "muted-foreground",
+        "border",
+        "ring",
+        "radius"
+      ],
+      "relatedComponents": [
+        "accordion",
+        "card",
+        "navigation-menu"
+      ],
+      "tags": [
+        "navigation",
+        "tabs",
+        "panels",
+        "disclosure",
+        "interactive"
+      ],
+      "categories": [
+        "navigation",
+        "interactive"
+      ]
+    },
+    "breadcrumb": {
+      "name": "Breadcrumb",
+      "description": "A trail of links showing where the current page sits in a hierarchy, ending in the current page itself. Renders a nav landmark labelled \"breadcrumb\" around an ordered list: ancestors are BreadcrumbLink anchors, the final crumb is a BreadcrumbPage, and decorative BreadcrumbSeparator items sit between them. The trail is authored by hand; the component does not read the router or derive itself from the URL.",
+      "status": "stable",
+      "whenToUse": "Use on pages two or more levels deep in a hierarchy the user can actually navigate up: documentation sections, category to subcategory to product, workspace to project to resource. A breadcrumb answers \"where am I\" and offers one-click ascent to any ancestor, which is most valuable on detail views people arrive at from search or a deep link.",
+      "whenNotToUse": "Do not use a breadcrumb as a site's primary navigation, and do not use one on a flat site or a single-level hierarchy where a \"Back to X\" link says the same thing with less furniture. Do not use it to show where the user has been; a breadcrumb reflects the structure of the site, not the path the user took. Do not use it for progress through a multi-step flow (use a stepper) or for switching between peer views (use Tabs).",
+      "props": {
+        "aria-label": {
+          "type": "string",
+          "propRole": "content",
+          "default": "breadcrumb",
+          "description": "The accessible name of the nav landmark, preset to \"breadcrumb\". Override it only to localize the label or to distinguish this trail when the page carries more than one navigation landmark."
+        }
+      },
+      "accessibility": {
+        "role": "navigation",
+        "requiredAttributes": [
+          {
+            "attribute": "href",
+            "condition": "on every BreadcrumbLink",
+            "description": "BreadcrumbLink renders a bare anchor. Without href it is neither focusable nor announced as a link, so a click handler on it is unreachable from the keyboard. Give it the ancestor's URL, or set asChild and pass a router link that renders one."
+          },
+          {
+            "attribute": "aria-current",
+            "condition": "on the crumb representing the current page",
+            "description": "Supplied automatically by BreadcrumbPage as aria-current=\"page\", alongside role=\"link\" and aria-disabled=\"true\". Exactly one crumb carries it and it is the last one; never add aria-current to the ancestor links."
+          },
+          {
+            "attribute": "aria-label",
+            "condition": "when BreadcrumbEllipsis is used as the visible content of a trigger, such as a DropdownMenuTrigger",
+            "description": "The ellipsis is aria-hidden and contributes no accessible name, so the trigger would otherwise be announced as unnamed. Give the trigger its own name with aria-label or a visually hidden span; shadcn's example uses a span reading \"Toggle menu\"."
+          }
+        ],
+        "keyboardInteractions": [
+          {
+            "key": "Tab",
+            "description": "Moves to the next crumb link. Every link is its own tab stop: a breadcrumb has no roving focus and no arrow-key navigation, because it is a list of links rather than a composite widget."
+          },
+          {
+            "key": "Enter",
+            "description": "Follows the focused crumb link. Space does not activate an anchor; that is native link behavior, not a gap in the component."
+          }
+        ],
+        "focusManagement": "Nothing is trapped or moved: focus follows document order through the crumb links. BreadcrumbPage is deliberately not focusable, because the current page is not a destination. When collapsed crumbs are opened from a DropdownMenu, that menu owns focus while open and returns it to its trigger on close.",
+        "labelRequirement": "required-accessible-name",
+        "notes": "BreadcrumbList is an ordered list because the order of the crumbs carries meaning; never reorder crumbs for visual balance and never let a separator carry meaning, since separators are role=\"presentation\" and aria-hidden=\"true\". BreadcrumbPage renders a span with role=\"link\" and aria-disabled=\"true\" rather than an anchor, so the current page is announced in the trail without inviting a navigation that goes nowhere. BreadcrumbEllipsis is aria-hidden in its entirety, so the visually hidden \"More\" text inside it is never announced; treat the glyph as decoration and put the real affordance on the control that wraps it."
+      },
+      "composition": {
+        "subComponents": [
+          {
+            "id": "breadcrumb-list",
+            "name": "BreadcrumbList",
+            "description": "The ordered list (ol) holding the trail. Wraps onto more than one line when the trail is long, so a wrapping trail is a signal to collapse rather than to shrink the type.",
+            "required": true,
+            "slot": "list",
+            "acceptsChildren": "components"
+          },
+          {
+            "id": "breadcrumb-item",
+            "name": "BreadcrumbItem",
+            "description": "One entry in the trail, rendered as an li. Holds a BreadcrumbLink, a BreadcrumbPage, or a collapse control such as a DropdownMenu wrapping BreadcrumbEllipsis.",
+            "required": true,
+            "slot": "item",
+            "acceptsChildren": "any"
+          },
+          {
+            "id": "breadcrumb-link",
+            "name": "BreadcrumbLink",
+            "description": "A link to an ancestor. Renders an anchor by default; set asChild to hand rendering to a routing library's link component so client-side navigation is preserved.",
+            "slot": "link",
+            "acceptsChildren": "any",
+            "categories": [
+              "interactive"
+            ],
+            "props": {
+              "href": {
+                "type": "string",
+                "propRole": "content",
+                "description": "The ancestor's URL. Required for the crumb to be focusable and announced as a link, unless asChild is set and the child supplies its own destination."
+              },
+              "asChild": {
+                "type": "boolean",
+                "propRole": "flag",
+                "default": false,
+                "description": "Renders the link's props and styling onto its single child instead of an anchor, so a router link such as Next.js Link or React Router Link can take over navigation."
+              }
+            }
+          },
+          {
+            "id": "breadcrumb-page",
+            "name": "BreadcrumbPage",
+            "description": "The final crumb: the page the user is on. Renders a span carrying role=\"link\", aria-disabled=\"true\", and aria-current=\"page\", and is deliberately not a link. Exactly one per trail, always last.",
+            "required": true,
+            "slot": "current",
+            "acceptsChildren": "text"
+          },
+          {
+            "id": "breadcrumb-separator",
+            "name": "BreadcrumbSeparator",
+            "description": "The divider between crumbs, rendered as an li with role=\"presentation\" and aria-hidden=\"true\". Defaults to a chevron; pass children to substitute another glyph such as a slash.",
+            "slot": "separator",
+            "acceptsChildren": "any"
+          },
+          {
+            "id": "breadcrumb-ellipsis",
+            "name": "BreadcrumbEllipsis",
+            "description": "The collapsed-crumbs indicator: an aria-hidden span holding a horizontal-ellipsis icon. It is decoration and is not focusable, so wrap it in a DropdownMenu or Drawer trigger that carries its own accessible name to make the hidden ancestors reachable.",
+            "slot": "ellipsis",
+            "acceptsChildren": "none"
+          }
+        ],
+        "requiredChildren": [
+          "breadcrumb-list",
+          "breadcrumb-item",
+          "breadcrumb-page"
+        ],
+        "allowedChildren": [
+          "breadcrumb-list"
+        ],
+        "notes": "Breadcrumb takes exactly one BreadcrumbList, and every crumb and separator is an li inside it: nothing may sit between the ol and its li children. Order the crumbs root first and end with a single BreadcrumbPage. When the trail outgrows its container, replace the middle crumbs with one BreadcrumbEllipsis inside a DropdownMenu rather than truncating labels, keeping the root and the current page visible."
+      },
+      "constraints": [
+        {
+          "context": "A page two or more levels deep in a navigable hierarchy",
+          "rule": "Use Breadcrumb to show the path and offer one-click ascent to each ancestor",
+          "severity": "should"
+        },
+        {
+          "context": "The last crumb, representing the page being viewed",
+          "rule": "Use BreadcrumbPage rather than BreadcrumbLink; the current page must not link to itself",
+          "severity": "must"
+        },
+        {
+          "context": "Any breadcrumb trail",
+          "rule": "Include exactly one BreadcrumbPage, as the final item, so exactly one crumb carries aria-current=\"page\"",
+          "severity": "must"
+        },
+        {
+          "context": "Every BreadcrumbLink",
+          "rule": "Give it an href, or set asChild and pass a link that renders one; an anchor without href is not focusable and is not announced as a link",
+          "severity": "must"
+        },
+        {
+          "context": "An app using client-side routing",
+          "rule": "Set asChild on BreadcrumbLink and pass the router's link component instead of a bare anchor, so ascending the trail does not force a full page load",
+          "severity": "should"
+        },
+        {
+          "context": "The visual divider between crumbs",
+          "rule": "Do not put meaning in BreadcrumbSeparator; it is aria-hidden and never announced",
+          "severity": "must-not"
+        },
+        {
+          "context": "A trail too long for its container",
+          "rule": "Collapse the middle crumbs behind a BreadcrumbEllipsis inside a DropdownMenu, keeping the root and the current page visible",
+          "severity": "should"
+        },
+        {
+          "context": "Reaching the ancestors hidden behind a collapsed trail",
+          "rule": "Do not treat BreadcrumbEllipsis as the affordance; it is aria-hidden and not focusable, so wrap it in a real trigger that carries its own accessible name",
+          "severity": "must-not"
+        },
+        {
+          "context": "Showing the sequence of pages the user visited",
+          "rule": "Do not use Breadcrumb; it reflects site structure, not browsing history",
+          "severity": "must-not"
+        },
+        {
+          "context": "Progress through a multi-step flow",
+          "rule": "Use a stepper instead of Breadcrumb",
+          "severity": "should-not"
+        },
+        {
+          "context": "A site with a flat structure or a single level above the current page",
+          "rule": "Prefer a single \"Back to X\" link over a breadcrumb",
+          "severity": "should"
+        }
+      ],
+      "tokens": [
+        "foreground",
+        "muted-foreground"
+      ],
+      "relatedComponents": [
+        "navigation-menu",
+        "dropdown-menu",
+        "separator"
+      ],
+      "tags": [
+        "navigation",
+        "wayfinding",
+        "hierarchy",
+        "links"
+      ],
+      "categories": [
+        "navigation"
+      ]
+    },
+    "pagination": {
+      "name": "Pagination",
+      "description": "Page-by-page navigation for a paged collection: previous and next controls, numbered page links, and an ellipsis marking the pages skipped between them. Renders a nav landmark labelled \"pagination\" around an unordered list. The links are anchors styled with buttonVariants, and the component holds no state: the current page, the page count, and each page's href are supplied by the app.",
+      "status": "stable",
+      "whenToUse": "Use when a collection is served in discrete, addressable pages and the user benefits from jumping directly to one: search results, a table of records, an archive. Numbered links earn their space when a page can be linked to, bookmarked, and returned to with the back button, and when knowing how many pages exist is itself useful information.",
+      "whenNotToUse": "Do not use Pagination for a feed that is read continuously; infinite scroll or a \"Load more\" button fits that reading pattern better. Do not render numbered links over a cursor-based API that cannot address page N, since the numbers would point nowhere. Do not use it to switch between unrelated views (that is Tabs) or to step through a wizard (that is a stepper).",
+      "props": {
+        "aria-label": {
+          "type": "string",
+          "propRole": "content",
+          "default": "pagination",
+          "description": "The accessible name of the nav landmark, preset to \"pagination\". Override it to localize the label, or to tell two pagers apart when a page has controls both above and below a table."
+        }
+      },
+      "accessibility": {
+        "role": "navigation",
+        "requiredAttributes": [
+          {
+            "attribute": "href",
+            "condition": "on every PaginationLink, PaginationPrevious, and PaginationNext",
+            "description": "These render bare anchors. Without href they are not focusable and not announced as links, so a click handler attached to them cannot be reached from the keyboard. Give each the URL of the page it targets."
+          },
+          {
+            "attribute": "aria-current",
+            "condition": "on the link for the page currently being viewed",
+            "description": "Set isActive on that PaginationLink; it applies aria-current=\"page\" along with a data-active attribute and the outline styling. Exactly one link in a pager may carry it."
+          },
+          {
+            "attribute": "aria-disabled",
+            "condition": "on PaginationPrevious at the first page, or PaginationNext at the last",
+            "description": "An anchor cannot be disabled. Drop the href and set aria-disabled=\"true\" (removing pointer events in styling), or render a disabled Button in that item, so the control is announced as unavailable instead of leading nowhere."
+          },
+          {
+            "attribute": "aria-label",
+            "condition": "when the page contains more than one pagination landmark",
+            "description": "Override the nav's aria-label on each pager so the two landmarks can be told apart in a screen reader's landmark list."
+          }
+        ],
+        "keyboardInteractions": [
+          {
+            "key": "Tab",
+            "description": "Moves to the next control in the pager. Every link is its own tab stop: the pager has no roving focus and no arrow-key navigation, because it is a list of links rather than a composite widget."
+          },
+          {
+            "key": "Enter",
+            "description": "Follows the focused link. Space does not activate an anchor; that is native link behavior, not a gap in the component."
+          }
+        ],
+        "focusManagement": "The component moves no focus of its own. When a page change re-renders the results in place rather than navigating, focus is dropped to the document: send it to the results region or its heading and announce the change, or keyboard and screen reader users are left with no signal that anything happened. A real navigation to a new URL needs none of this. Keep the pager's DOM position stable across page changes so the tab order does not shift under the user.",
+        "labelRequirement": "required-accessible-name",
+        "notes": "PaginationPrevious and PaginationNext ship with aria-label values of \"Go to previous page\" and \"Go to next page\" because their visible text is hidden below the sm breakpoint, leaving an icon alone on small screens; localize those labels rather than removing them. PaginationEllipsis is aria-hidden in its entirety, so the visually hidden \"More pages\" text inside it is never announced. Let each numbered link's text be the page number so its accessible name distinguishes it from its neighbors."
+      },
+      "composition": {
+        "subComponents": [
+          {
+            "id": "pagination-content",
+            "name": "PaginationContent",
+            "description": "The unordered list (ul) that holds the pager's items, laid out in a row.",
+            "required": true,
+            "slot": "list",
+            "acceptsChildren": "components"
+          },
+          {
+            "id": "pagination-item",
+            "name": "PaginationItem",
+            "description": "One entry in the pager, rendered as an li. Every control belongs in one, including the ellipsis, because only li elements may be children of the ul.",
+            "required": true,
+            "slot": "item",
+            "acceptsChildren": "any"
+          },
+          {
+            "id": "pagination-link",
+            "name": "PaginationLink",
+            "description": "A link to a specific page. Renders an anchor styled with buttonVariants, outline while active and ghost otherwise, and applies aria-current=\"page\" when isActive is set.",
+            "slot": "page",
+            "acceptsChildren": "any",
+            "categories": [
+              "interactive"
+            ],
+            "props": {
+              "href": {
+                "type": "string",
+                "propRole": "content",
+                "description": "The URL of the page this link targets. Required for the control to be focusable and announced as a link."
+              },
+              "isActive": {
+                "type": "boolean",
+                "propRole": "state",
+                "default": false,
+                "description": "Marks this link as the page currently being viewed. Applies aria-current=\"page\" and switches the styling from ghost to outline. Exactly one link in a pager may set it."
+              },
+              "size": {
+                "type": "enum",
+                "propRole": "dimension",
+                "values": [
+                  {
+                    "value": "icon",
+                    "description": "Square, sized for a single page number. The default, and what numbered links use."
+                  },
+                  {
+                    "value": "default",
+                    "description": "Standard button width for a link with a text label. What PaginationPrevious and PaginationNext use."
+                  },
+                  {
+                    "value": "sm",
+                    "description": "Compact height for a pager sitting inside a dense toolbar or table footer."
+                  },
+                  {
+                    "value": "lg",
+                    "description": "Large height for a pager that needs a bigger touch target."
+                  }
+                ],
+                "default": "icon",
+                "description": "Button size token passed through to buttonVariants. Keep one size across every control in a pager so the row stays on a single baseline."
+              }
+            }
+          },
+          {
+            "id": "pagination-previous",
+            "name": "PaginationPrevious",
+            "description": "The link to the preceding page: a PaginationLink preset to size=\"default\" with a left chevron, the label \"Previous\" (hidden below the sm breakpoint), and aria-label=\"Go to previous page\". Its content is fixed, so customization happens through props rather than children.",
+            "slot": "previous",
+            "acceptsChildren": "none",
+            "categories": [
+              "interactive"
+            ],
+            "props": {
+              "href": {
+                "type": "string",
+                "propRole": "content",
+                "description": "The URL of the preceding page. Omit it, and set aria-disabled=\"true\", when the user is already on the first page."
+              },
+              "aria-label": {
+                "type": "string",
+                "propRole": "content",
+                "default": "Go to previous page",
+                "description": "The control's accessible name, which carries the whole meaning on small screens where the visible \"Previous\" text is hidden. Override it to localize, never to remove it."
+              }
+            }
+          },
+          {
+            "id": "pagination-next",
+            "name": "PaginationNext",
+            "description": "The link to the following page: a PaginationLink preset to size=\"default\" with a right chevron, the label \"Next\" (hidden below the sm breakpoint), and aria-label=\"Go to next page\". Its content is fixed, so customization happens through props rather than children.",
+            "slot": "next",
+            "acceptsChildren": "none",
+            "categories": [
+              "interactive"
+            ],
+            "props": {
+              "href": {
+                "type": "string",
+                "propRole": "content",
+                "description": "The URL of the following page. Omit it, and set aria-disabled=\"true\", when the user is already on the last page."
+              },
+              "aria-label": {
+                "type": "string",
+                "propRole": "content",
+                "default": "Go to next page",
+                "description": "The control's accessible name, which carries the whole meaning on small screens where the visible \"Next\" text is hidden. Override it to localize, never to remove it."
+              }
+            }
+          },
+          {
+            "id": "pagination-ellipsis",
+            "name": "PaginationEllipsis",
+            "description": "The gap marker standing in for the pages between two non-consecutive numbers. Renders an aria-hidden span holding a horizontal-ellipsis icon; it is decoration, is not focusable, and is never announced.",
+            "slot": "ellipsis",
+            "acceptsChildren": "none"
+          }
+        ],
+        "requiredChildren": [
+          "pagination-content",
+          "pagination-item"
+        ],
+        "allowedChildren": [
+          "pagination-content"
+        ],
+        "notes": "Pagination takes exactly one PaginationContent, and every control sits in its own PaginationItem because PaginationContent is a ul. Order the items as previous, then the page links with any ellipses between them, then next, and keep the set of visible numbers stable in size as the user moves through the range so the controls do not shift under the pointer."
+      },
+      "constraints": [
+        {
+          "context": "A collection served in addressable pages the user may want to jump into, bookmark, or share",
+          "rule": "Use Pagination with a real href for every page",
+          "severity": "should"
+        },
+        {
+          "context": "Every PaginationLink, PaginationPrevious, and PaginationNext",
+          "rule": "Give it an href; an anchor without one is not focusable and its click handler is unreachable from the keyboard",
+          "severity": "must"
+        },
+        {
+          "context": "Client-side pagination with no URL per page",
+          "rule": "Encode the page in the URL, a query parameter is enough, rather than wiring onClick to an anchor with no href; where a page genuinely cannot be addressed, render Buttons in the items instead of PaginationLink",
+          "severity": "should"
+        },
+        {
+          "context": "The link for the page currently being viewed",
+          "rule": "Mark exactly one link isActive so exactly one control carries aria-current=\"page\"",
+          "severity": "must"
+        },
+        {
+          "context": "Previous on the first page, or Next on the last",
+          "rule": "Do not leave a live link that goes nowhere; drop the href and set aria-disabled=\"true\", or render a disabled Button in that item",
+          "severity": "must-not"
+        },
+        {
+          "context": "Direct children of PaginationContent",
+          "rule": "Wrap every control, including PaginationEllipsis, in a PaginationItem, because PaginationContent renders a ul",
+          "severity": "must"
+        },
+        {
+          "context": "A pager repeated above and below the same collection",
+          "rule": "Give each nav a distinct aria-label so the two landmarks can be told apart",
+          "severity": "should"
+        },
+        {
+          "context": "A run of pages omitted between two visible numbers",
+          "rule": "Mark the gap with PaginationEllipsis rather than letting the numbers jump silently",
+          "severity": "should"
+        },
+        {
+          "context": "Reaching the pages hidden behind an ellipsis",
+          "rule": "Do not treat PaginationEllipsis as the affordance; it is aria-hidden and not focusable, so provide a real control such as a page input or a menu",
+          "severity": "must-not"
+        },
+        {
+          "context": "A page change that re-renders results in place without navigating",
+          "rule": "Move focus to the results region and announce the change, so keyboard and screen reader users know the content updated",
+          "severity": "must"
+        },
+        {
+          "context": "A feed that is read continuously rather than jumped through",
+          "rule": "Use infinite scroll or a \"Load more\" button instead of Pagination",
+          "severity": "should-not"
+        },
+        {
+          "context": "A cursor-based API that cannot address an arbitrary page",
+          "rule": "Do not render numbered links; expose only Previous and Next",
+          "severity": "must-not"
+        }
+      ],
+      "tokens": [
+        "background",
+        "foreground",
+        "accent",
+        "border",
+        "ring",
+        "radius"
+      ],
+      "relatedComponents": [
+        "button",
+        "table",
+        "select"
+      ],
+      "tags": [
+        "navigation",
+        "pagination",
+        "data",
+        "links"
+      ],
+      "categories": [
+        "navigation"
+      ]
+    },
+    "label": {
+      "name": "Label",
+      "description": "A caption that names a form control, built on Radix UI Label. Renders a native label element and suppresses text selection on double click so repeated clicks toggle the control rather than selecting its text. The label supplies the control's accessible name and extends its hit target.",
+      "status": "stable",
+      "whenToUse": "Use to name every form control on a surface: Input, Textarea, Checkbox, Switch, RadioGroupItem, and the Select trigger. Point htmlFor at the control's id so clicking or tapping the label focuses the control and, for checkboxes, switches, and radio items, activates it.",
+      "whenNotToUse": "Do not use it as a general text style for headings, hint text, or table column titles — it carries labelling semantics that assistive technology will try to associate with a control. Do not use one Label to name a group of controls such as a RadioGroup or a set of related checkboxes; a fieldset with a legend names a group. Do not put one on a Button — a button's own text is its accessible name.",
+      "props": {
+        "htmlFor": {
+          "type": "string",
+          "propRole": "content",
+          "description": "The id of the form control this label names. Must match that control's id exactly and that id must be unique on the page. Required unless the control is rendered inside the Label."
+        },
+        "asChild": {
+          "type": "boolean",
+          "propRole": "flag",
+          "default": false,
+          "description": "When true, merges the label's props and behavior onto its single child element instead of rendering a label element. Use only when the child is itself a labelling element; otherwise the association is lost."
+        }
+      },
+      "accessibility": {
+        "labelRequirement": "none",
+        "requiredAttributes": [
+          {
+            "attribute": "htmlFor",
+            "condition": "whenever the labelled control is not a descendant of the Label",
+            "description": "Reference the control's id. This is what makes the label text the control's accessible name and makes the label a click target for it."
+          },
+          {
+            "attribute": "id",
+            "condition": "on the control being labelled",
+            "description": "The control needs a unique id for htmlFor to point at. For Select this is the id of the SelectTrigger, not of the hidden native select."
+          }
+        ],
+        "focusManagement": "Not focusable and not in the tab order. Activating the label moves focus to the associated control and, for Checkbox, Switch, and RadioGroupItem, toggles or selects it.",
+        "notes": "A label element exposes no ARIA role of its own; it contributes the accessible name of the control it references. It must contain non-empty text — an empty Label silently leaves the control unnamed. A placeholder, a title attribute, or adjacent prose that is not bound with htmlFor is not a substitute. Do not nest interactive content (buttons, links) inside a Label: clicking it would activate both the label's control and the nested control."
+      },
+      "constraints": [
+        {
+          "context": "Any Input, Textarea, Checkbox, Switch, RadioGroupItem, or Select on a surface",
+          "rule": "Give it a Label whose htmlFor matches the control's id",
+          "severity": "must"
+        },
+        {
+          "context": "A control whose purpose is already suggested by placeholder text",
+          "rule": "Still render a Label — placeholder text disappears on input and is not an accessible name",
+          "severity": "must"
+        },
+        {
+          "context": "Naming a group of related controls such as a RadioGroup or a set of checkboxes",
+          "rule": "Use a fieldset with a legend (or aria-labelledby on the group) instead of a single Label",
+          "severity": "should"
+        },
+        {
+          "context": "Styling non-label text such as headings, hints, or column titles",
+          "rule": "Use a text element instead of Label",
+          "severity": "should-not"
+        },
+        {
+          "context": "A Label that wraps the control it names",
+          "rule": "Still pair an explicit htmlFor with the control's id so the association survives layout refactors",
+          "severity": "should"
+        },
+        {
+          "context": "Interactive content such as a Button or link inside label text",
+          "rule": "Move it outside the Label — activating the label would trigger both it and the labelled control",
+          "severity": "must-not"
+        }
+      ],
+      "tokens": [
+        "foreground"
+      ],
+      "relatedComponents": [
+        "input",
+        "textarea",
+        "checkbox",
+        "switch",
+        "radio-group",
+        "select"
+      ],
+      "tags": [
+        "form",
+        "label",
+        "accessibility",
+        "naming"
+      ]
+    },
+    "textarea": {
+      "name": "Textarea",
+      "description": "A multi-line text input rendered as a native textarea element. The shadcn wrapper applies field-sizing-content over a minimum height, so the control grows with what the user types instead of staying at a fixed row count.",
+      "status": "stable",
+      "whenToUse": "Use for free-form prose whose length is open-ended: descriptions, comments, support ticket bodies, release notes, feedback. Reach for it whenever a plausible answer would wrap onto a second line, or whenever the user should be able to press Enter for a new paragraph.",
+      "whenNotToUse": "Do not use for single-line values such as names, email addresses, amounts, or search queries, where Enter should submit rather than insert a newline; use Input. Do not use it as a code or rich-text editor — it has no formatting, syntax, or structured undo affordances. Do not use it to collect a value from a known set of options; use Select or RadioGroup.",
+      "props": {
+        "value": {
+          "type": "string",
+          "propRole": "state",
+          "description": "Controlled text content. Pair with onChange; a value without a change handler renders a read-only field that appears broken to the user."
+        },
+        "defaultValue": {
+          "type": "string",
+          "propRole": "state",
+          "description": "Initial text for an uncontrolled textarea. Use this when the form reads its value on submit rather than on every keystroke."
+        },
+        "onChange": {
+          "type": "function",
+          "propRole": "handler",
+          "description": "Native change handler fired on each edit, receiving the textarea event."
+        },
+        "placeholder": {
+          "type": "string",
+          "propRole": "content",
+          "description": "Hint text shown while the field is empty. Use it for an example of the expected content, never as the field's name — it disappears as soon as the user types."
+        },
+        "rows": {
+          "type": "number",
+          "propRole": "dimension",
+          "description": "Native attribute for the initial visible line count. shadcn's textarea sets field-sizing-content over a minimum height, so the rendered height follows the content; set a floor or ceiling with height classes rather than relying on rows."
+        },
+        "maxLength": {
+          "type": "number",
+          "propRole": "dimension",
+          "description": "Maximum number of characters the browser will accept. Enforcement is silent — the field simply stops accepting input — so pair it with a visible count."
+        },
+        "disabled": {
+          "type": "boolean",
+          "propRole": "flag",
+          "default": false,
+          "description": "Whether the field is non-interactive. Disabled fields are skipped by the tab order and are not submitted with the form."
+        },
+        "readOnly": {
+          "type": "boolean",
+          "propRole": "flag",
+          "default": false,
+          "description": "Whether the content is visible and selectable but not editable. Unlike disabled, a read-only field stays focusable and is still submitted."
+        },
+        "required": {
+          "type": "boolean",
+          "propRole": "flag",
+          "default": false,
+          "description": "Whether the field must be filled in before the form can be submitted. Mark the requirement visibly in the Label too, not only in markup."
+        },
+        "name": {
+          "type": "string",
+          "propRole": "content",
+          "description": "Form field name under which the value is submitted."
+        }
+      },
+      "accessibility": {
+        "role": "textbox",
+        "keyboardInteractions": [
+          {
+            "key": "Enter",
+            "description": "Inserts a newline. It does not submit the surrounding form, so a form containing a Textarea needs an explicit submit Button."
+          },
+          {
+            "key": "Tab",
+            "description": "Moves focus out of the field. It does not insert a tab character, so keyboard users are never trapped in the textarea."
+          }
+        ],
+        "labelRequirement": "required-visible",
+        "requiredAttributes": [
+          {
+            "attribute": "id",
+            "description": "Required so the field's Label can reference it with htmlFor. Without the pairing the field is announced as an unnamed text area."
+          },
+          {
+            "attribute": "aria-describedby",
+            "condition": "when hint text, a character count, or an error message qualifies the field",
+            "description": "Reference the ids of those elements so the guidance is announced with the field rather than being visual-only."
+          },
+          {
+            "attribute": "aria-invalid",
+            "condition": "when the field has failed validation",
+            "description": "Set aria-invalid so the error state is announced, and point aria-describedby at the message that explains how to fix it. shadcn styles the invalid state from this attribute."
+          }
+        ],
+        "notes": "The field grows as the user types, so avoid absolutely positioned siblings that assume a fixed height. Character counters must be referenced with aria-describedby to be announced; a live-updating counter should not be an aria-live region on every keystroke."
+      },
+      "constraints": [
+        {
+          "context": "A single-line value such as a name, email address, or search query",
+          "rule": "Use Input instead of Textarea",
+          "severity": "must-not"
+        },
+        {
+          "context": "Any Textarea",
+          "rule": "Give it a visible Label associated by id and htmlFor",
+          "severity": "must"
+        },
+        {
+          "context": "A field that has failed validation",
+          "rule": "Set aria-invalid and reference the error message with aria-describedby",
+          "severity": "must"
+        },
+        {
+          "context": "A field with a character limit",
+          "rule": "Show the limit and the remaining count in text referenced by aria-describedby rather than relying on maxLength to cut input off silently",
+          "severity": "should"
+        },
+        {
+          "context": "A textarea that needs a fixed or capped height",
+          "rule": "Constrain it with height classes — field-sizing-content supersedes the rows attribute",
+          "severity": "should"
+        },
+        {
+          "context": "Rich text, markdown with live preview, or code entry",
+          "rule": "Use a dedicated editor instead of Textarea",
+          "severity": "should-not"
+        }
+      ],
+      "tokens": [
+        "background",
+        "foreground",
+        "muted-foreground",
+        "border",
+        "ring",
+        "radius-sm"
+      ],
+      "relatedComponents": [
+        "input",
+        "label",
+        "select"
+      ],
+      "tags": [
+        "form",
+        "input",
+        "text",
+        "multiline"
+      ],
+      "categories": [
+        "interactive"
+      ]
+    },
+    "checkbox": {
+      "name": "Checkbox",
+      "description": "A tri-state checkbox built on Radix UI Checkbox. Renders a button with role checkbox plus a visually hidden native input so the value participates in form submission. The check mark is rendered internally by the component's indicator, so there is nothing to compose inside it — the option's text belongs in a sibling Label.",
+      "status": "stable",
+      "whenToUse": "Use for independent boolean choices the user opts into: accepting terms, selecting rows, enabling several non-exclusive filters or permissions. Use a set of checkboxes whenever more than one option in a group may be chosen at once.",
+      "whenNotToUse": "Do not use for mutually exclusive options; use RadioGroup. Do not use for a setting that takes effect the instant it is flipped with no Save step; that is Switch. Do not use a checkbox as a trigger for an action or for navigation; use Button.",
+      "props": {
+        "checked": {
+          "type": "boolean | 'indeterminate'",
+          "propRole": "state",
+          "values": [
+            {
+              "value": true,
+              "description": "Checked. The hidden input submits the checkbox's value with the form."
+            },
+            {
+              "value": false,
+              "description": "Unchecked. Nothing is submitted for this field."
+            },
+            {
+              "value": "indeterminate",
+              "description": "Mixed state for a parent checkbox whose children are only partly selected. Radix exposes it as aria-checked=\"mixed\"; activating it resolves to checked, so it is never part of the user-facing click cycle."
+            }
+          ],
+          "description": "Controlled checked state. Pair it with onCheckedChange — a checked value without a handler produces a box the user cannot toggle."
+        },
+        "defaultChecked": {
+          "type": "boolean | 'indeterminate'",
+          "propRole": "state",
+          "description": "Initial state for an uncontrolled checkbox. Use this when the surrounding form reads values on submit rather than tracking them per keystroke."
+        },
+        "onCheckedChange": {
+          "type": "function",
+          "propRole": "handler",
+          "description": "Fires with the new state (true, false, or \"indeterminate\") whenever the user toggles the checkbox."
+        },
+        "disabled": {
+          "type": "boolean",
+          "propRole": "flag",
+          "default": false,
+          "description": "Whether the checkbox is non-interactive. Disabled checkboxes leave the tab order and are not submitted; if the reason is not obvious from context, explain it in nearby text."
+        },
+        "required": {
+          "type": "boolean",
+          "propRole": "flag",
+          "default": false,
+          "description": "Whether the box must be checked before the form can be submitted. Use it for consent gates, and mark the requirement visibly in the Label as well."
+        },
+        "name": {
+          "type": "string",
+          "propRole": "content",
+          "description": "Form field name applied to the hidden native input, under which the value is submitted."
+        },
+        "value": {
+          "type": "string",
+          "propRole": "content",
+          "default": "on",
+          "description": "Value submitted when the box is checked. Set it when a group of checkboxes shares one name and the server distinguishes them by value."
+        }
+      },
+      "accessibility": {
+        "role": "checkbox",
+        "keyboardInteractions": [
+          {
+            "key": "Space",
+            "description": "Toggles the checkbox."
+          },
+          {
+            "key": "Enter",
+            "description": "Does not toggle the checkbox. Radix suppresses Enter to match native checkbox behavior."
+          },
+          {
+            "key": "Tab",
+            "description": "Moves focus to the checkbox. Every checkbox is its own tab stop — unlike RadioGroup, where the whole group is one stop."
+          }
+        ],
+        "labelRequirement": "required-visible",
+        "requiredAttributes": [
+          {
+            "attribute": "id",
+            "description": "Required so a sibling Label can reference it with htmlFor. The pairing supplies the accessible name and makes the label text a click target for the box."
+          },
+          {
+            "attribute": "aria-describedby",
+            "condition": "when legal text, a consequence, or an error message qualifies the choice",
+            "description": "Reference the ids of that text so it is announced with the checkbox instead of being read as unrelated prose."
+          },
+          {
+            "attribute": "aria-invalid",
+            "condition": "when a required checkbox has failed validation",
+            "description": "Set aria-invalid and reference the error message with aria-describedby so the failure is announced, not just outlined in red."
+          }
+        ],
+        "focusManagement": "Focusable and in the tab order; focus stays on the control after toggling so the new state is announced in place. The hidden native input is never focused.",
+        "notes": "Radix sets aria-checked=\"mixed\" when checked is \"indeterminate\", and activating an indeterminate checkbox resolves it to checked — the mixed state is something the parent sets from its children's state, never a third position the user cycles through. Do not convey checked state by color alone; the check mark carries it."
+      },
+      "constraints": [
+        {
+          "context": "Several independent options where more than one may be selected",
+          "rule": "Use a group of Checkboxes",
+          "severity": "should"
+        },
+        {
+          "context": "Mutually exclusive options where exactly one may be selected",
+          "rule": "Use RadioGroup instead of Checkbox",
+          "severity": "must-not"
+        },
+        {
+          "context": "A setting that applies immediately with no Save step",
+          "rule": "Use Switch instead of Checkbox",
+          "severity": "should-not"
+        },
+        {
+          "context": "A parent checkbox summarizing children that are only partly selected",
+          "rule": "Set checked to \"indeterminate\" rather than inventing a third visual state, and make activation resolve to all checked or all unchecked",
+          "severity": "must"
+        },
+        {
+          "context": "Any Checkbox",
+          "rule": "Give it a visible Label associated by id and htmlFor so the text is clickable and the name is announced",
+          "severity": "must"
+        },
+        {
+          "context": "A consent gate that blocks submission",
+          "rule": "Set required, and on failure set aria-invalid with the error message referenced by aria-describedby",
+          "severity": "must"
+        },
+        {
+          "context": "A checkbox whose value is submitted with a native form",
+          "rule": "Set name, and set value when the submitted value is not the default \"on\"",
+          "severity": "should"
+        }
+      ],
+      "tokens": [
+        "background",
+        "primary",
+        "primary-foreground",
+        "border",
+        "ring",
+        "radius-sm"
+      ],
+      "relatedComponents": [
+        "label",
+        "radio-group",
+        "switch"
+      ],
+      "tags": [
+        "form",
+        "boolean",
+        "selection",
+        "tri-state"
+      ],
+      "categories": [
+        "interactive"
+      ]
+    },
+    "switch": {
+      "name": "Switch",
+      "description": "A control that turns a single setting on or off and applies the change immediately, built on Radix UI Switch. Renders a button with role switch and aria-checked plus a hidden native input for form submission, and slides a thumb between two positions to show state.",
+      "status": "stable",
+      "whenToUse": "Use for a setting whose effect is immediate and reversible: enabling notifications, turning on a beta feature, toggling dark mode in a preferences panel. The label names the setting; the switch's position carries on or off.",
+      "whenNotToUse": "Do not use inside a form that is only committed on Save — a switch implies the change has already happened; use Checkbox. Do not use it to accept terms or capture consent that is submitted with a form; that is a Checkbox. Do not use it to choose among options or for anything that is not a two-state setting; use RadioGroup or Select.",
+      "props": {
+        "checked": {
+          "type": "boolean",
+          "propRole": "state",
+          "description": "Controlled on/off state. Pair it with onCheckedChange; because the change is applied immediately, drive this from the value your backend acknowledged rather than from an unreconciled optimistic guess."
+        },
+        "defaultChecked": {
+          "type": "boolean",
+          "propRole": "state",
+          "description": "Initial state for an uncontrolled switch."
+        },
+        "onCheckedChange": {
+          "type": "function",
+          "propRole": "handler",
+          "description": "Fires with the new boolean state when the user toggles the switch. This is where the setting is persisted — there is no Save step."
+        },
+        "size": {
+          "type": "enum",
+          "propRole": "dimension",
+          "values": [
+            {
+              "value": "default",
+              "description": "Standard size, suitable for settings rows and forms."
+            },
+            {
+              "value": "sm",
+              "description": "Compact size for dense lists and toolbars. Keep the surrounding row large enough to stay a comfortable touch target."
+            }
+          ],
+          "default": "default",
+          "description": "Switch size. shadcn adds this on top of the Radix primitive."
+        },
+        "disabled": {
+          "type": "boolean",
+          "propRole": "flag",
+          "default": false,
+          "description": "Whether the switch is non-interactive. Explain in nearby text why a setting is locked — a disabled switch on its own reads as an unexplained dead control."
+        },
+        "required": {
+          "type": "boolean",
+          "propRole": "flag",
+          "default": false,
+          "description": "Whether the switch must be on before the form can be submitted. Rarely appropriate: a required toggle usually indicates the choice belongs to a Checkbox in a submitted form."
+        },
+        "name": {
+          "type": "string",
+          "propRole": "content",
+          "description": "Form field name applied to the hidden native input, under which the value is submitted."
+        },
+        "value": {
+          "type": "string",
+          "propRole": "content",
+          "default": "on",
+          "description": "Value submitted when the switch is on."
+        }
+      },
+      "accessibility": {
+        "role": "switch",
+        "keyboardInteractions": [
+          {
+            "key": "Space",
+            "description": "Toggles the switch."
+          },
+          {
+            "key": "Enter",
+            "description": "Toggles the switch. This differs from Checkbox, which ignores Enter."
+          },
+          {
+            "key": "Tab",
+            "description": "Moves focus to the switch. Each switch is its own tab stop."
+          }
+        ],
+        "labelRequirement": "required-visible",
+        "requiredAttributes": [
+          {
+            "attribute": "id",
+            "description": "Required so the settings row's Label can reference it with htmlFor, making the label text a click target and the switch's accessible name."
+          },
+          {
+            "attribute": "aria-describedby",
+            "condition": "when the consequence of the setting is explained in secondary text",
+            "description": "Reference the description's id so the explanation is announced with the control rather than read as loose prose."
+          }
+        ],
+        "focusManagement": "Focusable and in the tab order; focus stays on the switch after toggling so the new state is announced in place. The hidden native input is never focused.",
+        "notes": "Screen readers announce a switch as on or off rather than checked or unchecked, so the label must name the setting (\"Email notifications\"), not its state (\"On\"). Do not add separate On/Off text as the accessible name, and do not rely on the track color alone to communicate state."
+      },
+      "constraints": [
+        {
+          "context": "A setting that takes effect the moment it is flipped",
+          "rule": "Use Switch",
+          "severity": "should"
+        },
+        {
+          "context": "A form that is committed with an explicit Save or Submit button",
+          "rule": "Use Checkbox instead of Switch",
+          "severity": "should-not"
+        },
+        {
+          "context": "Any Switch",
+          "rule": "Give it a visible Label that names the setting, associated by id and htmlFor",
+          "severity": "must"
+        },
+        {
+          "context": "The wording of a switch's label",
+          "rule": "Name the setting rather than its current state — \"Email notifications\", never \"On\"",
+          "severity": "must"
+        },
+        {
+          "context": "A toggle whose effect is destructive or hard to reverse, such as disabling two-factor authentication",
+          "rule": "Confirm with an AlertDialog before applying the change",
+          "severity": "must"
+        },
+        {
+          "context": "A switch backed by a network request",
+          "rule": "Reflect the persisted result — revert the position and surface an error if the write fails, rather than leaving an optimistic state that lies about the setting",
+          "severity": "should"
+        },
+        {
+          "context": "Choosing among three or more options",
+          "rule": "Use RadioGroup or Select instead of a row of Switches",
+          "severity": "must-not"
+        }
+      ],
+      "tokens": [
+        "primary",
+        "primary-foreground",
+        "background",
+        "border",
+        "ring"
+      ],
+      "relatedComponents": [
+        "checkbox",
+        "label",
+        "alert-dialog"
+      ],
+      "tags": [
+        "form",
+        "toggle",
+        "boolean",
+        "setting"
+      ],
+      "categories": [
+        "interactive"
+      ]
+    },
+    "radio-group": {
+      "name": "Radio Group",
+      "description": "A set of mutually exclusive options where exactly one may be selected, built on Radix UI RadioGroup. The group renders role radiogroup and manages a roving tabindex, so the whole group is a single tab stop; each RadioGroupItem is a button with role radio backed by a hidden native input for form submission.",
+      "status": "stable",
+      "whenToUse": "Use when the user must pick exactly one option from a small, stable set that is worth seeing all at once: a billing interval, a shipping speed, a visibility level. Showing every option side by side, with its trade-offs visible, is the reason to choose RadioGroup over Select.",
+      "whenNotToUse": "Do not use when more than one option may be selected; use Checkboxes. Do not use for long or runtime-generated lists — past roughly six options the group crowds the form and Select is easier to scan. Do not use for a binary on/off setting; use Switch or a single Checkbox.",
+      "props": {
+        "value": {
+          "type": "string",
+          "propRole": "state",
+          "description": "Controlled selected value. Must match the value of exactly one RadioGroupItem in the group."
+        },
+        "defaultValue": {
+          "type": "string",
+          "propRole": "state",
+          "description": "Initially selected value for an uncontrolled group. Omit it when there is no safe default — an unselected group forces a deliberate choice."
+        },
+        "onValueChange": {
+          "type": "function",
+          "propRole": "handler",
+          "description": "Fires with the newly selected value. Because selection follows focus, this also fires while the user arrows through the options."
+        },
+        "orientation": {
+          "type": "enum",
+          "propRole": "choice",
+          "values": [
+            {
+              "value": "vertical",
+              "description": "Options stacked in a column. Up and Down arrows move between them."
+            },
+            {
+              "value": "horizontal",
+              "description": "Options laid out in a row. Left and Right arrows move between them."
+            }
+          ],
+          "description": "Sets aria-orientation and constrains arrow-key navigation to one axis. Unset by default, which lets both axes navigate; set it to match the visual arrangement whenever the layout is committed to a direction."
+        },
+        "disabled": {
+          "type": "boolean",
+          "propRole": "flag",
+          "default": false,
+          "description": "Disables every item in the group. To disable one option, set disabled on that RadioGroupItem instead."
+        },
+        "required": {
+          "type": "boolean",
+          "propRole": "flag",
+          "default": false,
+          "description": "Whether a selection is required before the form can be submitted. Sets aria-required on the group."
+        },
+        "name": {
+          "type": "string",
+          "propRole": "content",
+          "description": "Form field name applied to the items' hidden native inputs, under which the selected value is submitted."
+        },
+        "loop": {
+          "type": "boolean",
+          "propRole": "flag",
+          "default": true,
+          "description": "Whether arrow-key navigation wraps from the last item back to the first."
+        },
+        "dir": {
+          "type": "enum",
+          "propRole": "choice",
+          "values": [
+            {
+              "value": "ltr",
+              "description": "Left-to-right reading order."
+            },
+            {
+              "value": "rtl",
+              "description": "Right-to-left reading order, which swaps what Left and Right arrows mean."
+            }
+          ],
+          "description": "Reading direction for arrow-key navigation. Inherited from an ambient direction provider when omitted."
+        }
+      },
+      "composition": {
+        "subComponents": [
+          {
+            "id": "radio-group-item",
+            "name": "RadioGroupItem",
+            "description": "A single option. Needs a value that is unique within the group and an id so a sibling Label can name it. The selected indicator is rendered internally, so the item takes no children — the option's text goes in a Label next to it, not inside it.",
+            "required": true,
+            "slot": "item",
+            "acceptsChildren": "none",
+            "categories": [
+              "interactive"
+            ]
+          }
+        ],
+        "requiredChildren": [
+          "radio-group-item"
+        ],
+        "notes": "RadioGroupItem must be a descendant of RadioGroup, which supplies the selection context and the roving tabindex; an item outside a group is inert. Each item pairs with a Label whose htmlFor matches the item's id. Wrap the group in a fieldset with a legend so the whole set has an accessible name, and keep the items' order stable — arrow-key navigation follows DOM order."
+      },
+      "accessibility": {
+        "role": "radiogroup",
+        "keyboardInteractions": [
+          {
+            "key": "Tab",
+            "description": "Moves focus into the group, landing on the checked item or, when nothing is checked, on the first enabled one. The group is a single tab stop; Tab again leaves it entirely."
+          },
+          {
+            "key": "ArrowDown / ArrowRight",
+            "description": "Moves focus to the next item and checks it — selection follows focus."
+          },
+          {
+            "key": "ArrowUp / ArrowLeft",
+            "description": "Moves focus to the previous item and checks it."
+          },
+          {
+            "key": "Space",
+            "description": "Checks the focused item when it is not already checked."
+          },
+          {
+            "key": "Enter",
+            "description": "Does nothing. Radix suppresses Enter on radio items to match native radio behavior."
+          }
+        ],
+        "labelRequirement": "required-visible",
+        "requiredAttributes": [
+          {
+            "attribute": "aria-labelledby",
+            "condition": "on the RadioGroup when its name comes from a visible heading rather than a fieldset legend",
+            "description": "Reference the id of the element that names the whole group. The per-item Labels name individual options; they never name the set."
+          },
+          {
+            "attribute": "id",
+            "condition": "on every RadioGroupItem",
+            "description": "Required so each option's Label can reference it with htmlFor. Without it the option is announced with no name."
+          },
+          {
+            "attribute": "aria-describedby",
+            "condition": "when a hint or an error message qualifies the whole group",
+            "description": "Put it on the RadioGroup so the guidance is announced once for the set rather than repeated on every option."
+          },
+          {
+            "attribute": "aria-invalid",
+            "condition": "when a required group has failed validation",
+            "description": "Set it on the RadioGroup so the state is announced for the set. shadcn's item styles also key off aria-invalid, so mirror it onto the RadioGroupItems when the options themselves should show the error."
+          }
+        ],
+        "focusManagement": "Roving tabindex: exactly one item is tabbable at a time, and arrow keys move focus within the group, checking as they land. Because selection follows focus, a keyboard user cannot browse the options without selecting them — keep the set short and keep onValueChange free of side effects.",
+        "notes": "The group name and the option names are separate obligations: a fieldset legend (or aria-labelledby) names the set, and a Label per item names each option. Do not convey the selected option by color alone; the indicator dot carries it."
+      },
+      "constraints": [
+        {
+          "context": "Exactly one choice from a small set that should all stay visible",
+          "rule": "Use RadioGroup",
+          "severity": "should"
+        },
+        {
+          "context": "More than one option may be selected",
+          "rule": "Use Checkboxes instead of RadioGroup",
+          "severity": "must-not"
+        },
+        {
+          "context": "More than roughly six options, or a list generated at runtime",
+          "rule": "Use Select instead of RadioGroup",
+          "severity": "should"
+        },
+        {
+          "context": "Every option in the group",
+          "rule": "Give each RadioGroupItem a unique non-empty value and a Label bound by id and htmlFor",
+          "severity": "must"
+        },
+        {
+          "context": "The group as a whole",
+          "rule": "Give it an accessible group name with a fieldset and legend, or with aria-labelledby",
+          "severity": "must"
+        },
+        {
+          "context": "Options arranged in a row",
+          "rule": "Set orientation to \"horizontal\" so aria-orientation and arrow-key navigation match what the user sees",
+          "severity": "should"
+        },
+        {
+          "context": "A consequential choice with no obviously safe default",
+          "rule": "Leave defaultValue unset rather than pre-selecting an option the user may never consciously confirm",
+          "severity": "should"
+        },
+        {
+          "context": "Reacting to a change of selection",
+          "rule": "Do not navigate, submit, or trigger destructive side effects on change — selection follows focus, so arrow keys would fire them for every option passed over",
+          "severity": "must-not"
+        }
+      ],
+      "tokens": [
+        "primary",
+        "background",
+        "border",
+        "ring"
+      ],
+      "relatedComponents": [
+        "checkbox",
+        "label",
+        "select"
+      ],
+      "tags": [
+        "form",
+        "selection",
+        "exclusive",
+        "group"
+      ],
+      "categories": [
+        "interactive"
+      ]
+    },
+    "select": {
+      "name": "Select",
+      "description": "A select-only combobox built on Radix UI Select: a trigger button that opens a portalled listbox of options. The trigger renders role combobox, the content renders role listbox, and each item renders role option, while a hidden native select carries the value into form submission. It is not a native select element — the list is fully stylable but always renders in a layer above the page, and it accepts no typed input.",
+      "status": "stable",
+      "whenToUse": "Use to pick one value from a known list that is too long to show inline: a country, a timezone, a project, a status. It earns its click from roughly six options upward, where a RadioGroup would crowd the form.",
+      "whenNotToUse": "Do not use for two to five options that fit on screen — a RadioGroup shows them all without a click. Do not use when more than one value may be chosen; Select is single-value, so use checkboxes or a dedicated multi-select. Do not use when the user needs to type to filter a long list or to enter a value that is not in it; use a combobox. When the platform's native picker is what you actually want, on dense mobile forms, use a native select instead.",
+      "props": {
+        "value": {
+          "type": "string",
+          "propRole": "state",
+          "description": "Controlled selected value; must match the value of one SelectItem. The empty string means nothing is selected and shows the SelectValue placeholder."
+        },
+        "defaultValue": {
+          "type": "string",
+          "propRole": "state",
+          "description": "Initially selected value for an uncontrolled Select. Omit it to start on the placeholder."
+        },
+        "onValueChange": {
+          "type": "function",
+          "propRole": "handler",
+          "description": "Fires with the newly selected value. Selection is committed on click, Enter, Space, or typeahead — not while arrowing through the list."
+        },
+        "open": {
+          "type": "boolean",
+          "propRole": "state",
+          "description": "Controlled open state of the listbox. Only needed when something outside the Select has to open or close it."
+        },
+        "defaultOpen": {
+          "type": "boolean",
+          "propRole": "state",
+          "description": "Whether the listbox starts open for an uncontrolled Select."
+        },
+        "onOpenChange": {
+          "type": "function",
+          "propRole": "handler",
+          "description": "Fires when the listbox opens or closes."
+        },
+        "disabled": {
+          "type": "boolean",
+          "propRole": "flag",
+          "default": false,
+          "description": "Whether the whole control is non-interactive. To disable one option, set disabled on that SelectItem instead."
+        },
+        "required": {
+          "type": "boolean",
+          "propRole": "flag",
+          "default": false,
+          "description": "Whether a value must be chosen before the form can be submitted. Sets aria-required on the trigger."
+        },
+        "name": {
+          "type": "string",
+          "propRole": "content",
+          "description": "Form field name applied to the hidden native select, under which the value is submitted."
+        },
+        "dir": {
+          "type": "enum",
+          "propRole": "choice",
+          "values": [
+            {
+              "value": "ltr",
+              "description": "Left-to-right reading order."
+            },
+            {
+              "value": "rtl",
+              "description": "Right-to-left reading order, which mirrors the content's alignment against the trigger."
+            }
+          ],
+          "description": "Reading direction. Inherited from an ambient direction provider when omitted."
+        }
+      },
+      "composition": {
+        "subComponents": [
+          {
+            "id": "select-trigger",
+            "name": "SelectTrigger",
+            "description": "The button that opens the listbox. Renders role combobox with aria-expanded, shows the current value, and draws its own chevron; it accepts a size of \"default\" or \"sm\". Give it an id — this is the element a Label's htmlFor must point at, and the element that carries aria-invalid.",
+            "required": true,
+            "slot": "trigger",
+            "acceptsChildren": "components",
+            "categories": [
+              "interactive"
+            ]
+          },
+          {
+            "id": "select-value",
+            "name": "SelectValue",
+            "description": "The trigger's text: it renders the selected item's label automatically, or the placeholder while nothing is selected. Pass the empty-state text through its placeholder prop rather than as children.",
+            "required": true,
+            "slot": "value",
+            "acceptsChildren": "none"
+          },
+          {
+            "id": "select-content",
+            "name": "SelectContent",
+            "description": "The portalled listbox holding the options. Renders role listbox and provides its own scrolling viewport and scroll buttons. Defaults to position \"item-aligned\", which lines the selected item up over the trigger; switch to \"popper\" to anchor it below the trigger like a menu.",
+            "required": true,
+            "slot": "content",
+            "acceptsChildren": "components"
+          },
+          {
+            "id": "select-item",
+            "name": "SelectItem",
+            "description": "A single option, rendered as role option with a check indicator for the selected state. Requires a unique, non-empty value. Its children are normally the option's text, optionally with a leading icon or a trailing Badge; whenever they are not plain text, set textValue so typeahead and the value shown in the trigger stay meaningful.",
+            "required": true,
+            "acceptsChildren": "any",
+            "categories": [
+              "interactive"
+            ]
+          },
+          {
+            "id": "select-group",
+            "name": "SelectGroup",
+            "description": "Groups related items under a SelectLabel. Renders role group and is labelled by the SelectLabel inside it, so assistive technology announces the group name alongside its options.",
+            "acceptsChildren": "components"
+          },
+          {
+            "id": "select-label",
+            "name": "SelectLabel",
+            "description": "A non-interactive heading naming a SelectGroup. It supplies the group's accessible name only when it sits inside a SelectGroup; used on its own it is decorative text. It is not the form field's label — that is a separate Label bound to the trigger.",
+            "acceptsChildren": "text"
+          },
+          {
+            "id": "select-separator",
+            "name": "SelectSeparator",
+            "description": "A decorative divider between groups of options. Not focusable and skipped by keyboard navigation, so it must never carry meaning of its own.",
+            "acceptsChildren": "none"
+          }
+        ],
+        "requiredChildren": [
+          "select-trigger",
+          "select-content"
+        ],
+        "allowedChildren": [
+          "select-trigger",
+          "select-content"
+        ],
+        "notes": "Select takes exactly two children: a SelectTrigger and a SelectContent. SelectValue belongs inside the trigger; SelectItem, SelectGroup, SelectLabel, and SelectSeparator belong inside the content, with SelectLabel nested in the SelectGroup it names. shadcn renders the scrolling viewport and the scroll-up/scroll-down buttons inside SelectContent for you — those parts are exported but are not part of normal composition. The field's own Label lives outside the Select and points at the trigger's id."
+      },
+      "accessibility": {
+        "role": "combobox",
+        "keyboardInteractions": [
+          {
+            "key": "Enter",
+            "description": "On the trigger, opens the listbox and moves focus to the first item. On an item, selects it, closes the listbox, and returns focus to the trigger."
+          },
+          {
+            "key": "Space",
+            "description": "On the trigger, opens the listbox with focus on the currently selected item. On an item, selects it and closes the listbox."
+          },
+          {
+            "key": "ArrowDown / ArrowUp",
+            "description": "On the trigger, opens the listbox. Inside the listbox, moves focus to the next or previous enabled item without committing a selection."
+          },
+          {
+            "key": "Escape",
+            "description": "Closes the listbox without changing the selection and returns focus to the trigger."
+          },
+          {
+            "key": "Printable characters",
+            "description": "Typeahead: jumps to the first item whose text starts with what was typed. With the listbox closed, typing on the trigger changes the selected value directly, so items need meaningful text or an explicit textValue."
+          },
+          {
+            "key": "Tab",
+            "description": "The trigger is the control's single tab stop. Options are reached with the arrow keys and typeahead while the listbox is open, never with Tab."
+          }
+        ],
+        "labelRequirement": "required-visible",
+        "requiredAttributes": [
+          {
+            "attribute": "id",
+            "condition": "on the SelectTrigger",
+            "description": "The field's Label must reference the trigger with htmlFor. Pointing at the hidden native select instead leaves the focusable control unnamed."
+          },
+          {
+            "attribute": "aria-invalid",
+            "condition": "on the SelectTrigger when the field has failed validation",
+            "description": "Set it on the trigger, which is the element the user focuses and shadcn styles from this attribute, and reference the error message with aria-describedby."
+          },
+          {
+            "attribute": "aria-describedby",
+            "condition": "on the SelectTrigger when hint or error text qualifies the field",
+            "description": "Reference the ids of that text so it is announced with the control."
+          }
+        ],
+        "focusManagement": "Focus starts on the trigger. Opening moves focus into the listbox, onto the selected item or the first item when nothing is selected, and contains it there; choosing an item or pressing Escape closes the listbox and returns focus to the trigger. Unlike RadioGroup, selection does not follow focus — arrow keys only move the highlight until Enter, Space, or a click commits.",
+        "notes": "The roles are split across the parts: trigger is combobox with aria-expanded and aria-controls, content is listbox, item is option, and SelectGroup is a group labelled by its SelectLabel. Radix keeps a hidden native select in sync for form submission; it is aria-hidden, so never label, style, or target it. The listbox renders in a portal, so it escapes ancestor overflow but also any ancestor that assumed it could clip its children."
+      },
+      "constraints": [
+        {
+          "context": "One value from a list of roughly six or more known options",
+          "rule": "Use Select",
+          "severity": "should"
+        },
+        {
+          "context": "Two to five options that fit on screen",
+          "rule": "Use RadioGroup instead of Select",
+          "severity": "should-not"
+        },
+        {
+          "context": "The user may pick more than one value",
+          "rule": "Use Checkboxes or a dedicated multi-select instead of Select",
+          "severity": "must-not"
+        },
+        {
+          "context": "A list long enough that the user would want to type to narrow it, or a value that may not be in the list",
+          "rule": "Use a combobox instead of Select",
+          "severity": "should-not"
+        },
+        {
+          "context": "Every SelectItem",
+          "rule": "Give it a unique, non-empty value — the empty string is how Radix represents nothing selected, so an item using it can never be shown as the selection",
+          "severity": "must"
+        },
+        {
+          "context": "An empty, \"None\", or \"All\" choice",
+          "rule": "Express the empty state with the SelectValue placeholder, or add an item with a real value such as \"none\" — never an item with an empty value",
+          "severity": "must-not"
+        },
+        {
+          "context": "Any Select",
+          "rule": "Associate a visible Label with the SelectTrigger's id",
+          "severity": "must"
+        },
+        {
+          "context": "Items whose content is not plain text, such as icons, badges, or two-line rows",
+          "rule": "Set textValue on the item so typeahead and the value rendered in the trigger stay meaningful",
+          "severity": "should"
+        },
+        {
+          "context": "Options that fall into categories",
+          "rule": "Wrap each category in a SelectGroup with a SelectLabel inside it rather than faking headings with disabled items",
+          "severity": "should"
+        },
+        {
+          "context": "A trigger that shows no chosen value yet",
+          "rule": "Give SelectValue a placeholder that names the field's subject, not a bare \"Select...\"",
+          "severity": "should"
+        }
+      ],
+      "tokens": [
+        "background",
+        "foreground",
+        "muted-foreground",
+        "accent",
+        "border",
+        "ring",
+        "radius"
+      ],
+      "relatedComponents": [
+        "radio-group",
+        "label",
+        "input",
+        "dropdown-menu"
+      ],
+      "tags": [
+        "form",
+        "selection",
+        "dropdown",
+        "listbox",
+        "overlay"
+      ],
+      "categories": [
+        "interactive",
+        "overlay"
+      ]
+    },
+    "alert": {
+      "name": "Alert",
+      "description": "A static, in-page callout that draws attention to a short message without interrupting the flow. Renders a div with a hardcoded role=\"alert\" and lays out an optional icon, a title, a description, and an optional action on a grid. Alert is presentational: it has no open state, no dismiss affordance, and no portal, and it stays wherever you place it in the document.",
+      "status": "stable",
+      "whenToUse": "Use for a persistent message that belongs to a region of the page: a form-level error summary above the submit button, a plan-limit warning on a settings panel, an informational note explaining a feature. Reach for Alert when the message must stay on screen for as long as the condition holds and the user should be able to re-read it after looking away.",
+      "whenNotToUse": "Do not use for a transient confirmation of something the user just did — Sonner clears itself, Alert does not. Do not use to block a workflow or demand a decision; that is AlertDialog. Do not use it as a generic bordered container for arbitrary content; that is Card. Do not use it for a short status label attached to a row or item; that is Badge.",
+      "props": {
+        "variant": {
+          "type": "enum",
+          "propRole": "choice",
+          "values": [
+            {
+              "value": "default",
+              "description": "Neutral callout on the card surface. Covers informational and warning messages; carry the meaning in the icon and the title text rather than in colour."
+            },
+            {
+              "value": "destructive",
+              "description": "Errors and failures. Tints the title, the icon, and the description with the destructive token."
+            }
+          ],
+          "default": "default",
+          "description": "Visual treatment. shadcn ships only these two variants — there is no success or warning variant — so other tones are built by adding utility classes through className."
+        },
+        "className": {
+          "type": "string",
+          "propRole": "content",
+          "description": "Additional CSS classes. This is the sanctioned way to produce tones shadcn does not ship a variant for (for example bg-amber-50 dark:bg-amber-950 for a warning) and to constrain the alert's width; the component is w-full and fills its parent."
+        }
+      },
+      "accessibility": {
+        "role": "alert",
+        "labelRequirement": "none",
+        "requiredAttributes": [
+          {
+            "attribute": "role",
+            "condition": "when the Alert is part of the initial page render rather than appearing in response to an event",
+            "description": "Override the built-in role with role=\"status\" or role=\"note\". role=\"alert\" is an assertive live region that interrupts whatever the screen reader is currently saying — correct for an error that appears after a failed submit, wrong for a callout that was always on the page. The component spreads incoming props after its own role, so the value you pass wins."
+          },
+          {
+            "attribute": "aria-hidden",
+            "condition": "on the decorative icon passed as a direct child of Alert",
+            "description": "Mark the icon aria-hidden=\"true\". It restates what the title already says, and the alert is announced as one block of text, so an unnamed or named icon only adds noise at the front of the message."
+          },
+          {
+            "attribute": "aria-label",
+            "condition": "only when the alert's own text does not identify what it refers to",
+            "description": "Alert takes its accessible name from its content, so a label is normally unnecessary. Prefer rewriting the title to name the subject over bolting on a label that screen-reader users hear and sighted users do not."
+          }
+        ],
+        "keyboardInteractions": [
+          {
+            "key": "Tab",
+            "description": "Moves focus to interactive controls inside the alert, such as the Button in AlertAction. The Alert container itself is not focusable and defines no keyboard behaviour of its own."
+          }
+        ],
+        "focusManagement": "Alert never moves, traps, or restores focus. When one appears after a failed submit, leave focus where the user put it and let role=\"alert\" do the announcing; move focus into the alert only when the user's next action genuinely lives there.",
+        "notes": "role=\"alert\" is hardcoded on the root element, which makes every Alert an assertive, atomic live region. Reserve that for messages the user must hear immediately and downgrade the rest with an explicit role. AlertTitle and AlertDescription are plain divs, not headings, and are not wired to the container with aria-labelledby or aria-describedby — the whole alert is announced as a single run of text, so write the title and description to read well when concatenated."
+      },
+      "composition": {
+        "subComponents": [
+          {
+            "id": "alert-title",
+            "name": "AlertTitle",
+            "description": "The one-line headline of the alert. Rendered as a div with a medium font weight — not a heading — and moved into the second grid column when an icon is present. Write it as the message itself, not a category label: \"Your trial ends in 3 days\" rather than \"Warning\".",
+            "required": true,
+            "slot": "title",
+            "acceptsChildren": "text"
+          },
+          {
+            "id": "alert-description",
+            "name": "AlertDescription",
+            "description": "Supporting detail below the title, in muted foreground. Styled to handle paragraphs and inline links, so it can hold more than a single string when the message needs to explain a consequence or point at documentation.",
+            "slot": "description",
+            "acceptsChildren": "any"
+          },
+          {
+            "id": "alert-action",
+            "name": "AlertAction",
+            "description": "An absolutely positioned slot in the top-right corner of the alert holding a single action control, usually an outline or ghost Button. Its presence adds right padding to the alert so the title and description never run underneath it. AlertAction is the container, not the control.",
+            "slot": "action",
+            "acceptsChildren": "components",
+            "categories": [
+              "interactive"
+            ]
+          }
+        ],
+        "notes": "Order the children as icon, AlertTitle, AlertDescription, AlertAction. The grid switches to a two-column layout only when a direct svg child is present, and it spans that icon across both text rows, so pass at most one icon and pass it as a direct child of Alert rather than nesting it inside the title. AlertAction is positioned absolutely wherever it appears in the markup; keep it last so the DOM order still matches the reading order. Alert has no close button and no dismiss state — if the message should go away on its own, it is a toast, not an alert."
+      },
+      "constraints": [
+        {
+          "context": "A persistent in-page message tied to a region, a form, or a record",
+          "rule": "Use Alert",
+          "severity": "should"
+        },
+        {
+          "context": "A transient confirmation of an action the user just completed",
+          "rule": "Use Sonner instead of Alert, so the message clears itself",
+          "severity": "should-not"
+        },
+        {
+          "context": "A message that must block the workflow until the user chooses",
+          "rule": "Use AlertDialog instead of Alert",
+          "severity": "must-not"
+        },
+        {
+          "context": "An Alert present in the initial render rather than appearing in response to an event",
+          "rule": "Pass role=\"status\" or role=\"note\" to override the built-in role=\"alert\", so a static callout does not interrupt the screen reader",
+          "severity": "should"
+        },
+        {
+          "context": "An error or failure message",
+          "rule": "Use variant=\"destructive\"",
+          "severity": "must"
+        },
+        {
+          "context": "Success and warning states, for which shadcn ships no variant",
+          "rule": "Add the tone with utility classes on className and keep the meaning in the title text and the icon; do not convey the state through colour alone",
+          "severity": "must"
+        },
+        {
+          "context": "Any alert",
+          "rule": "Include an AlertTitle so the message has a scannable headline",
+          "severity": "should"
+        },
+        {
+          "context": "The decorative icon passed as a direct child of Alert",
+          "rule": "Mark it aria-hidden=\"true\"; it duplicates the title",
+          "severity": "should"
+        },
+        {
+          "context": "Making the whole alert clickable",
+          "rule": "Put a real Button inside AlertAction instead of attaching a click handler to the Alert container",
+          "severity": "must-not"
+        },
+        {
+          "context": "More than one interactive control in a single alert",
+          "rule": "Reduce to one action in AlertAction, or move the decision into an AlertDialog; the action slot is a fixed corner position sized for a single control",
+          "severity": "should-not"
+        }
+      ],
+      "tokens": [
+        "card",
+        "card-foreground",
+        "muted-foreground",
+        "destructive",
+        "border",
+        "radius"
+      ],
+      "relatedComponents": [
+        "alert-dialog",
+        "sonner",
+        "badge",
+        "card"
+      ],
+      "tags": [
+        "feedback",
+        "callout",
+        "status",
+        "inline",
+        "messaging"
+      ],
+      "categories": [
+        "feedback"
+      ]
+    },
+    "progress": {
+      "name": "Progress",
+      "description": "A determinate progress bar built on Radix UI Progress. Renders a track with role=\"progressbar\" and an indicator whose horizontal offset is driven by the value prop, and publishes aria-valuenow, aria-valuemin, aria-valuemax, and aria-valuetext automatically. The shadcn wrapper renders both the track and the indicator itself and exports no sub-components.",
+      "status": "stable",
+      "whenToUse": "Use when completion can be expressed as a number the user can watch move: a file upload, a multi-step form, a quota filling up, an import job reporting processed records. Progress earns its place when quantifying the remaining work tells the user something a spinner cannot.",
+      "whenNotToUse": "Do not use when you cannot compute a percentage — an operation of unknown length needs a Spinner, and a page or panel waiting on its content needs a Skeleton. Do not use it as a gauge for a static quantity: a battery level, a score, or a disk-usage readout is a meter, not progress, and must not claim role=\"progressbar\". Do not use it as a decorative rule or as the connector line in a stepper.",
+      "props": {
+        "value": {
+          "type": "number",
+          "propRole": "state",
+          "required": true,
+          "description": "How much of the task is complete, on a 0–100 scale. Radix treats a missing or null value as indeterminate and drops aria-valuenow, but the shadcn wrapper computes the indicator offset as translateX(-${100 - (value || 0)}%), so omitting value paints a permanently empty track instead of an indeterminate animation. Always pass a number; when the duration is unknown, use Spinner instead."
+        },
+        "max": {
+          "type": "number",
+          "propRole": "dimension",
+          "default": 100,
+          "description": "Upper bound of value, published as aria-valuemax. Radix falls back to 100 when max is absent or not greater than zero. Note that the shipped indicator transform is hardcoded to a 0–100 scale: setting max to anything else keeps the ARIA values correct while rendering the bar at the wrong width. Normalise your value to a percentage before passing it, or edit the transform in progress.tsx."
+        },
+        "getValueLabel": {
+          "type": "function",
+          "propRole": "content",
+          "description": "(value, max) => string. Produces the aria-valuetext announced in place of the raw number; Radix's default returns a rounded percentage. Override it when a percentage is not the useful unit — \"3 of 8 files\", \"about 2 minutes left\" — so the announcement matches whatever is written next to the bar."
+        },
+        "className": {
+          "type": "string",
+          "propRole": "content",
+          "description": "Additional CSS classes. Use it to constrain the width (the track is w-full and fills its parent) and to override the shipped track height. Colour comes from the primary and muted tokens; restyling the indicator means editing progress.tsx, as the indicator is not reachable through props."
+        }
+      },
+      "accessibility": {
+        "role": "progressbar",
+        "labelRequirement": "required-accessible-name",
+        "requiredAttributes": [
+          {
+            "attribute": "aria-label",
+            "condition": "when no visible text names the progress bar",
+            "description": "Radix supplies the value attributes but never a name. Without aria-label or aria-labelledby the bar is announced as a bare percentage with no indication of what is progressing."
+          },
+          {
+            "attribute": "aria-labelledby",
+            "condition": "when a visible label or heading already names the progress bar",
+            "description": "Reference the id of that visible text rather than duplicating it in aria-label; shadcn's own example wires this up with the Field component. Use one or the other, never both."
+          },
+          {
+            "attribute": "aria-valuenow",
+            "condition": "always — applied automatically, never by hand",
+            "description": "Radix derives aria-valuenow, aria-valuemin, aria-valuemax, and aria-valuetext from value, max, and getValueLabel. A hand-written value disagrees with the rendered indicator the moment state changes, so change the value prop instead."
+          }
+        ],
+        "focusManagement": "Progress is not focusable and takes no part in the tab order. When the operation finishes and the bar is replaced, move focus deliberately to whatever the user should do next rather than letting it fall to the body.",
+        "notes": "Radix sets data-state to loading, complete, or indeterminate, which is available for styling. Screen readers do not reliably re-announce a progressbar as its value changes, and they do not announce completion — do not rely on the bar alone to report that a task finished; say so in a polite live region or in visible copy. If the bar reports a static quantity rather than an operation in flight, role=\"meter\" is the correct role and this is the wrong component."
+      },
+      "composition": {
+        "notes": "Progress renders the Radix Root and Indicator itself and exports no sub-components, so nothing goes inside it. Build the label and the numeric readout as siblings — shadcn's documented example composes Progress with Field for exactly this — and point aria-labelledby at the visible label."
+      },
+      "constraints": [
+        {
+          "context": "An operation whose completion can be expressed as a percentage",
+          "rule": "Use Progress with an explicit value",
+          "severity": "should"
+        },
+        {
+          "context": "An operation of unknown duration",
+          "rule": "Use Spinner instead of Progress; a progressbar with no value announces nothing useful and, as shipped, renders an empty track rather than an indeterminate animation",
+          "severity": "must-not"
+        },
+        {
+          "context": "Any progress bar",
+          "rule": "Give it an accessible name with aria-label, or with aria-labelledby pointing at the visible label",
+          "severity": "must"
+        },
+        {
+          "context": "A value on a scale other than 0–100",
+          "rule": "Normalise the value to a percentage before passing it; the shipped indicator transform ignores max",
+          "severity": "must"
+        },
+        {
+          "context": "A static quantity such as a battery level, disk usage, or a score",
+          "rule": "Use an element with role=\"meter\" instead of Progress",
+          "severity": "must-not"
+        },
+        {
+          "context": "Reporting that a task has finished",
+          "rule": "Announce completion in a polite live region or in visible copy as well; a progressbar reaching its maximum is not reliably announced",
+          "severity": "should"
+        },
+        {
+          "context": "Setting aria-valuenow, aria-valuemin, aria-valuemax, or aria-valuetext by hand",
+          "rule": "Let Radix derive them from value, max, and getValueLabel",
+          "severity": "must-not"
+        },
+        {
+          "context": "A unit the user cares about that is not a percentage",
+          "rule": "Pass getValueLabel so the announced text matches the visible readout",
+          "severity": "should"
+        }
+      ],
+      "tokens": [
+        "primary",
+        "muted"
+      ],
+      "relatedComponents": [
+        "spinner",
+        "skeleton"
+      ],
+      "tags": [
+        "feedback",
+        "loading",
+        "determinate",
+        "status",
+        "progress"
+      ],
+      "categories": [
+        "feedback"
+      ]
+    },
+    "skeleton": {
+      "name": "Skeleton",
+      "description": "A pulsing placeholder block that stands in for content that has not arrived yet. It is a single muted, rounded div with animate-pulse and no intrinsic size — you give it the shape of the content it replaces using utility classes. It carries no ARIA role and no loading semantics of its own; those belong to the region that contains it.",
+      "status": "stable",
+      "whenToUse": "Use when you already know the shape of the content that is loading and the wait is short enough that showing the layout reassures more than a spinner would: a card grid, the first page of a table, a profile header, a form being hydrated. Skeletons are most valuable when they hold the layout still so nothing jumps when the real content lands.",
+      "whenNotToUse": "Do not use for feedback on an action the user just triggered — a submitting button wants a Spinner inside it, not a placeholder where the control used to be. Do not use when real progress is measurable; that is Progress. Do not use for long or open-ended waits, where a repeating pulse becomes noise: show an explanatory empty or error state instead. Do not ship a skeleton whose dimensions differ from the content that replaces it.",
+      "props": {
+        "className": {
+          "type": "string",
+          "propRole": "content",
+          "required": true,
+          "description": "Utility classes that give the placeholder its size and shape. The component ships with no width and no height, so a Skeleton with no className renders a zero-size element and is invisible. Always pass at least a height and a width (h-4 w-[250px]), add rounded-full for avatars and other circles, and match the values to the real content so the layout does not shift on swap."
+        },
+        "aria-hidden": {
+          "type": "boolean",
+          "propRole": "flag",
+          "description": "Removes the placeholder from the accessibility tree. Skeletons carry no information — a screen reader walking a tree of empty divs learns nothing — so hide them and announce the loading state once on the containing region instead. The component does not set this for you."
+        }
+      },
+      "accessibility": {
+        "labelRequirement": "none",
+        "requiredAttributes": [
+          {
+            "attribute": "aria-hidden",
+            "condition": "on every Skeleton",
+            "description": "Set aria-hidden=\"true\" so assistive technology does not walk a tree of empty placeholder elements. The shipped component sets no role and no ARIA attributes of any kind."
+          },
+          {
+            "attribute": "aria-busy",
+            "condition": "on the container that will hold the loaded content",
+            "description": "Set aria-busy=\"true\" while the placeholders are showing and remove it when the real content renders, so assistive technology knows the region is incomplete rather than empty."
+          },
+          {
+            "attribute": "aria-live",
+            "condition": "on the region that reports the loading state",
+            "description": "Announce the transition once — a polite live region, or a visually hidden element with role=\"status\" containing text such as \"Loading results\", swapped for the count when the data arrives. Skeletons announce nothing themselves."
+          }
+        ],
+        "focusManagement": "Skeletons are not focusable and must not be made focusable. If a placeholder replaces a control the user had focused, focus is dropped to the body when the skeleton mounts — prefer disabling the control in place over swapping it for a skeleton, and restore focus deliberately when the content arrives.",
+        "notes": "The pulse comes from Tailwind's animate-pulse, which runs regardless of the user's motion preference. Add motion-reduce:animate-none (or scope the animation in CSS) so users who have asked for reduced motion get a static placeholder. Because the component is a bare div, everything about how the loading state is communicated — the busy state, the announcement, the eventual result — is the caller's responsibility."
+      },
+      "composition": {
+        "notes": "Skeleton has no sub-components. Build a placeholder by composing several Skeletons inside the same layout primitives the real content uses, so the two are structurally interchangeable and the swap causes no reflow. shadcn documents this pattern for avatars, cards, text runs, forms, and tables."
+      },
+      "constraints": [
+        {
+          "context": "Content whose layout is known and will arrive shortly",
+          "rule": "Use Skeleton shaped like the content it replaces",
+          "severity": "should"
+        },
+        {
+          "context": "Any Skeleton",
+          "rule": "Pass explicit size classes on className; the component has no intrinsic dimensions and renders invisibly without them",
+          "severity": "must"
+        },
+        {
+          "context": "A loading region built from skeletons",
+          "rule": "Mark the skeletons aria-hidden=\"true\" and announce the loading state once on the containing region",
+          "severity": "must"
+        },
+        {
+          "context": "A placeholder whose dimensions do not match the content that replaces it",
+          "rule": "Match the skeleton to the real layout so the page does not shift when content lands",
+          "severity": "must-not"
+        },
+        {
+          "context": "Users who have requested reduced motion",
+          "rule": "Suppress the pulse with motion-reduce:animate-none; animate-pulse does not honour the preference on its own",
+          "severity": "should"
+        },
+        {
+          "context": "Feedback for an action the user just triggered, such as a submitting button",
+          "rule": "Put a Spinner inside the control instead of replacing it with a Skeleton",
+          "severity": "should-not"
+        },
+        {
+          "context": "A load that fails or runs indefinitely",
+          "rule": "Replace the skeletons with an explanatory empty or error state rather than pulsing forever",
+          "severity": "must"
+        },
+        {
+          "context": "A control that the user may have focused",
+          "rule": "Disable it in place rather than swapping it for a Skeleton, so focus is not dropped to the body",
+          "severity": "should"
+        }
+      ],
+      "tokens": [
+        "muted",
+        "radius"
+      ],
+      "relatedComponents": [
+        "spinner",
+        "progress",
+        "card"
+      ],
+      "tags": [
+        "feedback",
+        "loading",
+        "placeholder",
+        "perceived-performance"
+      ],
+      "categories": [
+        "feedback"
+      ]
+    },
+    "spinner": {
+      "name": "Spinner",
+      "description": "An indeterminate loading indicator. It is a single lucide icon — Loader2Icon as shipped — rendered with animate-spin and a hardcoded role=\"status\" and aria-label=\"Loading\". There are no variants and no size prop: size and colour come from utility classes, and the icon is changed by editing the component rather than through a prop.",
+      "status": "stable",
+      "whenToUse": "Use for a wait whose length you cannot predict and whose shape you cannot draw: a button that has just submitted, a field validating against the server, an input group fetching suggestions, a small region refreshing in place. Spinner works best inside or beside the control that started the work, so the indicator is where the user is already looking.",
+      "whenNotToUse": "Do not use when completion is measurable — that is Progress. Do not use for the first paint of a page or panel whose layout you already know; Skeleton holds the layout and reads as faster. Do not scatter several spinners across one view: one indicator per in-flight operation, placed at the operation.",
+      "props": {
+        "className": {
+          "type": "string",
+          "propRole": "content",
+          "description": "Utility classes. Size the spinner with size-* — it ships at size-4 — and colour it with a text-* class. The icon draws with currentColor, so by default it inherits the colour of whatever it sits inside, which is usually what you want inside a Button or Badge."
+        },
+        "aria-label": {
+          "type": "string",
+          "propRole": "content",
+          "default": "Loading",
+          "description": "Accessible name of the indicator. The component sets \"Loading\" and spreads incoming props afterwards, so passing aria-label replaces it. Make it specific when more than one thing on the page can be loading (\"Loading search results\"), and localise it — the built-in string is English and is not translated."
+        },
+        "aria-hidden": {
+          "type": "boolean",
+          "propRole": "flag",
+          "description": "Removes the spinner from the accessibility tree. Set it to true whenever the surrounding control already announces the state — a Button whose accessible name changes to \"Saving…\", or a region with its own role=\"status\" — so the wait is announced once rather than twice."
+        }
+      },
+      "accessibility": {
+        "role": "status",
+        "labelRequirement": "required-accessible-name",
+        "requiredAttributes": [
+          {
+            "attribute": "aria-label",
+            "condition": "when the built-in \"Loading\" is ambiguous, or the interface is not in English",
+            "description": "Replace the hardcoded English default with a localised, specific name. The component supplies a name, so the requirement is already met by default — but the default is neither translated nor scoped to what is actually loading."
+          },
+          {
+            "attribute": "aria-hidden",
+            "condition": "when the spinner sits inside a control or region that already announces the loading state",
+            "description": "Set aria-hidden=\"true\" so the spinner's role=\"status\" does not compete with the announcement you already make on the control. Two live regions describing the same wait is worse than one."
+          }
+        ],
+        "focusManagement": "Spinner is not focusable and takes no part in the tab order. When it appears inside a Button, keep the Button mounted and set disabled rather than unmounting or replacing it, so focus is not dropped to the body while the operation runs.",
+        "notes": "role=\"status\" makes the icon a polite live region, but its content never changes after mount, and screen readers vary in whether they announce a live region that is itself inserted into the DOM. Do not rely on the spinner alone to tell a screen-reader user that work has started: change the control's accessible name (\"Save\" to \"Saving…\"), set aria-busy on the region, or announce the state in a live region you own — and mark the spinner aria-hidden so it does not duplicate that. animate-spin does not honour prefers-reduced-motion, so a continuously rotating indicator keeps rotating for users who have asked for less motion."
+      },
+      "composition": {
+        "notes": "Spinner has no sub-components — it is the thing that gets composed. shadcn documents it inside Button, Badge, InputGroup, and Empty; place it before the label with data-icon=\"inline-start\" or after it with data-icon=\"inline-end\" to control which side it sits on. To use a different icon, swap the lucide import in spinner.tsx; there is no icon prop and no size prop."
+      },
+      "constraints": [
+        {
+          "context": "An operation whose duration cannot be predicted",
+          "rule": "Use Spinner",
+          "severity": "should"
+        },
+        {
+          "context": "An operation whose completion can be quantified",
+          "rule": "Use Progress instead of Spinner",
+          "severity": "should-not"
+        },
+        {
+          "context": "The first load of a page or panel whose layout is known",
+          "rule": "Use Skeleton instead of Spinner so the layout does not shift when content arrives",
+          "severity": "should-not"
+        },
+        {
+          "context": "A button that has triggered an async action",
+          "rule": "Keep the Button mounted and disabled with the Spinner inside it, rather than unmounting or replacing the control",
+          "severity": "should"
+        },
+        {
+          "context": "A spinner inside a control that already announces its own loading state",
+          "rule": "Set aria-hidden=\"true\" on the Spinner so the state is announced once",
+          "severity": "must"
+        },
+        {
+          "context": "A spinner that is the only signal that work has started",
+          "rule": "Also change the control's accessible name or set aria-busy on the region; a static role=\"status\" element is not reliably announced when it is inserted into the DOM",
+          "severity": "must"
+        },
+        {
+          "context": "An interface that is not in English",
+          "rule": "Pass a localised aria-label; the built-in \"Loading\" string is hardcoded and untranslated",
+          "severity": "must"
+        },
+        {
+          "context": "Users who have requested reduced motion",
+          "rule": "Stop or slow the rotation; animate-spin runs regardless of the prefers-reduced-motion setting",
+          "severity": "should"
+        },
+        {
+          "context": "Several concurrent operations in one view",
+          "rule": "Show one spinner per in-flight operation, positioned at that operation, rather than a single global indicator or a field of spinners",
+          "severity": "should"
+        }
+      ],
+      "tokens": [],
+      "relatedComponents": [
+        "skeleton",
+        "progress",
+        "button",
+        "badge"
+      ],
+      "tags": [
+        "feedback",
+        "loading",
+        "indeterminate",
+        "status",
+        "icon"
+      ],
+      "categories": [
+        "feedback"
+      ]
+    },
+    "sonner": {
+      "name": "Sonner",
+      "description": "The toast system shadcn ships, wrapping the sonner library. The registry item installs exactly one component — Toaster — which you mount once at the root of the app and theme through next-themes. Individual toasts are not written as JSX: you call toast() from the sonner package anywhere in your code and the mounted Toaster renders, stacks, and expires them. A toast's title, description, icon, action, and cancel button are all options on that call.",
+      "status": "stable",
+      "whenToUse": "Use to confirm the outcome of something the user just did, when the message is short, needs no response, and can be missed without consequence: \"Event created\", \"Copied to clipboard\", \"Changes saved\". Use toast.promise for an async action that should report loading and then success or failure from a single call site.",
+      "whenNotToUse": "Do not use for anything the user must read or act on. A toast disappears on a timer, is announced only politely, and sits outside the tab order — an error that blocks progress belongs in an Alert beside the thing that failed, and a decision belongs in an AlertDialog. Do not use it for field-level validation errors; put those on the field. Do not narrate a process with a run of toasts; only a few are visible at a time and the rest collapse.",
+      "props": {
+        "position": {
+          "type": "enum",
+          "propRole": "choice",
+          "values": [
+            {
+              "value": "bottom-right",
+              "description": "The default. Least intrusive on desktop, and furthest from primary content."
+            },
+            {
+              "value": "bottom-center",
+              "description": "Reads as a status line along the bottom edge. Works well in mobile-first layouts where the thumb is already there."
+            },
+            {
+              "value": "bottom-left",
+              "description": "Keeps toasts clear of a right-hand rail, inspector, or chat launcher."
+            },
+            {
+              "value": "top-right",
+              "description": "Common when the primary actions live in the top bar, so feedback appears near the control that produced it."
+            },
+            {
+              "value": "top-center",
+              "description": "The most noticeable placement. Use it when toasts carry information users should not miss, and nothing else is anchored to the top."
+            },
+            {
+              "value": "top-left",
+              "description": "Useful in RTL layouts, or when the bottom of the viewport is occupied by fixed chrome."
+            }
+          ],
+          "default": "bottom-right",
+          "description": "Where the stack is anchored in the viewport. It also determines the default swipe-to-dismiss directions. Individual toasts can override it per call, but a stable position is easier to learn."
+        },
+        "theme": {
+          "type": "enum",
+          "propRole": "choice",
+          "values": [
+            {
+              "value": "system",
+              "description": "Follows the OS colour scheme. This is what the shadcn wrapper passes when next-themes has no explicit preference."
+            },
+            {
+              "value": "light",
+              "description": "Force the light surface regardless of the app theme."
+            },
+            {
+              "value": "dark",
+              "description": "Force the dark surface regardless of the app theme."
+            }
+          ],
+          "default": "system",
+          "description": "Colour scheme of the toasts. The shadcn wrapper already reads the app theme from next-themes and passes it down, so you normally leave this alone; because props are spread last, passing it explicitly overrides the wired-up theme and can desynchronise toasts from the rest of the UI."
+        },
+        "richColors": {
+          "type": "boolean",
+          "propRole": "flag",
+          "default": false,
+          "description": "Tints success, error, warning, and info toasts with their semantic colours instead of the neutral popover surface. The built-in icons already distinguish the types, so treat this as emphasis rather than as the signal — and check the tinted surfaces for contrast in both themes before enabling it."
+        },
+        "closeButton": {
+          "type": "boolean",
+          "propRole": "flag",
+          "default": false,
+          "description": "Renders a dismiss button on every toast. Turn it on when toasts carry actions or text that takes longer than the duration to read; without it a toast can only be dismissed by swiping or by waiting it out."
+        },
+        "expand": {
+          "type": "boolean",
+          "propRole": "flag",
+          "default": false,
+          "description": "Shows the stack expanded rather than collapsed. By default only the front toast is fully visible and the stack expands on hover or when the notification hotkey is pressed."
+        },
+        "visibleToasts": {
+          "type": "number",
+          "propRole": "dimension",
+          "default": 3,
+          "description": "How many toasts are rendered at once; the rest queue behind them. Raising it makes the stack harder to scan and pushes more content over the page, so prefer fixing the code that emits a flood of toasts."
+        },
+        "duration": {
+          "type": "number",
+          "propRole": "dimension",
+          "default": 4000,
+          "description": "Milliseconds a toast stays on screen before auto-dismissing, applied to every toast unless a call overrides it. Four seconds is not enough time to read a message, decide, and act, so raise it for any toast that carries an action."
+        },
+        "offset": {
+          "type": "string | number | object",
+          "propRole": "dimension",
+          "default": "32px",
+          "description": "Distance from the viewport edge. Accepts one value or an object of top/right/bottom/left. Increase it when fixed chrome — a bottom bar, a consent banner, a floating action button — would otherwise sit under the toasts."
+        },
+        "mobileOffset": {
+          "type": "string | number | object",
+          "propRole": "dimension",
+          "default": "16px",
+          "description": "Offset applied at mobile widths, where a large inset wastes scarce vertical space. Set it alongside offset whenever you change the desktop value."
+        },
+        "dir": {
+          "type": "enum",
+          "propRole": "choice",
+          "values": [
+            {
+              "value": "ltr",
+              "description": "Left-to-right. The default."
+            },
+            {
+              "value": "rtl",
+              "description": "Right-to-left, for Arabic, Hebrew, and other RTL locales."
+            },
+            {
+              "value": "auto",
+              "description": "Reads the direction from the document at render time. Prefer this in apps that switch locales at runtime."
+            }
+          ],
+          "default": "ltr",
+          "description": "Text direction of the toast list. It also affects which swipe directions dismiss a toast, so set it rather than relying on CSS alone in bidirectional interfaces."
+        },
+        "hotkey": {
+          "type": "array",
+          "propRole": "content",
+          "default": [
+            "altKey",
+            "KeyT"
+          ],
+          "description": "Key combination that expands the stack and moves focus into the notification region. This is the only keyboard route to a toast, and its human-readable form is appended to the region's accessible name (\"Notifications alt+T\"), so changing it changes what screen readers announce."
+        },
+        "invert": {
+          "type": "boolean",
+          "propRole": "flag",
+          "default": false,
+          "description": "Inverts toast colours against the current theme so they read as the opposite surface. Use it sparingly: it breaks the visual relationship between the toast and the rest of the interface, and it interacts badly with richColors."
+        },
+        "icons": {
+          "type": "object",
+          "propRole": "content",
+          "description": "Map of toast type to the node rendered as its icon — success, info, warning, error, and loading. The shadcn wrapper already fills all five with lucide icons and animates the loading one; override it only to match a different icon set, and keep all five so the types stay distinguishable."
+        },
+        "toastOptions": {
+          "type": "object",
+          "propRole": "content",
+          "description": "Defaults applied to every toast: duration, className and classNames, closeButton, style, and the other per-toast options. It is spread onto the underlying Toaster after the wrapper's own toastOptions, so passing it replaces rather than merges with whatever the shipped component set."
+        },
+        "containerAriaLabel": {
+          "type": "string",
+          "propRole": "content",
+          "default": "Notifications",
+          "description": "Accessible name of the notification region, before the hotkey label is appended to it. The default is English; localise it in any non-English interface."
+        },
+        "className": {
+          "type": "string",
+          "propRole": "content",
+          "description": "Classes applied to the toast list element. The shipped wrapper already sets \"toaster group\" on it, and because props are spread last, passing className replaces that rather than adding to it. To style individual toasts, use toastOptions.classNames."
+        }
+      },
+      "accessibility": {
+        "role": "region",
+        "labelRequirement": "required-accessible-name",
+        "requiredAttributes": [
+          {
+            "attribute": "aria-live",
+            "condition": "always — applied by sonner to the notification region",
+            "description": "Sonner puts aria-live=\"polite\", aria-relevant=\"additions text\", and aria-atomic=\"false\" on the wrapping region and leaves the individual toasts without any role. Every toast — including error toasts — is therefore announced politely, after whatever the screen reader is currently saying. There is no assertive path; if a message must interrupt, it should not be a toast."
+          },
+          {
+            "attribute": "aria-label",
+            "condition": "when the interface is not in English",
+            "description": "Pass containerAriaLabel to localise the region's name, or customAriaLabel to replace the whole string including the hotkey suffix. The default is \"Notifications\" with the hotkey label appended."
+          }
+        ],
+        "keyboardInteractions": [
+          {
+            "key": "Alt + T",
+            "description": "The default hotkey. Expands the stack and moves focus into the toast list. Toasts are deliberately outside the normal tab order, so this is the only way to reach one from the keyboard."
+          },
+          {
+            "key": "Tab",
+            "description": "Once focus is inside the region, moves through the toasts and their action, cancel, and close buttons, then leaves the region and returns to the document."
+          },
+          {
+            "key": "Escape",
+            "description": "Collapses the expanded stack while focus is inside the region. It does not dismiss the toasts."
+          },
+          {
+            "key": "Enter",
+            "description": "Activates the focused action, cancel, or close button."
+          },
+          {
+            "key": "Space",
+            "description": "Activates the focused action, cancel, or close button."
+          }
+        ],
+        "focusManagement": "Toasts never take focus when they appear — that is the point of the pattern, and it is why they must not carry anything essential. Focus enters the region only through the hotkey, and sonner restores focus to the previously focused element when focus leaves the region or the region unmounts. A toast can auto-dismiss while a keyboard user is still tabbing through it, so never put the only copy of an action inside one.",
+        "notes": "Individual toasts carry no role of their own — not role=\"alert\", not role=\"status\" — and are announced only because they are inserted into the wrapping polite live region. That makes toasts unsuitable for urgent content: an error that must interrupt belongs in an Alert next to the failure, or in an AlertDialog if a decision is needed. Because toasts sit outside the tab order, a keyboard user who does not know the hotkey cannot reach an action inside one before it expires. Duration is an accessibility constraint, not a style preference: WCAG SC 2.2.1 (Timing Adjustable) covers content that disappears on a timer, so raise duration and enable closeButton for anything actionable."
+      },
+      "composition": {
+        "notes": "There are no sub-components. A toast's anatomy — type icon, title, description, action button, cancel button, and the optional close button — is data passed to the toast() call, not JSX you nest. The surface is toast(title, options) plus toast.success, toast.info, toast.warning, toast.error, toast.loading, toast.message, toast.promise, toast.custom, and toast.dismiss(id), imported from the sonner package rather than from your components directory; the registry item's only export is Toaster. The rendered structure is Toaster > notification region > toast list > toast, and none of those levels is addressable as a component. Mount exactly one Toaster in the root layout, outside any conditionally rendered subtree, and every toast() call in the app renders into it."
+      },
+      "constraints": [
+        {
+          "context": "Confirming a short, non-blocking outcome of an action the user just took",
+          "rule": "Use Sonner",
+          "severity": "should"
+        },
+        {
+          "context": "Anywhere in the application",
+          "rule": "Mount exactly one Toaster, in the root layout; a second one splits the queue and produces duplicate announcements",
+          "severity": "must"
+        },
+        {
+          "context": "An error the user must act on, or information they must not miss",
+          "rule": "Use an Alert beside the thing that failed instead of a toast; toasts auto-dismiss, are announced only politely, and sit outside the tab order",
+          "severity": "must-not"
+        },
+        {
+          "context": "A message that requires a decision before the user can continue",
+          "rule": "Use AlertDialog instead of a toast",
+          "severity": "must-not"
+        },
+        {
+          "context": "Validation errors on a specific form field",
+          "rule": "Render the error on the field rather than in a toast",
+          "severity": "must-not"
+        },
+        {
+          "context": "A toast that carries an action such as Undo",
+          "rule": "Raise duration, enable closeButton, and provide a permanent way to perform the same action elsewhere; a keyboard or screen-reader user may never reach the toast before it expires",
+          "severity": "must"
+        },
+        {
+          "context": "An async operation reported from a single call site",
+          "rule": "Use toast.promise so one toast moves through loading, success, and error rather than stacking three",
+          "severity": "should"
+        },
+        {
+          "context": "Signalling the kind of a toast",
+          "rule": "Call the typed helper (toast.success, toast.error, toast.warning, toast.info) so the correct icon renders; do not rely on richColors alone to carry the meaning",
+          "severity": "must"
+        },
+        {
+          "context": "An interface that is not in English",
+          "rule": "Pass containerAriaLabel so the notification region is named in the user's language",
+          "severity": "must"
+        },
+        {
+          "context": "A sequence of steps the user should be able to review",
+          "rule": "Write the outcome into the page — a log, a status column, an Alert — instead of emitting a run of toasts that expire unread",
+          "severity": "should-not"
+        }
+      ],
+      "tokens": [
+        "popover",
+        "popover-foreground",
+        "border",
+        "radius"
+      ],
+      "relatedComponents": [
+        "alert",
+        "alert-dialog",
+        "button"
+      ],
+      "tags": [
+        "feedback",
+        "toast",
+        "notification",
+        "transient",
+        "imperative",
+        "overlay"
+      ],
+      "categories": [
+        "feedback",
+        "overlay"
+      ]
+    }
+  },
+  "categories": {
+    "interactive": {
+      "name": "Interactive",
+      "description": "Receives pointer or keyboard activation: buttons, inputs, menu items, and trigger/action/cancel sub-components. Category-based composition rules select by this instead of enumerating ids."
+    },
+    "overlay": {
+      "name": "Overlay",
+      "description": "Renders content in a layer above the page with its own focus and dismiss semantics: dialogs, alert dialogs, dropdown menus."
+    },
+    "form": {
+      "name": "Form",
+      "description": "Form structure and controls: field wrappers, labels, descriptions, validation messages, and the inputs they name."
+    },
+    "layout": {
+      "name": "Layout",
+      "description": "Arranges, bounds, or separates other content without presenting content of its own: separators, scroll containers, ratio boxes, and structural wrappers."
+    },
+    "content": {
+      "name": "Content",
+      "description": "Presents content directly — text, media, labels, and identity: avatars and their images and fallbacks, disclosure panels, captions."
+    },
+    "feedback": {
+      "name": "Feedback",
+      "description": "Communicates system state to the user: alerts, progress, loading placeholders, and transient notifications."
+    },
+    "navigation": {
+      "name": "Navigation",
+      "description": "Moves the user between views or between panels of one view: tabs, breadcrumbs, and pagination."
+    }
+  },
+  "patterns": [
+    {
+      "id": "destructive-action-confirmation",
+      "name": "Destructive Action Confirmation",
+      "description": "A confirmation flow for actions that are irreversible or have significant consequences, using AlertDialog to require explicit user acknowledgment.",
+      "intent": "Prevent accidental data loss or irreversible state changes by requiring the user to explicitly confirm before proceeding.",
+      "context": "Use whenever an action cannot be undone: deleting a record, removing a team member, clearing form data, revoking access, or any operation the user might regret if triggered accidentally.",
+      "components": [
+        "alert-dialog",
+        "button"
+      ],
+      "guidance": "Use AlertDialog, not Dialog, for destructive confirmations. The trigger should clearly indicate the destructive nature of the action. Inside the AlertDialog, provide a clear title stating what will happen, a description of the consequences, and two actions: a cancel option and a confirm option. The confirm button MUST use the destructive variant. Place the cancel action before the confirm action in the footer. The description should state specifically what will be affected (e.g., 'This will permanently delete 3 projects and all associated data').",
+      "relatedPatterns": [],
+      "tags": [
+        "confirmation",
+        "destructive",
+        "modal",
+        "safety"
+      ]
+    },
+    {
+      "id": "form-field-layout",
+      "name": "Form Field Layout",
+      "description": "Standard arrangement of form controls within a Card container, providing consistent structure for data entry interfaces.",
+      "intent": "Give forms a consistent visual structure that groups related inputs, separates them from surrounding content, and provides clear hierarchy through Card sub-components.",
+      "context": "Use for settings panels, profile editors, checkout flows, or any interface where the user enters structured data across multiple fields.",
+      "components": [
+        "card",
+        "input",
+        "button"
+      ],
+      "guidance": "Wrap the form in a Card. Use CardHeader with CardTitle and CardDescription to introduce the form's purpose. Place inputs inside CardContent with consistent vertical spacing (space-y-4 or equivalent). Group related fields together. Place primary actions (submit, save) in CardFooter. Labels should be associated with inputs for accessibility. Required fields should be visually indicated.",
+      "relatedPatterns": [
+        "destructive-action-confirmation"
+      ],
+      "tags": [
+        "form",
+        "layout",
+        "data-entry"
+      ]
+    },
+    {
+      "id": "contextual-actions-menu",
+      "name": "Contextual Actions Menu",
+      "description": "A pattern for exposing a set of context-sensitive actions through a dropdown menu triggered by an icon button.",
+      "intent": "Keep interfaces clean by collecting secondary or overflow actions behind a single trigger, while maintaining discoverability through a familiar interaction pattern.",
+      "context": "Use for row-level actions in tables or lists, overflow menus in toolbars, or any place where multiple actions apply to a single item but showing all of them inline would be visually noisy.",
+      "components": [
+        "dropdown-menu",
+        "button"
+      ],
+      "guidance": "Use a Button with the ghost variant and icon size as the DropdownMenuTrigger. A vertical ellipsis icon is the conventional trigger for contextual menus. Group related actions with DropdownMenuGroup and separate groups with DropdownMenuSeparator. Place destructive actions (delete, remove) at the end of the menu, visually distinguished. Include keyboard shortcuts in DropdownMenuItem when available.",
+      "relatedPatterns": [
+        "destructive-action-confirmation"
+      ],
+      "tags": [
+        "actions",
+        "menu",
+        "overflow"
+      ]
+    },
+    {
+      "id": "data-table-with-row-actions",
+      "name": "Data Table with Row Actions",
+      "description": "An enterprise data table that presents records with a sortable header, a status column, and a trailing column of per-row actions — including destructive ones routed through a confirmation. Composes the Table primitives with Badge for status, a DropdownMenu (via the contextual-actions-menu pattern) for the actions column, and AlertDialog (via the destructive-action-confirmation pattern) for destructive actions.",
+      "intent": "Let users scan and act on a list of records — reviewing each row's status and reaching its actions — without sacrificing the semantics, keyboard access, or safety guarantees that the underlying components provide.",
+      "context": "Use for access-management and administrative surfaces: a members table, a users-and-roles list, an API-keys table, or any view where each row is an entity with a status and a set of actions, some of which (remove, revoke access) are destructive.",
+      "components": [
+        "table",
+        "badge",
+        "button",
+        "dropdown-menu",
+        "alert-dialog"
+      ],
+      "guidance": "Build the table from the Table primitives: a TableHeader row of TableHead cells, a TableBody of one TableRow per record, and a TableCaption (or aria-label) naming the table. Make sortable columns real controls — render a ghost Button inside the TableHead and set aria-sort on that TableHead to ascending, descending, or none, with only one column sorted at a time. Render the status column with a Badge whose variant reflects state (for example default or secondary for active and pending, destructive for suspended or revoked); because Badge is presentational, keep the status readable as text so it is announced by assistive technology, not conveyed by color alone. Put per-row actions in a trailing TableCell as a contextual-actions-menu: a ghost icon Button (a vertical ellipsis) as the DropdownMenuTrigger opening a DropdownMenu of actions, with an aria-label on the trigger. Route every destructive row action — remove, revoke access — through the destructive-action-confirmation pattern using AlertDialog, never Dialog, so the action cannot be dismissed by accident; the AlertDialogDescription should name the specific record affected (for example 'This revokes Jordan Lee's access to the Acme workspace'). Do not make the entire TableRow a single clickable target while it also contains its own action controls — that is the nested-interactive-elements anti-pattern, which produces ambiguous click targets and unpredictable behavior for keyboard and screen-reader users; if rows need a primary navigation, expose it as a distinct link or cell control rather than wrapping the row.",
+      "relatedPatterns": [
+        "contextual-actions-menu",
+        "destructive-action-confirmation"
+      ],
+      "tags": [
+        "table",
+        "data",
+        "actions",
+        "access-management",
+        "destructive"
+      ]
+    }
+  ],
+  "antiPatterns": [
+    {
+      "id": "dialog-for-destructive-actions",
+      "name": "Using Dialog for Destructive Confirmations",
+      "description": "Using the dismissible Dialog component instead of AlertDialog when confirming a destructive or irreversible action.",
+      "reason": "Dialog can be dismissed by clicking the overlay or pressing Escape, which means a user can accidentally bypass the confirmation without making a conscious choice. AlertDialog forces the user to select an explicit action (confirm or cancel), providing a stronger safeguard against accidental destructive operations. This distinction also matters for accessibility: screen readers announce AlertDialog with greater urgency.",
+      "severity": "must-not",
+      "insteadUse": "destructive-action-confirmation",
+      "components": [
+        "dialog",
+        "alert-dialog"
+      ],
+      "tags": [
+        "modal",
+        "destructive",
+        "accessibility"
+      ]
+    },
+    {
+      "id": "nested-interactive-elements",
+      "name": "Nesting Interactive Elements",
+      "description": "Placing a clickable or focusable element (Button, Link, Input) inside another clickable element (a clickable Card, a Button, or a Link).",
+      "reason": "Nested interactive elements create ambiguous click targets and are a significant accessibility violation. Screen readers cannot determine user intent when interactive elements are nested, and the resulting behavior varies unpredictably across browsers. The outer element may intercept clicks intended for the inner element, or both may fire, leading to unexpected navigation or duplicate actions.",
+      "severity": "must-not",
+      "components": [
+        "button",
+        "card",
+        "input"
+      ],
+      "tags": [
+        "accessibility",
+        "interaction",
+        "html-semantics"
+      ]
+    },
+    {
+      "id": "div-as-button",
+      "name": "Using a Styled Div as a Button",
+      "description": "Creating a clickable element by adding an onClick handler and visual styles to a <div> or <span> instead of using the Button component or a native <button> element.",
+      "reason": "A styled div lacks keyboard accessibility (not focusable by default, does not respond to Enter or Space), is not announced as a button by screen readers, and does not participate in form submission. The Button component handles all of these concerns. Using a div requires manually re-implementing focus management, keyboard handling, and ARIA attributes — work that is error-prone and already solved by the component.",
+      "severity": "must-not",
+      "components": [
+        "button"
+      ],
+      "tags": [
+        "accessibility",
+        "semantics",
+        "component-misuse"
+      ]
+    }
+  ],
+  "intents": [
+    {
+      "id": "destructive-action",
+      "name": "Destructive action",
+      "description": "The requested UI performs an irreversible or high-consequence operation: deleting records or accounts, revoking access, removing members.",
+      "relatedPatterns": [
+        "destructive-action-confirmation"
+      ]
+    },
+    {
+      "id": "record-collection",
+      "name": "Record collection",
+      "description": "Surfaces that present many records of the same kind — support tickets, orders, members — for scanning and action. Records share uniform fields, so the collection renders as a semantic data table built from the Table primitives; status stays readable as text (badges are appropriate, color is never the only signal). Per-row actions and destructive confirmations follow the data-table-with-row-actions pattern as guidance until the dropdown-menu item vocabulary is specified.",
+      "relatedPatterns": [
+        "data-table-with-row-actions"
+      ]
+    },
+    {
+      "id": "structured-input",
+      "name": "Structured input",
+      "description": "The requested UI collects structured values and commits them on an explicit action — a profile editor, a checkout step, a create-record form. Every control is named by a visible Label bound with htmlFor and id; placeholder text disappears on input and is never the accessible name. The control follows the shape of the answer: Input for a single line, Textarea for prose, RadioGroup for two to five exclusive options, Select for six or more, Checkbox for options that are independent of each other. Label, description, and error are associated through exactly one family per field — the react-hook-form Form parts, which generate the ids, or the Field parts, which require them to be written by hand — never a mix of the two.",
+      "relatedPatterns": [
+        "form-field-layout"
+      ]
+    },
+    {
+      "id": "preference-settings",
+      "name": "Preference settings",
+      "description": "A panel of settings that take effect the moment they change, with no Save step — notification preferences, workspace defaults, feature toggles. Each one is a Switch with a visible Label naming the setting rather than its current state (\"Email notifications\", never \"On\"); a Checkbox belongs here only when the change is staged for an explicit submit, and three or more choices are a RadioGroup or a Select, never a row of Switches. A toggle backed by a network write reflects the persisted result instead of an optimistic position that lies about the setting, and one whose effect is destructive or hard to reverse — disabling two-factor authentication — is confirmed before it applies.",
+      "relatedPatterns": [
+        "destructive-action-confirmation"
+      ]
+    },
+    {
+      "id": "record-detail",
+      "name": "Record detail",
+      "description": "One entity presented for reading, with its actions attached — a member profile, an order summary, a ticket's detail pane. The record is grouped in a single Card and given hierarchy with headings and spacing rather than a Card nested inside another Card, and the Card itself is never the click target: actions are real controls placed inside it. Identity renders as an Avatar with a fallback that fills the box when the image never arrives and alt text carrying the name; thumbnails, cover art, and product photos are not identities and belong in an AspectRatio instead. Status reads as text — a Badge carries the tone, and a presence dot is restated in words, because a coloured dot has no accessible name. The record's secondary actions collect behind one named overflow trigger rather than crowding the header.",
+      "relatedPatterns": [
+        "contextual-actions-menu"
+      ]
+    },
+    {
+      "id": "overlay-task",
+      "name": "Overlay task",
+      "description": "A focused task or detail the user completes without leaving the page behind it — editing a record, filtering a list, picking a date. The container follows how much of the user's attention the task must own: Popover for transient content anchored to the control that opened it, Dialog when the task deserves a focus trap, Sheet when it needs a full edge panel such as mobile navigation or a record editor. The panel names itself — a SheetTitle, visually hidden if the design shows none, and a PopoverContent wired by aria-labelledby to its title, which Radix Popover does not do for you. A trigger that is already a Button uses asChild rather than nesting a button inside a button. Confirming a destructive action is never one of these."
+    },
+    {
+      "id": "panel-navigation",
+      "name": "Panel navigation",
+      "description": "One subject with several peer views the user switches between in place — Overview, Activity, and Settings on a record; Monthly and Yearly on a report. These are Tabs, not links: a view the user should be able to link to, bookmark, or reach with the back button is a route and belongs in navigation rather than in a tab set. Each trigger and its panel share a value unique within the set, the root supplies a defaultValue (or a controlled value) so one panel starts visible, and the tablist is given an accessible name when no visible heading names it. Unselected panels are unmounted, so anything that must be printable, comparable side by side, or reachable by find-in-page does not live in one."
+    },
+    {
+      "id": "wayfinding",
+      "name": "Wayfinding",
+      "description": "Controls that say where the user is and move them to another addressable position — the trail from the workspace root down to the record on screen, the pager beneath a long collection. Both render nav landmarks around a list of real anchors: every BreadcrumbLink and every PaginationLink carries an href, because an anchor without one is neither focusable nor announced as a link. Exactly one crumb is the BreadcrumbPage and exactly one pager link is active, so exactly one control carries aria-current=\"page\". The ellipsis in either family is decorative and aria-hidden, never the affordance for reaching what it hides — the collapsed items need a real control with its own accessible name."
+    },
+    {
+      "id": "supplementary-detail",
+      "name": "Supplementary detail",
+      "description": "Detail the user may want but does not need in order to finish the task — what an icon-only button does, what an abbreviated column header means, the terms behind a one-line summary. A Tooltip holds a short phrase about the control it is attached to: it never receives focus, closes on click, and is absent entirely on touch, so it may hold no links or buttons and nothing required to complete the task, and it describes a control rather than naming it — an icon-only control still carries its own aria-label. Content the user can act on, or must read at their own pace, belongs in a named Popover or in an Accordion whose triggers hold no nested controls; a closed panel is unmounted, so nothing that must be reachable by find-in-page or print goes inside one."
+    },
+    {
+      "id": "status-feedback",
+      "name": "Status feedback",
+      "description": "The surface reports an outcome or a condition the user needs to know about — a save succeeded, an import partly failed, a workspace is over quota. Placement follows persistence and consequence: an Alert sits beside the thing it describes and stays there; a toast confirms something transient and clears itself, so it must never carry an error the user has to act on, a field's validation message, or information they cannot afford to miss. Errors take Alert's destructive variant, and because shadcn ships no success or warning variant, that meaning lives in the title text and the icon rather than in colour alone. A message that must block until the user chooses is not a status message but a confirmation."
+    },
+    {
+      "id": "loading-state",
+      "name": "Loading state",
+      "description": "The surface stands in for work that has not finished — a panel fetching its first page, a form mid-submit, a file uploading. The indicator follows what is known about the work: a Skeleton shaped like the content when the layout is known, a Spinner when the duration cannot be predicted, and Progress only when completion is a real percentage, since a progressbar with no value announces nothing and renders an empty track. Skeletons are aria-hidden and the loading state is announced once on the region that contains them; a control the user has just activated stays mounted and disabled with the spinner inside it rather than being swapped for a placeholder that drops focus. Nothing pulses forever — a load that fails resolves to an explanatory error or empty state."
+    }
+  ],
+  "rules": [
+    {
+      "id": "rule.destructive-requires-alertdialog",
+      "type": "component-choice",
+      "severity": "must",
+      "appliesTo": {
+        "intents": [
+          "destructive-action"
+        ]
+      },
+      "require": [
+        "alert-dialog"
+      ],
+      "forbid": [
+        "dialog"
+      ],
+      "rationale": "Dialog can be dismissed by clicking the overlay or pressing Escape, so a user can bypass a destructive confirmation without making a conscious choice. AlertDialog forces an explicit confirm/cancel decision and is announced with greater urgency by screen readers.",
+      "examples": [
+        "ex.delete-account-confirmation"
+      ],
+      "tags": [
+        "safety",
+        "accessibility"
+      ]
+    },
+    {
+      "id": "rule.alertdialog-requires-cancel",
+      "type": "required-composition",
+      "severity": "must",
+      "component": "alert-dialog",
+      "requiredSubComponents": [
+        {
+          "id": "alert-dialog-cancel",
+          "min": 1
+        },
+        {
+          "id": "alert-dialog-title",
+          "min": 1
+        }
+      ],
+      "rationale": "A confirmation without an explicit cancel action and a title naming the consequence funnels the user toward the destructive action; the title is also required for aria-labelledby.",
+      "examples": [
+        "ex.delete-account-confirmation"
+      ],
+      "tags": [
+        "safety",
+        "accessibility"
+      ]
+    },
+    {
+      "id": "rule.button-no-interactive-descendants",
+      "type": "forbidden-composition",
+      "severity": "must",
+      "component": "button",
+      "forbiddenDescendants": [
+        "button",
+        "input"
+      ],
+      "rationale": "Nested interactive elements create ambiguous click targets and are an accessibility violation: screen readers cannot determine intent and click handling varies across browsers.",
+      "examples": [
+        "ex.delete-account-confirmation"
+      ],
+      "tags": [
+        "accessibility",
+        "interaction"
+      ]
+    },
+    {
+      "id": "rule.trigger-carries-label",
+      "type": "required-props",
+      "severity": "must",
+      "component": "alert-dialog-trigger",
+      "requiredText": true,
+      "textScope": "subtree",
+      "rationale": "The trigger must present an accessible label: non-empty text somewhere under the trigger. Protocol projections lift the label from the trigger's subtree (preferring a label-bearing button; lifts are audited) — a trigger with no label text anywhere yields a control with no accessible name and an instance downstream emitters must refuse.",
+      "examples": [
+        "ex.delete-account-confirmation"
+      ],
+      "tags": [
+        "accessibility",
+        "projection"
+      ]
+    },
+    {
+      "id": "rule.alertdialog-no-nested-overlays",
+      "type": "forbidden-composition",
+      "severity": "must",
+      "component": "alert-dialog",
+      "forbiddenCategories": [
+        "overlay"
+      ],
+      "rationale": "An alert dialog is a single focused interruption. Stacking another overlay (dialog, dropdown menu, another alert dialog) inside it breaks focus containment and dismiss semantics and buries the confirmation decision under a second layer.",
+      "tags": [
+        "accessibility",
+        "interaction"
+      ]
+    },
+    {
+      "id": "rule.record-collection-requires-table",
+      "type": "component-choice",
+      "severity": "must",
+      "appliesTo": {
+        "intents": [
+          "record-collection"
+        ]
+      },
+      "require": [
+        "table"
+      ],
+      "rationale": "The data-table-with-row-actions pattern: a record collection is built from the Table primitives, not prose or ad-hoc stacks. Records share uniform fields; a semantic table is how they stay scannable, sortable, and navigable by assistive technology.",
+      "examples": [
+        "ex.support-ticket-queue"
+      ],
+      "tags": [
+        "structure"
+      ]
+    },
+    {
+      "id": "rule.table-carries-structure",
+      "type": "required-composition",
+      "severity": "must",
+      "appliesTo": {
+        "intents": [
+          "record-collection"
+        ]
+      },
+      "component": "table",
+      "requiredSubComponents": [
+        {
+          "id": "table-header",
+          "min": 1
+        },
+        {
+          "id": "table-body",
+          "min": 1
+        }
+      ],
+      "rationale": "The table's own constraints demand semantic structure: header cells as th within a TableHeader so screen readers can associate columns, and records inside a TableBody. A table without both is a grid of divs wearing table styling.",
+      "examples": [
+        "ex.support-ticket-queue"
+      ],
+      "tags": [
+        "structure",
+        "accessibility"
+      ]
+    },
+    {
+      "id": "rule.table-carries-caption",
+      "type": "required-composition",
+      "severity": "must",
+      "appliesTo": {
+        "intents": [
+          "record-collection"
+        ]
+      },
+      "component": "table",
+      "requiredSubComponents": [
+        {
+          "id": "table-caption",
+          "min": 1
+        }
+      ],
+      "rationale": "The data-table-with-row-actions pattern requires an accessible name via TableCaption or an aria-label. The pattern permits either; the contract can only govern the declarative form, so the caption is the enforceable floor — an aria-label alternative is legitimate but inexpressible in current rule types and remains guidance.",
+      "examples": [
+        "ex.support-ticket-queue"
+      ],
+      "tags": [
+        "accessibility"
+      ]
+    },
+    {
+      "id": "rule.no-toaster-in-surface",
+      "type": "component-choice",
+      "severity": "must",
+      "forbid": [
+        "sonner"
+      ],
+      "rationale": "The sonner registry item exports exactly one component — Toaster — which is mounted once in the app's root layout; individual toasts are produced by toast() calls, never by JSX in a page. A surface that declares a Toaster mounts a second one, which splits the queue and announces every toast twice in the polite live region.",
+      "tags": [
+        "feedback",
+        "structure",
+        "accessibility"
+      ]
+    },
+    {
+      "id": "rule.alert-carries-title",
+      "type": "required-props",
+      "severity": "must",
+      "appliesTo": {
+        "intents": [
+          "destructive-action",
+          "record-collection",
+          "status-feedback",
+          "wayfinding",
+          "panel-navigation",
+          "record-detail"
+        ]
+      },
+      "component": "alert-title",
+      "within": "alert",
+      "requiredText": true,
+      "rationale": "An alert takes its accessible name from its own content and is announced as one atomic run of text — AlertTitle is a plain div, not a heading, and is not wired to the container with aria-labelledby. An alert with no title, or an empty one, reaches the user as a bare description with no headline to scan.",
+      "tags": [
+        "accessibility",
+        "content"
+      ]
+    },
+    {
+      "id": "rule.badge-carries-text",
+      "type": "required-props",
+      "severity": "must",
+      "appliesTo": {
+        "intents": [
+          "record-collection"
+        ]
+      },
+      "component": "badge",
+      "requiredText": true,
+      "rationale": "Badge is presentational: it renders an inline element with no role, no accessible name of its own, and no aria-label in this vocabulary. A badge that carries only variant=\"destructive\" reaches a screen-reader user as an empty element, so the record's status is conveyed by colour alone and the status column reads as blank.",
+      "examples": [
+        "ex.support-ticket-queue"
+      ],
+      "tags": [
+        "accessibility",
+        "content"
+      ]
+    },
+    {
+      "id": "rule.table-head-names-its-column",
+      "type": "required-props",
+      "severity": "must",
+      "appliesTo": {
+        "intents": [
+          "record-collection"
+        ]
+      },
+      "component": "table-head",
+      "within": "table-header",
+      "requiredText": true,
+      "rationale": "TableHeader supplies only the thead; the column association comes from the cells inside it being named TableHead (th) elements. A header row built from TableCell, or one whose heads are empty, leaves every data cell announced with no column name — the user hears \"Waiting on customer\" with no way to tell which attribute it is.",
+      "examples": [
+        "ex.support-ticket-queue"
+      ],
+      "tags": [
+        "accessibility",
+        "structure"
+      ]
+    },
+    {
+      "id": "rule.table-caption-carries-text",
+      "type": "required-props",
+      "severity": "must",
+      "appliesTo": {
+        "intents": [
+          "record-collection"
+        ]
+      },
+      "component": "table-caption",
+      "requiredText": true,
+      "rationale": "A caption supplies the table's accessible name only if it says something. An empty TableCaption satisfies the presence requirement while leaving the table announced as an unnamed table, so a user arriving by rotor or landmark navigation is told there is a table of four columns and nothing about what the rows are.",
+      "examples": [
+        "ex.support-ticket-queue"
+      ],
+      "tags": [
+        "accessibility",
+        "structure"
+      ]
+    },
+    {
+      "id": "rule.progress-carries-value",
+      "type": "required-props",
+      "severity": "must",
+      "appliesTo": {
+        "intents": [
+          "record-collection",
+          "status-feedback",
+          "supplementary-detail"
+        ]
+      },
+      "component": "progress",
+      "requiredProps": [
+        {
+          "prop": "value"
+        }
+      ],
+      "rationale": "Progress is determinate only: with no value the shipped indicator renders an empty track rather than an indeterminate animation, while Radix publishes role=\"progressbar\" with no aria-valuenow — an import job that announces itself as a bar stuck at nothing. A wait you cannot quantify is a Spinner. The bar's accessible name is equally required but has no declarative form in these rule types.",
+      "tags": [
+        "accessibility",
+        "feedback"
+      ]
+    },
+    {
+      "id": "rule.skeleton-is-a-silent-placeholder",
+      "type": "required-props",
+      "severity": "must",
+      "appliesTo": {
+        "intents": [
+          "record-collection",
+          "loading-state"
+        ]
+      },
+      "component": "skeleton",
+      "requiredProps": [
+        {
+          "prop": "className"
+        },
+        {
+          "prop": "aria-hidden",
+          "oneOf": [
+            true
+          ]
+        }
+      ],
+      "rationale": "Skeleton ships with no dimensions and no ARIA of its own. Without size classes it renders a zero-size element, so the loading state is invisible and the layout still jumps when content lands; left in the accessibility tree, a row of placeholders makes a screen reader walk empty divs that say nothing about the wait.",
+      "tags": [
+        "accessibility",
+        "feedback"
+      ]
+    },
+    {
+      "id": "rule.skeleton-hides-no-controls",
+      "type": "forbidden-composition",
+      "severity": "must",
+      "appliesTo": {
+        "intents": [
+          "record-collection",
+          "loading-state"
+        ]
+      },
+      "component": "skeleton",
+      "forbiddenCategories": [
+        "interactive"
+      ],
+      "rationale": "A skeleton stands in for content that has not arrived and is hidden from assistive technology. A control placed inside one stays in the tab order while being absent from the accessibility tree: the user tabs to something no screen reader can name. Keep the real control mounted and disabled instead of covering it.",
+      "tags": [
+        "accessibility",
+        "interaction"
+      ]
+    },
+    {
+      "id": "rule.spinner-names-what-is-loading",
+      "type": "required-props",
+      "severity": "should",
+      "appliesTo": {
+        "intents": [
+          "record-collection",
+          "loading-state"
+        ]
+      },
+      "component": "spinner",
+      "requiredProps": [
+        {
+          "prop": "aria-label"
+        }
+      ],
+      "rationale": "The component hardcodes aria-label=\"Loading\" — English, and identical for every spinner on the page. Where the table body, a filter, and a row action can each be in flight at once, three indicators announce the same word, and a localised interface announces an untranslated one.",
+      "tags": [
+        "accessibility",
+        "i18n",
+        "feedback"
+      ]
+    },
+    {
+      "id": "rule.destructive-overlay-family",
+      "type": "component-choice",
+      "severity": "must",
+      "appliesTo": {
+        "intents": [
+          "destructive-action"
+        ]
+      },
+      "forbid": [
+        "popover",
+        "sheet"
+      ],
+      "rationale": "The four overlay families differ mainly in how easily they can be abandoned. Popover is non-modal by default — focus and the pointer leave freely and Escape closes it — so a user can wander off with the confirmation unanswered; Sheet is a Radix Dialog and closes on Escape or an overlay click. Only AlertDialog blocks both exits and forces confirm or cancel.",
+      "examples": [
+        "ex.delete-account-confirmation"
+      ],
+      "tags": [
+        "safety",
+        "overlay"
+      ]
+    },
+    {
+      "id": "rule.dialog-content-carries-title",
+      "type": "required-props",
+      "severity": "must",
+      "appliesTo": {
+        "intents": [
+          "record-collection",
+          "overlay-task"
+        ]
+      },
+      "component": "dialog-title",
+      "within": "dialog-content",
+      "requiredText": true,
+      "textScope": "self",
+      "rationale": "DialogTitle is the only part that wires aria-labelledby onto the content. Without it Radix warns in development and ships a modal that traps focus while announcing nothing but \"dialog\" — the user is held inside a window whose purpose is never spoken. The title must carry its own text; a title whose label sits in a child projects as an empty name.",
+      "tags": [
+        "accessibility",
+        "overlay"
+      ]
+    },
+    {
+      "id": "rule.sheet-content-carries-title",
+      "type": "required-props",
+      "severity": "must",
+      "appliesTo": {
+        "intents": [
+          "record-collection",
+          "overlay-task"
+        ]
+      },
+      "component": "sheet-title",
+      "within": "sheet-content",
+      "requiredText": true,
+      "textScope": "self",
+      "rationale": "A Sheet is the same Radix Dialog primitive, so SheetTitle is what supplies its accessible name. On a small viewport the panel covers three quarters of the screen; announcing it only as \"dialog\" leaves the user trapped in unnamed content with no idea what they opened. A design with no visible title still renders SheetTitle, visually hidden — it is never dropped.",
+      "tags": [
+        "accessibility",
+        "overlay"
+      ]
+    },
+    {
+      "id": "rule.popover-content-carries-title",
+      "type": "required-props",
+      "severity": "must",
+      "appliesTo": {
+        "intents": [
+          "record-collection",
+          "overlay-task",
+          "supplementary-detail"
+        ]
+      },
+      "component": "popover-title",
+      "within": "popover-content",
+      "requiredText": true,
+      "textScope": "self",
+      "rationale": "Popover is the one overlay with no ARIA wiring of its own: PopoverHeader, PopoverTitle and PopoverDescription are a div, a div and a p, not Radix parts, so rendering a title names nothing. PopoverContent still carries role=\"dialog\", and a panel with no authored aria-labelledby is announced as a bare \"dialog\". A titled panel is the floor the contract can check; pointing aria-labelledby at that title's id remains the author's job.",
+      "tags": [
+        "accessibility",
+        "overlay"
+      ]
+    },
+    {
+      "id": "rule.tooltip-content-is-text",
+      "type": "required-props",
+      "severity": "must",
+      "component": "tooltip-content",
+      "requiredText": true,
+      "textScope": "self",
+      "rationale": "TooltipContent takes short text only: it never receives focus, it closes on pointer-down and on click, and Radix ignores touch pointers outright, so anything composed inside it — a link, a button, a paragraph of instructions — is unreachable for keyboard and touch users. Content with no text of its own claims role=\"tooltip\" and announces nothing at all.",
+      "tags": [
+        "accessibility",
+        "overlay"
+      ]
+    },
+    {
+      "id": "rule.tooltip-trigger-carries-own-label",
+      "type": "required-props",
+      "severity": "must",
+      "component": "tooltip-trigger",
+      "requiredText": true,
+      "textScope": "subtree",
+      "rationale": "Radix links the tooltip with aria-describedby, which is a description and not a name, and on touch the tooltip never opens at all. A control named only by its tooltip is therefore announced as an unnamed button to some users and as nothing whatsoever to others. The label must exist in the trigger's own subtree, where protocol projections lift it onto the control.",
+      "tags": [
+        "accessibility",
+        "projection"
+      ]
+    },
+    {
+      "id": "rule.menu-trigger-carries-label",
+      "type": "required-props",
+      "severity": "must",
+      "appliesTo": {
+        "intents": [
+          "record-collection"
+        ]
+      },
+      "component": "dropdown-menu-trigger",
+      "requiredText": true,
+      "textScope": "subtree",
+      "rationale": "The contextual-actions trigger is a ghost icon button. With no text anywhere beneath it, every row's menu is announced identically as an unnamed button and the projection has nothing to lift into the trigger's aria-label — a screen reader user hears the same thing on every row and cannot tell which record's actions they opened.",
+      "tags": [
+        "accessibility",
+        "projection"
+      ]
+    },
+    {
+      "id": "rule.separator-declares-decorative",
+      "type": "required-props",
+      "severity": "must",
+      "component": "separator",
+      "requiredProps": [
+        {
+          "prop": "decorative"
+        }
+      ],
+      "rationale": "shadcn defaults decorative to true, which renders role=\"none\": a rule drawn to mark a real boundary between groups is then invisible to assistive technology, and the grouping exists for sighted users only. Ornament or structure is a decision, not a default — false where the divider carries the boundary, true where a heading or card edge already does.",
+      "tags": [
+        "accessibility",
+        "layout"
+      ]
+    },
+    {
+      "id": "rule.card-not-nested",
+      "type": "forbidden-composition",
+      "severity": "must",
+      "component": "card",
+      "forbiddenDescendants": [
+        "card"
+      ],
+      "rationale": "A Card inside a Card draws two competing boundaries around one group and doubles the padding, so the inner group reads as a separate object and the outer surface loses its edge. Hierarchy within a card comes from headings and spacing: one bordered surface per group.",
+      "examples": [
+        "ex.delete-account-confirmation"
+      ],
+      "tags": [
+        "structure"
+      ]
+    },
+    {
+      "id": "rule.tabs-selects-initial-panel",
+      "type": "required-props",
+      "severity": "must",
+      "appliesTo": {
+        "intents": [
+          "record-collection"
+        ]
+      },
+      "component": "tabs",
+      "requiredProps": [
+        {
+          "prop": "defaultValue"
+        }
+      ],
+      "rationale": "With neither value nor defaultValue Radix selects nothing: the tablist renders over a stack of hidden panels, so the surface shows a row of triggers above an empty region. A generated surface has no handler to pair with the controlled value, so defaultValue is the enforceable floor and must name the panel that opens first.",
+      "tags": [
+        "interaction",
+        "structure"
+      ]
+    },
+    {
+      "id": "rule.tabs-pairs-triggers-and-panels",
+      "type": "required-composition",
+      "severity": "must",
+      "appliesTo": {
+        "intents": [
+          "record-collection"
+        ]
+      },
+      "component": "tabs",
+      "requiredSubComponents": [
+        {
+          "id": "tabs-list",
+          "min": 1
+        },
+        {
+          "id": "tabs-trigger",
+          "min": 1
+        },
+        {
+          "id": "tabs-content",
+          "min": 1
+        }
+      ],
+      "rationale": "Radix pairs each trigger with its panel through a shared value: an unmatched trigger selects nothing, an unmatched panel never appears, and the trigger's aria-controls resolves to an element that does not exist. Requiring the tablist, at least one trigger and at least one panel is the floor; the one-to-one value match cannot be expressed here and stays guidance.",
+      "tags": [
+        "structure",
+        "accessibility",
+        "navigation"
+      ]
+    },
+    {
+      "id": "rule.breadcrumb-carries-trail-structure",
+      "type": "required-composition",
+      "severity": "must",
+      "appliesTo": {
+        "intents": [
+          "record-collection"
+        ]
+      },
+      "component": "breadcrumb",
+      "requiredSubComponents": [
+        {
+          "id": "breadcrumb-list",
+          "min": 1
+        },
+        {
+          "id": "breadcrumb-item",
+          "min": 1
+        },
+        {
+          "id": "breadcrumb-page",
+          "min": 1
+        }
+      ],
+      "rationale": "BreadcrumbList is an ol and every crumb must be an li within it, or the trail is announced as loose links with no position or count. The final crumb must be a BreadcrumbPage: it is what carries aria-current=\"page\", and it renders a span rather than an anchor so the current page does not offer a link to itself. Exactly-one-and-last is not expressible; a minimum of one is the floor.",
+      "tags": [
+        "structure",
+        "accessibility",
+        "navigation"
+      ]
+    },
+    {
+      "id": "rule.pagination-wraps-controls-in-items",
+      "type": "required-composition",
+      "severity": "must",
+      "appliesTo": {
+        "intents": [
+          "record-collection"
+        ]
+      },
+      "component": "pagination",
+      "requiredSubComponents": [
+        {
+          "id": "pagination-content",
+          "min": 1
+        },
+        {
+          "id": "pagination-item",
+          "min": 1
+        }
+      ],
+      "rationale": "PaginationContent renders a ul, so a link dropped straight into it is not a list item: the pager loses its item count and its controls are announced as stray links inside a list. Every control, the ellipsis included, sits in its own PaginationItem.",
+      "tags": [
+        "structure",
+        "accessibility",
+        "navigation"
+      ]
+    },
+    {
+      "id": "rule.avatar-requires-fallback",
+      "type": "required-composition",
+      "severity": "must",
+      "appliesTo": {
+        "intents": [
+          "record-collection",
+          "record-detail"
+        ]
+      },
+      "component": "avatar",
+      "requiredSubComponents": [
+        {
+          "id": "avatar-fallback",
+          "min": 1
+        }
+      ],
+      "rationale": "AvatarImage mounts only once the image has actually loaded, so on a slow, blocked, or 404 URL the slot renders empty and the row loses the identity it was there to carry. AvatarFallback fills the same box with initials or an icon from first paint — it is what most users on poor connections actually see.",
+      "tags": [
+        "content",
+        "accessibility"
+      ]
+    },
+    {
+      "id": "rule.accordion-trigger-carries-label",
+      "type": "required-props",
+      "severity": "must",
+      "appliesTo": {
+        "intents": [
+          "record-collection"
+        ]
+      },
+      "component": "accordion-trigger",
+      "requiredText": true,
+      "textScope": "self",
+      "rationale": "AccordionTrigger is itself the button inside the heading, and nesting a control within it is invalid, so the label has to be the trigger's own text. Without it the disclosure is announced as an unnamed button and a screen reader user has to open every section in turn to discover what each one holds.",
+      "tags": [
+        "accessibility",
+        "content"
+      ]
+    },
+    {
+      "id": "rule.scroll-area-not-nested",
+      "type": "forbidden-composition",
+      "severity": "should",
+      "appliesTo": {
+        "intents": [
+          "record-collection"
+        ]
+      },
+      "component": "scroll-area",
+      "forbiddenDescendants": [
+        "scroll-area"
+      ],
+      "rationale": "Nested scroll containers fight over the same wheel and touch gestures: the inner region swallows the gesture until it reaches its own end, so the outer one reads as frozen and the content below it is unreachable by pointer. One region scrolls — restructure rather than stacking them.",
+      "tags": [
+        "interaction",
+        "layout"
+      ]
+    },
+    {
+      "id": "rule.label-names-a-control",
+      "type": "required-props",
+      "severity": "must",
+      "component": "label",
+      "requiredText": true,
+      "requiredProps": [
+        {
+          "prop": "htmlFor"
+        }
+      ],
+      "rationale": "Label wires nothing by itself: htmlFor is the only thing that turns its text into the control's accessible name, and an empty Label leaves the control nameless while looking finished on screen. Missing either, a screen reader announces the field as an unnamed edit box and clicking the caption does not focus it.",
+      "tags": [
+        "accessibility",
+        "naming",
+        "form"
+      ]
+    },
+    {
+      "id": "rule.label-no-interactive-descendants",
+      "type": "forbidden-composition",
+      "severity": "must",
+      "component": "label",
+      "forbiddenDescendants": [
+        "button"
+      ],
+      "rationale": "Activating a label activates the control it names, so a Button inside label text fires twice over: the click toggles the checkbox and runs the button's action. Buttons and links belong beside the label, never inside it; the control the label wraps is the one thing that may live there.",
+      "tags": [
+        "accessibility",
+        "interaction",
+        "form"
+      ]
+    },
+    {
+      "id": "rule.button-carries-text",
+      "type": "required-props",
+      "severity": "must",
+      "component": "button",
+      "requiredText": true,
+      "rationale": "A Button's own text is its only accessible-name channel in this contract — aria-label is not among its declared props — so a Button emitted without text reaches the user as a control announced as nothing but \"button\". On a confirmation that is the difference between Cancel and the destructive action.",
+      "examples": [
+        "ex.delete-account-confirmation"
+      ],
+      "tags": [
+        "accessibility",
+        "naming"
+      ]
+    },
+    {
+      "id": "rule.select-carries-trigger-and-content",
+      "type": "required-composition",
+      "severity": "must",
+      "appliesTo": {
+        "intents": [
+          "destructive-action",
+          "record-collection"
+        ]
+      },
+      "component": "select",
+      "requiredSubComponents": [
+        {
+          "id": "select-trigger",
+          "min": 1
+        },
+        {
+          "id": "select-content",
+          "min": 1
+        }
+      ],
+      "rationale": "Select renders no control of its own. SelectTrigger is the focusable combobox and the element a Label's htmlFor must point at; SelectContent is the listbox holding the options. A Select missing either leaves nothing to focus, name, or open — only the aria-hidden native select Radix keeps in sync, which must never be labelled.",
+      "tags": [
+        "structure",
+        "accessibility",
+        "form"
+      ]
+    },
+    {
+      "id": "rule.select-trigger-shows-a-value",
+      "type": "required-props",
+      "severity": "must",
+      "appliesTo": {
+        "intents": [
+          "destructive-action",
+          "record-collection"
+        ]
+      },
+      "component": "select-value",
+      "within": "select-trigger",
+      "requiredText": true,
+      "rationale": "SelectValue is the only thing the trigger displays: the chosen item's label, or its placeholder while nothing is chosen. A trigger without one is a blank button, and a generated surface starts with nothing selected — so that placeholder text is the only thing naming what the field is asking for. A bare \"Select...\" names nothing.",
+      "tags": [
+        "accessibility",
+        "content",
+        "form"
+      ]
+    },
+    {
+      "id": "rule.select-content-carries-named-options",
+      "type": "required-props",
+      "severity": "must",
+      "appliesTo": {
+        "intents": [
+          "destructive-action",
+          "record-collection"
+        ]
+      },
+      "component": "select-item",
+      "within": "select-content",
+      "requiredText": true,
+      "textScope": "subtree",
+      "rationale": "A SelectContent holding no items is a listbox offering nothing to choose, and an option with no text is announced as an unnamed option, cannot be reached by typeahead, and leaves the trigger blank once chosen, because SelectValue echoes the item's own label. Subtree text admits items carrying an icon or a trailing Badge beside their label.",
+      "tags": [
+        "accessibility",
+        "content",
+        "form"
+      ]
+    },
+    {
+      "id": "rule.select-group-is-named",
+      "type": "required-props",
+      "severity": "must",
+      "appliesTo": {
+        "intents": [
+          "destructive-action",
+          "record-collection"
+        ]
+      },
+      "component": "select-label",
+      "within": "select-group",
+      "requiredText": true,
+      "rationale": "SelectGroup renders role=group and takes its accessible name from the SelectLabel inside it, from nowhere else. A group without one announces a boundary with no subject — the same confusion authors create by faking category headings with disabled items. SelectLabel is not the field's label; that is a separate Label bound to the trigger.",
+      "tags": [
+        "accessibility",
+        "grouping",
+        "form"
+      ]
+    },
+    {
+      "id": "rule.radio-group-offers-a-choice",
+      "type": "required-composition",
+      "severity": "must",
+      "appliesTo": {
+        "intents": [
+          "destructive-action",
+          "record-collection"
+        ]
+      },
+      "component": "radio-group",
+      "requiredSubComponents": [
+        {
+          "id": "radio-group-item",
+          "min": 2
+        }
+      ],
+      "rationale": "A RadioGroupItem outside a RadioGroup is inert — the group supplies the selection context and the roving tabindex. A group holding one item is worse: a checked radio cannot be unchecked, so the first arrow key or click commits a choice the user can never withdraw. A one-option question is a Checkbox or a Switch.",
+      "tags": [
+        "structure",
+        "interaction",
+        "form"
+      ]
+    },
+    {
+      "id": "rule.radio-options-carry-labels",
+      "type": "required-props",
+      "severity": "should",
+      "appliesTo": {
+        "intents": [
+          "destructive-action",
+          "record-collection"
+        ]
+      },
+      "component": "label",
+      "within": "radio-group",
+      "requiredProps": [
+        {
+          "prop": "htmlFor"
+        }
+      ],
+      "rationale": "RadioGroupItem renders only its indicator and takes no children, so each option's text lives in a sibling Label bound to that item's id; a group of bare items is a column of radios announced with no option names. Held at should because the Field family's choice-card composition names options with FieldLabel, which this rule cannot see.",
+      "tags": [
+        "accessibility",
+        "naming",
+        "form"
+      ]
+    },
+    {
+      "id": "rule.field-set-carries-a-legend",
+      "type": "required-props",
+      "severity": "must",
+      "appliesTo": {
+        "intents": [
+          "destructive-action",
+          "record-collection"
+        ]
+      },
+      "component": "field-legend",
+      "within": "field-set",
+      "requiredText": true,
+      "rationale": "Controls that together answer one question — a checkbox group, a radio group, an address block — are named by the legend, which is announced with every control inside the set. A FieldSet whose legend is missing or empty announces a grouping with no subject, and a Label on one control names that control only, never the set.",
+      "tags": [
+        "accessibility",
+        "grouping",
+        "form"
+      ]
+    },
+    {
+      "id": "rule.field-label-carries-text",
+      "type": "required-props",
+      "severity": "must",
+      "appliesTo": {
+        "intents": [
+          "destructive-action",
+          "record-collection"
+        ]
+      },
+      "component": "field-label",
+      "requiredText": true,
+      "textScope": "subtree",
+      "rationale": "FieldLabel is the only part of the family that names anything: Field generates no ids and wires nothing, FieldTitle is styled like a label but renders a div, and placeholder text is never a name. An empty FieldLabel leaves its control unnamed. Subtree text admits the choice-card composition, where the visible name is a FieldTitle inside the label.",
+      "tags": [
+        "accessibility",
+        "naming",
+        "form"
+      ]
+    },
+    {
+      "id": "rule.field-excludes-form-family",
+      "type": "forbidden-composition",
+      "severity": "must",
+      "appliesTo": {
+        "intents": [
+          "destructive-action",
+          "record-collection"
+        ]
+      },
+      "component": "field",
+      "forbiddenDescendants": [
+        "form-item",
+        "form-label",
+        "form-control",
+        "form-description",
+        "form-message"
+      ],
+      "rationale": "Both families own the field's wiring and only one wins: FormControl stamps a generated id, aria-describedby, and aria-invalid onto the control it wraps, while Field expects those hand-written. Together they yield a duplicated id and an aria-describedby pointing at text that never renders. Field driven by Controller stays legal; the Form parts do not.",
+      "tags": [
+        "correctness",
+        "accessibility",
+        "form"
+      ]
+    },
+    {
+      "id": "rule.form-generates-the-field-wiring",
+      "type": "required-composition",
+      "severity": "must",
+      "appliesTo": {
+        "intents": [
+          "destructive-action",
+          "record-collection"
+        ]
+      },
+      "component": "form",
+      "requiredSubComponents": [
+        {
+          "id": "form-field",
+          "min": 1
+        },
+        {
+          "id": "form-item",
+          "min": 1
+        },
+        {
+          "id": "form-control",
+          "min": 1
+        },
+        {
+          "id": "form-message",
+          "min": 1
+        }
+      ],
+      "rationale": "FormItem mints the id every other part derives from, FormControl stamps id, aria-describedby, and aria-invalid onto the control it wraps, and FormMessage is the element aria-describedby names once the field errors. A control outside FormControl receives none of that and still looks right on screen; a FormItem without one dangles.",
+      "tags": [
+        "accessibility",
+        "validation",
+        "form"
+      ]
+    },
+    {
+      "id": "rule.form-item-is-labelled",
+      "type": "required-props",
+      "severity": "must",
+      "appliesTo": {
+        "intents": [
+          "destructive-action",
+          "record-collection"
+        ]
+      },
+      "component": "form-label",
+      "within": "form-item",
+      "requiredText": true,
+      "rationale": "FormLabel carries htmlFor bound to the id FormItem generated, so it is the field's name and a placeholder is not. A FormItem without one is a control whose label never renders; and any part placed outside a FormItem falls back to the id \"undefined-form-item\", collapsing every such field on the page onto one shared label.",
+      "tags": [
+        "accessibility",
+        "naming",
+        "form"
+      ]
+    },
+    {
+      "id": "rule.form-carries-submit",
+      "type": "required-composition",
+      "severity": "must",
+      "appliesTo": {
+        "intents": [
+          "destructive-action",
+          "record-collection"
+        ]
+      },
+      "component": "form",
+      "requiredSubComponents": [
+        {
+          "id": "button",
+          "min": 1
+        }
+      ],
+      "rationale": "Enter inserts a newline in a Textarea and does nothing on a Checkbox, Switch, or radio item, so a form whose controls are not single-line inputs has no keyboard path to submission — and with no Button, no pointer path either. Form is FormProvider and renders no DOM; the submit Button is the surface's only commit affordance.",
+      "tags": [
+        "interaction",
+        "form"
+      ]
+    },
+    {
+      "id": "rule.form-control-carries-control",
+      "type": "required-composition",
+      "severity": "must",
+      "component": "form-control",
+      "requiredCategories": [
+        {
+          "id": "interactive",
+          "min": 1
+        }
+      ],
+      "rationale": "A form-control represents the location of the user-editable control in a field. It must contain an approved interactive control; text-only or empty form controls are not meaningful form composition.",
+      "examples": [
+        "ex.expense-report-form"
+      ],
+      "x-source": {
+        "evidence": "dspack-emit eval/t1-build-matrix*.json — T1 Build runs generated lint-clean form-controls carrying literal text and no control; every gate passed and the emitter correctly refused",
+        "amendment": "spec v0.4 §4.3 (2026-08-07), the first §6 ceiling item lifted by measurement"
+      }
+    }
+  ],
+  "examples": [
+    {
+      "id": "ex.delete-account-confirmation",
+      "intent": "destructive-action",
+      "name": "Delete account confirmation",
+      "prompt": "a screen to delete my account",
+      "description": "Card with a destructive entry point; AlertDialog confirmation with explicit consequence text, cancel-before-confirm, destructive confirm variant.",
+      "surface": {
+        "dspackSurface": "0.1",
+        "system": "shadcn/ui",
+        "intent": "destructive-action",
+        "root": {
+          "component": "card",
+          "children": [
+            {
+              "component": "alert-dialog",
+              "children": [
+                {
+                  "component": "alert-dialog-trigger",
+                  "children": [
+                    {
+                      "component": "button",
+                      "props": {
+                        "variant": "destructive"
+                      },
+                      "text": "Delete account"
+                    }
+                  ]
+                },
+                {
+                  "component": "alert-dialog-content",
+                  "children": [
+                    {
+                      "component": "alert-dialog-title",
+                      "text": "Delete your account?"
+                    },
+                    {
+                      "component": "alert-dialog-description",
+                      "text": "This will permanently delete your account and all associated data. This action cannot be undone."
+                    },
+                    {
+                      "component": "alert-dialog-footer",
+                      "children": [
+                        {
+                          "component": "alert-dialog-cancel",
+                          "text": "Cancel"
+                        },
+                        {
+                          "component": "alert-dialog-action",
+                          "text": "Delete account"
+                        }
+                      ]
+                    }
+                  ]
+                }
+              ]
+            }
+          ]
+        }
+      }
+    },
+    {
+      "id": "ex.delete-project-confirmation",
+      "intent": "destructive-action",
+      "name": "Delete project confirmation",
+      "prompt": "a danger zone panel for deleting a project, with a confirmation step",
+      "description": "The destructive entry point sits in a Card whose Alert names what is lost, and a Field asks the operator to type the project name before the AlertDialog opens. The dialog states the consequence in its title, offers the cancel first, and reserves the destructive verb for the action.",
+      "surface": {
+        "dspackSurface": "0.1",
+        "system": "shadcn/ui",
+        "intent": "destructive-action",
+        "root": {
+          "component": "card",
+          "children": [
+            {
+              "component": "card-header",
+              "children": [
+                {
+                  "component": "card-title",
+                  "text": "Danger zone"
+                },
+                {
+                  "component": "card-description",
+                  "text": "Deleting a project removes its environments, deploys, and logs for everyone in the workspace."
+                }
+              ]
+            },
+            {
+              "component": "card-content",
+              "children": [
+                {
+                  "component": "alert",
+                  "props": {
+                    "variant": "destructive"
+                  },
+                  "children": [
+                    {
+                      "component": "alert-title",
+                      "text": "Deleting Northwind Checkout is permanent"
+                    },
+                    {
+                      "component": "alert-description",
+                      "text": "3 environments, 412 deploys, and 18 GB of build logs are destroyed immediately. There is no backup to restore from."
+                    }
+                  ]
+                },
+                {
+                  "component": "field",
+                  "props": {
+                    "orientation": "vertical"
+                  },
+                  "children": [
+                    {
+                      "component": "field-label",
+                      "text": "Type the project name to confirm"
+                    },
+                    {
+                      "component": "input",
+                      "id": "delete-project-confirm",
+                      "props": {
+                        "type": "text",
+                        "placeholder": "Northwind Checkout"
+                      }
+                    },
+                    {
+                      "component": "field-description",
+                      "text": "The name must match exactly, including capitalisation."
+                    }
+                  ]
+                }
+              ]
+            },
+            {
+              "component": "card-footer",
+              "children": [
+                {
+                  "component": "button",
+                  "props": {
+                    "variant": "outline"
+                  },
+                  "text": "Cancel"
+                },
+                {
+                  "component": "alert-dialog",
+                  "children": [
+                    {
+                      "component": "alert-dialog-trigger",
+                      "children": [
+                        {
+                          "component": "button",
+                          "props": {
+                            "variant": "destructive"
+                          },
+                          "text": "Delete project"
+                        }
+                      ]
+                    },
+                    {
+                      "component": "alert-dialog-content",
+                      "children": [
+                        {
+                          "component": "alert-dialog-header",
+                          "children": [
+                            {
+                              "component": "alert-dialog-title",
+                              "text": "Delete Northwind Checkout?"
+                            },
+                            {
+                              "component": "alert-dialog-description",
+                              "text": "The project, its three environments, and every deploy log are deleted immediately. Anyone with a link to a preview deploy will get a 404."
+                            }
+                          ]
+                        },
+                        {
+                          "component": "alert-dialog-footer",
+                          "children": [
+                            {
+                              "component": "alert-dialog-cancel",
+                              "text": "Keep project"
+                            },
+                            {
+                              "component": "alert-dialog-action",
+                              "text": "Delete project and all data"
+                            }
+                          ]
+                        }
+                      ]
+                    }
+                  ]
+                }
+              ]
+            }
+          ]
+        }
+      }
+    },
+    {
+      "id": "ex.support-ticket-queue",
+      "intent": "record-collection",
+      "name": "Support ticket queue",
+      "prompt": "a queue of open support tickets with status and priority",
+      "description": "A semantic data table from the Table primitives: a caption naming the collection, header cells for column association, and ticket rows in the body. Status renders as a Badge whose text stays readable — the variant reflects state, color is never the only signal.",
+      "surface": {
+        "dspackSurface": "0.1",
+        "system": "shadcn/ui",
+        "intent": "record-collection",
+        "root": {
+          "component": "table",
+          "children": [
+            {
+              "component": "table-caption",
+              "text": "Open support tickets, newest first."
+            },
+            {
+              "component": "table-header",
+              "children": [
+                {
+                  "component": "table-row",
+                  "children": [
+                    {
+                      "component": "table-head",
+                      "text": "Ticket"
+                    },
+                    {
+                      "component": "table-head",
+                      "text": "Subject"
+                    },
+                    {
+                      "component": "table-head",
+                      "text": "Status"
+                    },
+                    {
+                      "component": "table-head",
+                      "text": "Priority"
+                    }
+                  ]
+                }
+              ]
+            },
+            {
+              "component": "table-body",
+              "children": [
+                {
+                  "component": "table-row",
+                  "children": [
+                    {
+                      "component": "table-cell",
+                      "text": "#4812"
+                    },
+                    {
+                      "component": "table-cell",
+                      "text": "Cannot export billing statement"
+                    },
+                    {
+                      "component": "table-cell",
+                      "children": [
+                        {
+                          "component": "badge",
+                          "props": {
+                            "variant": "destructive"
+                          },
+                          "text": "Urgent"
+                        }
+                      ]
+                    },
+                    {
+                      "component": "table-cell",
+                      "text": "P1"
+                    }
+                  ]
+                },
+                {
+                  "component": "table-row",
+                  "children": [
+                    {
+                      "component": "table-cell",
+                      "text": "#4809"
+                    },
+                    {
+                      "component": "table-cell",
+                      "text": "Two-factor codes arrive late"
+                    },
+                    {
+                      "component": "table-cell",
+                      "children": [
+                        {
+                          "component": "badge",
+                          "props": {
+                            "variant": "secondary"
+                          },
+                          "text": "Waiting on customer"
+                        }
+                      ]
+                    },
+                    {
+                      "component": "table-cell",
+                      "text": "P2"
+                    }
+                  ]
+                },
+                {
+                  "component": "table-row",
+                  "children": [
+                    {
+                      "component": "table-cell",
+                      "text": "#4801"
+                    },
+                    {
+                      "component": "table-cell",
+                      "text": "Dark mode contrast on invoices"
+                    },
+                    {
+                      "component": "table-cell",
+                      "children": [
+                        {
+                          "component": "badge",
+                          "props": {
+                            "variant": "outline"
+                          },
+                          "text": "Open"
+                        }
+                      ]
+                    },
+                    {
+                      "component": "table-cell",
+                      "text": "P3"
+                    }
+                  ]
+                }
+              ]
+            }
+          ]
+        }
+      }
+    },
+    {
+      "id": "ex.workspace-members-directory",
+      "intent": "record-collection",
+      "name": "Workspace members directory",
+      "prompt": "a list of workspace members with their role and status, filterable, with paging",
+      "description": "The collection is a semantic Table inside a Card. The filter is a Select whose trigger always shows the current value and whose options are grouped under a named SelectLabel; the visible Label points at the trigger's id. Collection-level actions live in a DropdownMenu with a named trigger, and the page range is a Pagination whose every control sits in its own PaginationItem.",
+      "surface": {
+        "dspackSurface": "0.1",
+        "system": "shadcn/ui",
+        "intent": "record-collection",
+        "root": {
+          "component": "card",
+          "children": [
+            {
+              "component": "card-header",
+              "children": [
+                {
+                  "component": "card-title",
+                  "text": "Members"
+                },
+                {
+                  "component": "card-description",
+                  "text": "18 people have access to Northwind. Invitations expire after seven days."
+                },
+                {
+                  "component": "label",
+                  "props": {
+                    "htmlFor": "members-role-filter"
+                  },
+                  "text": "Role"
+                },
+                {
+                  "component": "select",
+                  "props": {
+                    "name": "role",
+                    "defaultValue": "all"
+                  },
+                  "children": [
+                    {
+                      "component": "select-trigger",
+                      "id": "members-role-filter",
+                      "children": [
+                        {
+                          "component": "select-value",
+                          "text": "All roles"
+                        }
+                      ]
+                    },
+                    {
+                      "component": "select-content",
+                      "children": [
+                        {
+                          "component": "select-group",
+                          "children": [
+                            {
+                              "component": "select-label",
+                              "text": "Access level"
+                            },
+                            {
+                              "component": "select-item",
+                              "text": "All roles"
+                            },
+                            {
+                              "component": "select-item",
+                              "text": "Admins"
+                            },
+                            {
+                              "component": "select-item",
+                              "text": "Editors"
+                            },
+                            {
+                              "component": "select-item",
+                              "text": "Members"
+                            }
+                          ]
+                        }
+                      ]
+                    }
+                  ]
+                },
+                {
+                  "component": "dropdown-menu",
+                  "children": [
+                    {
+                      "component": "dropdown-menu-trigger",
+                      "children": [
+                        {
+                          "component": "button",
+                          "props": {
+                            "variant": "outline",
+                            "size": "sm"
+                          },
+                          "text": "Member actions"
+                        }
+                      ]
+                    },
+                    {
+                      "component": "dropdown-menu-content",
+                      "children": [
+                        {
+                          "component": "dropdown-menu-label",
+                          "text": "Selected members"
+                        },
+                        {
+                          "component": "dropdown-menu-item",
+                          "text": "Resend invitation"
+                        },
+                        {
+                          "component": "dropdown-menu-item",
+                          "text": "Change role"
+                        },
+                        {
+                          "component": "dropdown-menu-separator"
+                        },
+                        {
+                          "component": "dropdown-menu-item",
+                          "text": "Export as CSV"
+                        }
+                      ]
+                    }
+                  ]
+                }
+              ]
+            },
+            {
+              "component": "table",
+              "children": [
+                {
+                  "component": "table-caption",
+                  "text": "Workspace members, most recently active first."
+                },
+                {
+                  "component": "table-header",
+                  "children": [
+                    {
+                      "component": "table-row",
+                      "children": [
+                        {
+                          "component": "table-head",
+                          "text": "Name"
+                        },
+                        {
+                          "component": "table-head",
+                          "text": "Email"
+                        },
+                        {
+                          "component": "table-head",
+                          "text": "Role"
+                        },
+                        {
+                          "component": "table-head",
+                          "text": "Status"
+                        },
+                        {
+                          "component": "table-head",
+                          "text": "Last active"
+                        }
+                      ]
+                    }
+                  ]
+                },
+                {
+                  "component": "table-body",
+                  "children": [
+                    {
+                      "component": "table-row",
+                      "children": [
+                        {
+                          "component": "table-cell",
+                          "text": "Amara Okafor"
+                        },
+                        {
+                          "component": "table-cell",
+                          "text": "amara@northwind.example"
+                        },
+                        {
+                          "component": "table-cell",
+                          "text": "Admin"
+                        },
+                        {
+                          "component": "table-cell",
+                          "children": [
+                            {
+                              "component": "badge",
+                              "props": {
+                                "variant": "default"
+                              },
+                              "text": "Active"
+                            }
+                          ]
+                        },
+                        {
+                          "component": "table-cell",
+                          "text": "12 minutes ago"
+                        }
+                      ]
+                    },
+                    {
+                      "component": "table-row",
+                      "children": [
+                        {
+                          "component": "table-cell",
+                          "text": "Jonas Weber"
+                        },
+                        {
+                          "component": "table-cell",
+                          "text": "jonas@northwind.example"
+                        },
+                        {
+                          "component": "table-cell",
+                          "text": "Editor"
+                        },
+                        {
+                          "component": "table-cell",
+                          "children": [
+                            {
+                              "component": "badge",
+                              "props": {
+                                "variant": "secondary"
+                              },
+                              "text": "Invited"
+                            }
+                          ]
+                        },
+                        {
+                          "component": "table-cell",
+                          "text": "Never"
+                        }
+                      ]
+                    },
+                    {
+                      "component": "table-row",
+                      "children": [
+                        {
+                          "component": "table-cell",
+                          "text": "Priya Raman"
+                        },
+                        {
+                          "component": "table-cell",
+                          "text": "priya@northwind.example"
+                        },
+                        {
+                          "component": "table-cell",
+                          "text": "Member"
+                        },
+                        {
+                          "component": "table-cell",
+                          "children": [
+                            {
+                              "component": "badge",
+                              "props": {
+                                "variant": "outline"
+                              },
+                              "text": "Suspended"
+                            }
+                          ]
+                        },
+                        {
+                          "component": "table-cell",
+                          "text": "6 days ago"
+                        }
+                      ]
+                    }
+                  ]
+                }
+              ]
+            },
+            {
+              "component": "card-footer",
+              "children": [
+                {
+                  "component": "pagination",
+                  "props": {
+                    "aria-label": "Member pages"
+                  },
+                  "children": [
+                    {
+                      "component": "pagination-content",
+                      "children": [
+                        {
+                          "component": "pagination-item",
+                          "children": [
+                            {
+                              "component": "pagination-previous"
+                            }
+                          ]
+                        },
+                        {
+                          "component": "pagination-item",
+                          "children": [
+                            {
+                              "component": "pagination-link",
+                              "text": "1"
+                            }
+                          ]
+                        },
+                        {
+                          "component": "pagination-item",
+                          "children": [
+                            {
+                              "component": "pagination-link",
+                              "text": "2"
+                            }
+                          ]
+                        },
+                        {
+                          "component": "pagination-item",
+                          "children": [
+                            {
+                              "component": "pagination-ellipsis"
+                            }
+                          ]
+                        },
+                        {
+                          "component": "pagination-item",
+                          "children": [
+                            {
+                              "component": "pagination-link",
+                              "text": "6"
+                            }
+                          ]
+                        },
+                        {
+                          "component": "pagination-item",
+                          "children": [
+                            {
+                              "component": "pagination-next"
+                            }
+                          ]
+                        }
+                      ]
+                    }
+                  ]
+                }
+              ]
+            }
+          ]
+        }
+      }
+    },
+    {
+      "id": "ex.expense-report-form",
+      "intent": "structured-input",
+      "name": "Expense report submission",
+      "prompt": "a form to submit an expense report for approval",
+      "description": "The react-hook-form family, composed exactly as shadcn prescribes: one FormField per value, each rendering a single FormItem that holds the FormLabel, one FormControl around one control, the guidance, and the FormMessage — so ids, htmlFor, aria-describedby, and aria-invalid are generated rather than hand-written. The Field family is deliberately absent: mixing the two duplicates the association. Radio options carry their own Labels bound by htmlFor, and the form ends in its submit.",
+      "surface": {
+        "dspackSurface": "0.1",
+        "system": "shadcn/ui",
+        "intent": "structured-input",
+        "root": {
+          "component": "form",
+          "props": {
+            "control": "form.control",
+            "handleSubmit": "form.handleSubmit(onSubmit)"
+          },
+          "children": [
+            {
+              "component": "form-field",
+              "children": [
+                {
+                  "component": "form-item",
+                  "children": [
+                    {
+                      "component": "form-label",
+                      "text": "Merchant"
+                    },
+                    {
+                      "component": "form-control",
+                      "children": [
+                        {
+                          "component": "input",
+                          "props": {
+                            "type": "text",
+                            "placeholder": "Where the expense was incurred"
+                          }
+                        }
+                      ]
+                    },
+                    {
+                      "component": "form-description",
+                      "text": "Use the name printed on the receipt, not the parent company."
+                    },
+                    {
+                      "component": "form-message"
+                    }
+                  ]
+                }
+              ]
+            },
+            {
+              "component": "form-field",
+              "children": [
+                {
+                  "component": "form-item",
+                  "children": [
+                    {
+                      "component": "form-label",
+                      "text": "Amount in USD"
+                    },
+                    {
+                      "component": "form-control",
+                      "children": [
+                        {
+                          "component": "input",
+                          "props": {
+                            "type": "number",
+                            "placeholder": "0.00"
+                          }
+                        }
+                      ]
+                    },
+                    {
+                      "component": "form-message"
+                    }
+                  ]
+                }
+              ]
+            },
+            {
+              "component": "form-field",
+              "children": [
+                {
+                  "component": "form-item",
+                  "children": [
+                    {
+                      "component": "form-label",
+                      "text": "Date of purchase"
+                    },
+                    {
+                      "component": "form-control",
+                      "children": [
+                        {
+                          "component": "input",
+                          "props": {
+                            "type": "date"
+                          }
+                        }
+                      ]
+                    },
+                    {
+                      "component": "form-description",
+                      "text": "Expenses older than 90 days need a manager's note."
+                    },
+                    {
+                      "component": "form-message"
+                    }
+                  ]
+                }
+              ]
+            },
+            {
+              "component": "form-field",
+              "children": [
+                {
+                  "component": "form-item",
+                  "children": [
+                    {
+                      "component": "form-label",
+                      "text": "Reimbursement method"
+                    },
+                    {
+                      "component": "form-control",
+                      "children": [
+                        {
+                          "component": "radio-group",
+                          "props": {
+                            "name": "reimbursement",
+                            "defaultValue": "payroll"
+                          },
+                          "children": [
+                            {
+                              "component": "radio-group-item",
+                              "id": "reimbursement-payroll"
+                            },
+                            {
+                              "component": "label",
+                              "props": {
+                                "htmlFor": "reimbursement-payroll"
+                              },
+                              "text": "Add to the next payroll run"
+                            },
+                            {
+                              "component": "radio-group-item",
+                              "id": "reimbursement-transfer"
+                            },
+                            {
+                              "component": "label",
+                              "props": {
+                                "htmlFor": "reimbursement-transfer"
+                              },
+                              "text": "Bank transfer within five working days"
+                            }
+                          ]
+                        }
+                      ]
+                    },
+                    {
+                      "component": "form-description",
+                      "text": "Contractors must choose bank transfer; payroll is unavailable to them."
+                    },
+                    {
+                      "component": "form-message"
+                    }
+                  ]
+                }
+              ]
+            },
+            {
+              "component": "form-field",
+              "children": [
+                {
+                  "component": "form-item",
+                  "children": [
+                    {
+                      "component": "form-label",
+                      "text": "Business purpose"
+                    },
+                    {
+                      "component": "form-control",
+                      "children": [
+                        {
+                          "component": "textarea",
+                          "props": {
+                            "name": "purpose",
+                            "rows": 4,
+                            "placeholder": "Who the expense was for and why it was necessary"
+                          }
+                        }
+                      ]
+                    },
+                    {
+                      "component": "form-description",
+                      "text": "Required for anything over $75."
+                    },
+                    {
+                      "component": "form-message"
+                    }
+                  ]
+                }
+              ]
+            },
+            {
+              "component": "form-field",
+              "children": [
+                {
+                  "component": "form-item",
+                  "children": [
+                    {
+                      "component": "form-label",
+                      "text": "Billable to a client"
+                    },
+                    {
+                      "component": "form-control",
+                      "children": [
+                        {
+                          "component": "checkbox",
+                          "props": {
+                            "name": "billable"
+                          }
+                        }
+                      ]
+                    },
+                    {
+                      "component": "form-description",
+                      "text": "Billable expenses appear on the client's next invoice."
+                    },
+                    {
+                      "component": "form-message"
+                    }
+                  ]
+                }
+              ]
+            },
+            {
+              "component": "button",
+              "props": {
+                "variant": "outline"
+              },
+              "text": "Save draft"
+            },
+            {
+              "component": "button",
+              "text": "Submit for approval"
+            }
+          ]
+        }
+      }
+    },
+    {
+      "id": "ex.notification-preferences",
+      "intent": "preference-settings",
+      "name": "Notification preferences",
+      "prompt": "a settings panel for notification preferences",
+      "description": "Settings that apply on change, grouped the way the Field family prescribes: a FieldSet with a FieldLegend names each group, a FieldGroup stacks the Fields, and each horizontal Field pairs one FieldLabel with one control. The digest frequency is a RadioGroup because the options are mutually exclusive, and every option carries its own Label bound by htmlFor. A decorative Separator divides the groups without announcing itself.",
+      "surface": {
+        "dspackSurface": "0.1",
+        "system": "shadcn/ui",
+        "intent": "preference-settings",
+        "root": {
+          "component": "card",
+          "children": [
+            {
+              "component": "card-header",
+              "children": [
+                {
+                  "component": "card-title",
+                  "text": "Notifications"
+                },
+                {
+                  "component": "card-description",
+                  "text": "Changes are saved as you make them."
+                }
+              ]
+            },
+            {
+              "component": "card-content",
+              "children": [
+                {
+                  "component": "field-set",
+                  "children": [
+                    {
+                      "component": "field-legend",
+                      "text": "Email me when"
+                    },
+                    {
+                      "component": "field-group",
+                      "children": [
+                        {
+                          "component": "field",
+                          "props": {
+                            "orientation": "horizontal"
+                          },
+                          "children": [
+                            {
+                              "component": "field-label",
+                              "text": "A ticket is assigned to me"
+                            },
+                            {
+                              "component": "switch",
+                              "id": "notify-assigned",
+                              "props": {
+                                "name": "assigned",
+                                "defaultChecked": true
+                              }
+                            }
+                          ]
+                        },
+                        {
+                          "component": "field",
+                          "props": {
+                            "orientation": "horizontal"
+                          },
+                          "children": [
+                            {
+                              "component": "field-label",
+                              "text": "A customer replies to a ticket I own"
+                            },
+                            {
+                              "component": "switch",
+                              "id": "notify-reply",
+                              "props": {
+                                "name": "reply",
+                                "defaultChecked": true
+                              }
+                            }
+                          ]
+                        },
+                        {
+                          "component": "field",
+                          "props": {
+                            "orientation": "horizontal"
+                          },
+                          "children": [
+                            {
+                              "component": "field-label",
+                              "text": "A production deploy fails"
+                            },
+                            {
+                              "component": "switch",
+                              "id": "notify-deploy",
+                              "props": {
+                                "name": "deployFailed"
+                              }
+                            }
+                          ]
+                        }
+                      ]
+                    }
+                  ]
+                },
+                {
+                  "component": "separator",
+                  "props": {
+                    "decorative": true,
+                    "orientation": "horizontal"
+                  }
+                },
+                {
+                  "component": "field-set",
+                  "children": [
+                    {
+                      "component": "field-legend",
+                      "text": "Weekly digest"
+                    },
+                    {
+                      "component": "field-group",
+                      "children": [
+                        {
+                          "component": "radio-group",
+                          "props": {
+                            "name": "digest",
+                            "defaultValue": "monday"
+                          },
+                          "children": [
+                            {
+                              "component": "radio-group-item",
+                              "id": "digest-monday"
+                            },
+                            {
+                              "component": "label",
+                              "props": {
+                                "htmlFor": "digest-monday"
+                              },
+                              "text": "Monday morning"
+                            },
+                            {
+                              "component": "radio-group-item",
+                              "id": "digest-friday"
+                            },
+                            {
+                              "component": "label",
+                              "props": {
+                                "htmlFor": "digest-friday"
+                              },
+                              "text": "Friday afternoon"
+                            },
+                            {
+                              "component": "radio-group-item",
+                              "id": "digest-off"
+                            },
+                            {
+                              "component": "label",
+                              "props": {
+                                "htmlFor": "digest-off"
+                              },
+                              "text": "Do not send a digest"
+                            }
+                          ]
+                        }
+                      ]
+                    }
+                  ]
+                }
+              ]
+            },
+            {
+              "component": "card-footer",
+              "children": [
+                {
+                  "component": "button",
+                  "props": {
+                    "variant": "outline"
+                  },
+                  "text": "Restore defaults"
+                }
+              ]
+            }
+          ]
+        }
+      }
+    },
+    {
+      "id": "ex.order-detail-summary",
+      "intent": "record-detail",
+      "name": "Customer order detail",
+      "prompt": "the detail view for a single customer order",
+      "description": "One record shown whole: the Card header carries the identity — an Avatar that always has a fallback, the order number, and a status Badge whose meaning is in its text — while the line items stay a semantic Table with a caption and a footer row for the total. The refund note is a static Alert with a title, and the actions sit in the Card footer.",
+      "surface": {
+        "dspackSurface": "0.1",
+        "system": "shadcn/ui",
+        "intent": "record-detail",
+        "root": {
+          "component": "card",
+          "children": [
+            {
+              "component": "card-header",
+              "children": [
+                {
+                  "component": "avatar",
+                  "props": {
+                    "size": "lg"
+                  },
+                  "children": [
+                    {
+                      "component": "avatar-image"
+                    },
+                    {
+                      "component": "avatar-fallback",
+                      "text": "AO"
+                    }
+                  ]
+                },
+                {
+                  "component": "card-title",
+                  "text": "Order #10482"
+                },
+                {
+                  "component": "card-description",
+                  "text": "Amara Okafor · placed 14 March 2026 · paid by Visa ending 4417"
+                },
+                {
+                  "component": "badge",
+                  "props": {
+                    "variant": "secondary"
+                  },
+                  "text": "Delivered"
+                }
+              ]
+            },
+            {
+              "component": "card-content",
+              "children": [
+                {
+                  "component": "alert",
+                  "children": [
+                    {
+                      "component": "alert-title",
+                      "text": "Partial refund issued 19 March"
+                    },
+                    {
+                      "component": "alert-description",
+                      "text": "$24.00 was refunded for the damaged desk mat. Refunds reach the card within five working days."
+                    }
+                  ]
+                },
+                {
+                  "component": "separator",
+                  "props": {
+                    "decorative": true,
+                    "orientation": "horizontal"
+                  }
+                },
+                {
+                  "component": "table",
+                  "children": [
+                    {
+                      "component": "table-caption",
+                      "text": "Items in order #10482."
+                    },
+                    {
+                      "component": "table-header",
+                      "children": [
+                        {
+                          "component": "table-row",
+                          "children": [
+                            {
+                              "component": "table-head",
+                              "text": "Item"
+                            },
+                            {
+                              "component": "table-head",
+                              "text": "Quantity"
+                            },
+                            {
+                              "component": "table-head",
+                              "text": "Unit price"
+                            },
+                            {
+                              "component": "table-head",
+                              "text": "Line total"
+                            }
+                          ]
+                        }
+                      ]
+                    },
+                    {
+                      "component": "table-body",
+                      "children": [
+                        {
+                          "component": "table-row",
+                          "children": [
+                            {
+                              "component": "table-cell",
+                              "text": "Adjustable standing desk, oak"
+                            },
+                            {
+                              "component": "table-cell",
+                              "text": "1"
+                            },
+                            {
+                              "component": "table-cell",
+                              "text": "$279.00"
+                            },
+                            {
+                              "component": "table-cell",
+                              "text": "$279.00"
+                            }
+                          ]
+                        },
+                        {
+                          "component": "table-row",
+                          "children": [
+                            {
+                              "component": "table-cell",
+                              "text": "Desk mat, charcoal"
+                            },
+                            {
+                              "component": "table-cell",
+                              "text": "2"
+                            },
+                            {
+                              "component": "table-cell",
+                              "text": "$24.00"
+                            },
+                            {
+                              "component": "table-cell",
+                              "text": "$48.00"
+                            }
+                          ]
+                        }
+                      ]
+                    },
+                    {
+                      "component": "table-footer",
+                      "children": [
+                        {
+                          "component": "table-row",
+                          "children": [
+                            {
+                              "component": "table-cell",
+                              "text": "Total after refund"
+                            },
+                            {
+                              "component": "table-cell"
+                            },
+                            {
+                              "component": "table-cell"
+                            },
+                            {
+                              "component": "table-cell",
+                              "text": "$303.00"
+                            }
+                          ]
+                        }
+                      ]
+                    }
+                  ]
+                }
+              ]
+            },
+            {
+              "component": "card-footer",
+              "children": [
+                {
+                  "component": "button",
+                  "props": {
+                    "variant": "outline"
+                  },
+                  "text": "Download invoice"
+                },
+                {
+                  "component": "button",
+                  "props": {
+                    "variant": "secondary"
+                  },
+                  "text": "Start a return"
+                }
+              ]
+            }
+          ]
+        }
+      }
+    },
+    {
+      "id": "ex.invite-teammates-dialog",
+      "intent": "overlay-task",
+      "name": "Invite teammates dialog",
+      "prompt": "a dialog for inviting teammates to the workspace",
+      "description": "A short task carried out over the page it belongs to. The task is not destructive, so Dialog is correct: it is dismissible by overlay and Escape. The trigger carries its own label, DialogTitle names the panel for aria-labelledby, each control sits in a Field with a FieldLabel, and the Select's trigger always displays the current value.",
+      "surface": {
+        "dspackSurface": "0.1",
+        "system": "shadcn/ui",
+        "intent": "overlay-task",
+        "root": {
+          "component": "dialog",
+          "props": {
+            "modal": true
+          },
+          "children": [
+            {
+              "component": "dialog-trigger",
+              "children": [
+                {
+                  "component": "button",
+                  "text": "Invite people"
+                }
+              ]
+            },
+            {
+              "component": "dialog-content",
+              "children": [
+                {
+                  "component": "dialog-header",
+                  "children": [
+                    {
+                      "component": "dialog-title",
+                      "text": "Invite people to Northwind"
+                    },
+                    {
+                      "component": "dialog-description",
+                      "text": "Each person receives an email invitation that expires in seven days."
+                    }
+                  ]
+                },
+                {
+                  "component": "field",
+                  "props": {
+                    "orientation": "vertical"
+                  },
+                  "children": [
+                    {
+                      "component": "field-label",
+                      "text": "Email addresses"
+                    },
+                    {
+                      "component": "textarea",
+                      "id": "invite-emails",
+                      "props": {
+                        "name": "invitees",
+                        "rows": 3,
+                        "placeholder": "maya@example.com, sam@example.com"
+                      }
+                    },
+                    {
+                      "component": "field-description",
+                      "text": "Separate addresses with a comma. Up to 20 people per invitation."
+                    }
+                  ]
+                },
+                {
+                  "component": "field",
+                  "props": {
+                    "orientation": "vertical"
+                  },
+                  "children": [
+                    {
+                      "component": "field-label",
+                      "text": "Role"
+                    },
+                    {
+                      "component": "select",
+                      "props": {
+                        "name": "role",
+                        "defaultValue": "member"
+                      },
+                      "children": [
+                        {
+                          "component": "select-trigger",
+                          "id": "invite-role",
+                          "children": [
+                            {
+                              "component": "select-value",
+                              "text": "Member"
+                            }
+                          ]
+                        },
+                        {
+                          "component": "select-content",
+                          "children": [
+                            {
+                              "component": "select-item",
+                              "text": "Member — can read and comment"
+                            },
+                            {
+                              "component": "select-item",
+                              "text": "Editor — can change project settings"
+                            },
+                            {
+                              "component": "select-item",
+                              "text": "Admin — can manage members and billing"
+                            }
+                          ]
+                        }
+                      ]
+                    },
+                    {
+                      "component": "field-description",
+                      "text": "Everyone in this invitation gets the same role. You can change it later."
+                    }
+                  ]
+                },
+                {
+                  "component": "dialog-footer",
+                  "children": [
+                    {
+                      "component": "dialog-close",
+                      "text": "Cancel"
+                    },
+                    {
+                      "component": "button",
+                      "text": "Send invitations"
+                    }
+                  ]
+                }
+              ]
+            }
+          ]
+        }
+      }
+    },
+    {
+      "id": "ex.project-workspace-panels",
+      "intent": "panel-navigation",
+      "name": "Project workspace panels",
+      "prompt": "a project workspace with tabs for overview, activity, and access",
+      "description": "One screen divided into sibling panels. Tabs supplies defaultValue so a panel is selected on first paint, every TabsTrigger has a matching TabsContent, and manual activation keeps arrow-key traversal from firing a request per tab. The activity feed scrolls inside a single ScrollArea rather than nesting scroll regions.",
+      "surface": {
+        "dspackSurface": "0.1",
+        "system": "shadcn/ui",
+        "intent": "panel-navigation",
+        "root": {
+          "component": "tabs",
+          "props": {
+            "defaultValue": "overview",
+            "activationMode": "manual"
+          },
+          "children": [
+            {
+              "component": "tabs-list",
+              "children": [
+                {
+                  "component": "tabs-trigger",
+                  "id": "overview",
+                  "text": "Overview"
+                },
+                {
+                  "component": "tabs-trigger",
+                  "id": "activity",
+                  "text": "Activity"
+                },
+                {
+                  "component": "tabs-trigger",
+                  "id": "access",
+                  "text": "Access"
+                }
+              ]
+            },
+            {
+              "component": "tabs-content",
+              "id": "overview",
+              "children": [
+                {
+                  "component": "card",
+                  "children": [
+                    {
+                      "component": "card-header",
+                      "children": [
+                        {
+                          "component": "card-title",
+                          "text": "Northwind Checkout"
+                        },
+                        {
+                          "component": "card-description",
+                          "text": "Production · eu-west-1 · last deploy 41 minutes ago"
+                        }
+                      ]
+                    },
+                    {
+                      "component": "card-content",
+                      "children": [
+                        {
+                          "component": "alert",
+                          "children": [
+                            {
+                              "component": "alert-title",
+                              "text": "Two environments are running an outdated build"
+                            },
+                            {
+                              "component": "alert-description",
+                              "text": "Staging and preview are three commits behind production. Redeploy them to keep test results meaningful."
+                            }
+                          ]
+                        }
+                      ]
+                    }
+                  ]
+                }
+              ]
+            },
+            {
+              "component": "tabs-content",
+              "id": "activity",
+              "children": [
+                {
+                  "component": "scroll-area",
+                  "props": {
+                    "type": "auto"
+                  },
+                  "children": [
+                    {
+                      "component": "card",
+                      "children": [
+                        {
+                          "component": "card-header",
+                          "children": [
+                            {
+                              "component": "card-title",
+                              "text": "Deploy 4f2c1a succeeded"
+                            },
+                            {
+                              "component": "card-description",
+                              "text": "Priya Raman · 41 minutes ago · 2 min 18 s"
+                            }
+                          ]
+                        }
+                      ]
+                    },
+                    {
+                      "component": "card",
+                      "children": [
+                        {
+                          "component": "card-header",
+                          "children": [
+                            {
+                              "component": "card-title",
+                              "text": "Environment variable STRIPE_KEY rotated"
+                            },
+                            {
+                              "component": "card-description",
+                              "text": "Amara Okafor · 3 hours ago"
+                            }
+                          ]
+                        }
+                      ]
+                    },
+                    {
+                      "component": "card",
+                      "children": [
+                        {
+                          "component": "card-header",
+                          "children": [
+                            {
+                              "component": "card-title",
+                              "text": "Deploy 91be07 rolled back"
+                            },
+                            {
+                              "component": "card-description",
+                              "text": "Jonas Weber · yesterday · checkout error rate above 2%"
+                            }
+                          ]
+                        }
+                      ]
+                    }
+                  ]
+                }
+              ]
+            },
+            {
+              "component": "tabs-content",
+              "id": "access",
+              "children": [
+                {
+                  "component": "card",
+                  "children": [
+                    {
+                      "component": "card-header",
+                      "children": [
+                        {
+                          "component": "card-title",
+                          "text": "Who can deploy"
+                        },
+                        {
+                          "component": "card-description",
+                          "text": "Applies to the production environment only."
+                        }
+                      ]
+                    },
+                    {
+                      "component": "card-content",
+                      "children": [
+                        {
+                          "component": "field",
+                          "props": {
+                            "orientation": "horizontal"
+                          },
+                          "children": [
+                            {
+                              "component": "field-label",
+                              "text": "Require a second reviewer before production deploys"
+                            },
+                            {
+                              "component": "switch",
+                              "id": "require-review",
+                              "props": {
+                                "name": "requireReview",
+                                "defaultChecked": true
+                              }
+                            }
+                          ]
+                        }
+                      ]
+                    }
+                  ]
+                }
+              ]
+            }
+          ]
+        }
+      }
+    },
+    {
+      "id": "ex.docs-article-trail",
+      "intent": "wayfinding",
+      "name": "Documentation article trail",
+      "prompt": "a documentation page header showing where the article sits, with paging to the next pages",
+      "description": "Orientation, not content. The Breadcrumb runs root-first and ends in a single BreadcrumbPage, so exactly one crumb carries aria-current and the current page does not link to itself. The Pagination wraps every control — including the ellipsis — in its own PaginationItem, and its nav gets a distinct aria-label so the two landmarks can be told apart.",
+      "surface": {
+        "dspackSurface": "0.1",
+        "system": "shadcn/ui",
+        "intent": "wayfinding",
+        "root": {
+          "component": "card",
+          "children": [
+            {
+              "component": "card-header",
+              "children": [
+                {
+                  "component": "breadcrumb",
+                  "props": {
+                    "aria-label": "Breadcrumb"
+                  },
+                  "children": [
+                    {
+                      "component": "breadcrumb-list",
+                      "children": [
+                        {
+                          "component": "breadcrumb-item",
+                          "children": [
+                            {
+                              "component": "breadcrumb-link",
+                              "text": "Docs"
+                            }
+                          ]
+                        },
+                        {
+                          "component": "breadcrumb-separator"
+                        },
+                        {
+                          "component": "breadcrumb-item",
+                          "children": [
+                            {
+                              "component": "breadcrumb-link",
+                              "text": "Authentication"
+                            }
+                          ]
+                        },
+                        {
+                          "component": "breadcrumb-separator"
+                        },
+                        {
+                          "component": "breadcrumb-item",
+                          "children": [
+                            {
+                              "component": "breadcrumb-page",
+                              "text": "Configuring SSO with Okta"
+                            }
+                          ]
+                        }
+                      ]
+                    }
+                  ]
+                },
+                {
+                  "component": "card-title",
+                  "text": "Configuring SSO with Okta"
+                },
+                {
+                  "component": "card-description",
+                  "text": "Updated 12 June 2026 · about 6 minutes to read"
+                }
+              ]
+            },
+            {
+              "component": "card-content",
+              "children": [
+                {
+                  "component": "alert",
+                  "children": [
+                    {
+                      "component": "alert-title",
+                      "text": "Available on Enterprise plans"
+                    },
+                    {
+                      "component": "alert-description",
+                      "text": "SAML single sign-on is not included on Team plans. Upgrading takes effect immediately, and existing sessions stay signed in."
+                    }
+                  ]
+                }
+              ]
+            },
+            {
+              "component": "card-footer",
+              "children": [
+                {
+                  "component": "pagination",
+                  "props": {
+                    "aria-label": "Article pages"
+                  },
+                  "children": [
+                    {
+                      "component": "pagination-content",
                       "children": [
-                        { "component": "alert-dialog-cancel", "text": "Cancel" },
-                        { "component": "alert-dialog-action", "text": "Delete account" }
+                        {
+                          "component": "pagination-item",
+                          "children": [
+                            {
+                              "component": "pagination-previous"
+                            }
+                          ]
+                        },
+                        {
+                          "component": "pagination-item",
+                          "children": [
+                            {
+                              "component": "pagination-link",
+                              "text": "1"
+                            }
+                          ]
+                        },
+                        {
+                          "component": "pagination-item",
+                          "children": [
+                            {
+                              "component": "pagination-link",
+                              "text": "2"
+                            }
+                          ]
+                        },
+                        {
+                          "component": "pagination-item",
+                          "children": [
+                            {
+                              "component": "pagination-link",
+                              "text": "3"
+                            }
+                          ]
+                        },
+                        {
+                          "component": "pagination-item",
+                          "children": [
+                            {
+                              "component": "pagination-ellipsis"
+                            }
+                          ]
+                        },
+                        {
+                          "component": "pagination-item",
+                          "children": [
+                            {
+                              "component": "pagination-link",
+                              "text": "9"
+                            }
+                          ]
+                        },
+                        {
+                          "component": "pagination-item",
+                          "children": [
+                            {
+                              "component": "pagination-next"
+                            }
+                          ]
+                        }
                       ]
                     }
                   ]
@@ -1188,70 +8900,633 @@
       }
     },
     {
-      "id": "ex.support-ticket-queue",
-      "intent": "record-collection",
-      "name": "Support ticket queue",
-      "prompt": "a queue of open support tickets with status and priority",
-      "description": "A semantic data table from the Table primitives: a caption naming the collection, header cells for column association, and ticket rows in the body. Status renders as a Badge whose text stays readable — the variant reflects state, color is never the only signal.",
+      "id": "ex.usage-help-affordances",
+      "intent": "supplementary-detail",
+      "name": "Usage panel with on-demand explanation",
+      "prompt": "a usage panel that explains how the numbers are calculated",
+      "description": "Three tiers of supplementary detail, each used for what it can carry: a Tooltip for one line of text on a control that already has its own label, a Popover with a title for a paragraph the reader controls, and an Accordion for the questions that would otherwise crowd the panel. The Progress carries an explicit value and is named by the FieldLabel beside it.",
       "surface": {
         "dspackSurface": "0.1",
         "system": "shadcn/ui",
-        "intent": "record-collection",
+        "intent": "supplementary-detail",
         "root": {
-          "component": "table",
+          "component": "card",
           "children": [
-            { "component": "table-caption", "text": "Open support tickets, newest first." },
             {
-              "component": "table-header",
+              "component": "card-header",
               "children": [
                 {
-                  "component": "table-row",
+                  "component": "card-title",
+                  "text": "Metered usage"
+                },
+                {
+                  "component": "card-description",
+                  "text": "1–31 August · Scale plan"
+                }
+              ]
+            },
+            {
+              "component": "card-content",
+              "children": [
+                {
+                  "component": "field",
+                  "props": {
+                    "orientation": "vertical"
+                  },
+                  "children": [
+                    {
+                      "component": "field-label",
+                      "text": "API requests"
+                    },
+                    {
+                      "component": "progress",
+                      "id": "usage-requests",
+                      "props": {
+                        "value": 68,
+                        "className": "h-2"
+                      }
+                    },
+                    {
+                      "component": "field-description",
+                      "text": "681,402 of 1,000,000 included requests"
+                    }
+                  ]
+                },
+                {
+                  "component": "tooltip",
+                  "props": {
+                    "delayDuration": 200
+                  },
                   "children": [
-                    { "component": "table-head", "text": "Ticket" },
-                    { "component": "table-head", "text": "Subject" },
-                    { "component": "table-head", "text": "Status" },
-                    { "component": "table-head", "text": "Priority" }
+                    {
+                      "component": "tooltip-trigger",
+                      "children": [
+                        {
+                          "component": "button",
+                          "props": {
+                            "variant": "ghost",
+                            "size": "sm"
+                          },
+                          "text": "Overage rate"
+                        }
+                      ]
+                    },
+                    {
+                      "component": "tooltip-content",
+                      "text": "$0.40 per 1,000 requests above the included volume."
+                    }
+                  ]
+                },
+                {
+                  "component": "popover",
+                  "children": [
+                    {
+                      "component": "popover-trigger",
+                      "children": [
+                        {
+                          "component": "button",
+                          "props": {
+                            "variant": "outline",
+                            "size": "sm"
+                          },
+                          "text": "How usage is measured"
+                        }
+                      ]
+                    },
+                    {
+                      "component": "popover-content",
+                      "children": [
+                        {
+                          "component": "popover-header",
+                          "children": [
+                            {
+                              "component": "popover-title",
+                              "text": "How usage is measured"
+                            },
+                            {
+                              "component": "popover-description",
+                              "text": "Every authenticated call to the REST and GraphQL endpoints counts once, including calls that return a cached response. Webhooks you receive are not counted."
+                            }
+                          ]
+                        }
+                      ]
+                    }
+                  ]
+                },
+                {
+                  "component": "accordion",
+                  "props": {
+                    "type": "single",
+                    "collapsible": true
+                  },
+                  "children": [
+                    {
+                      "component": "accordion-item",
+                      "children": [
+                        {
+                          "component": "accordion-trigger",
+                          "text": "What happens when I pass the included volume?"
+                        },
+                        {
+                          "component": "accordion-content",
+                          "text": "Requests keep succeeding. Overage is billed on the next invoice at the rate above, and an email goes to the billing contact at 90% and 100% of the included volume."
+                        }
+                      ]
+                    },
+                    {
+                      "component": "accordion-item",
+                      "children": [
+                        {
+                          "component": "accordion-trigger",
+                          "text": "When does the counter reset?"
+                        },
+                        {
+                          "component": "accordion-content",
+                          "text": "At 00:00 UTC on the first day of the billing period. Changing plan mid-period resets the counter and prorates the included volume."
+                        }
+                      ]
+                    }
                   ]
                 }
               ]
+            }
+          ]
+        }
+      }
+    },
+    {
+      "id": "ex.customer-context-sheet",
+      "intent": "supplementary-detail",
+      "name": "Customer context side panel",
+      "prompt": "a side panel showing customer context next to a support ticket",
+      "description": "Reference material beside the work, not instead of it: a Sheet pinned to the edge so the ticket stays in view. SheetTitle gives the panel its accessible name, the history scrolls in one ScrollArea placed as the middle child so the footer stays reachable, and SheetClose gives an explicit way out.",
+      "surface": {
+        "dspackSurface": "0.1",
+        "system": "shadcn/ui",
+        "intent": "supplementary-detail",
+        "root": {
+          "component": "sheet",
+          "props": {
+            "side": "right"
+          },
+          "children": [
+            {
+              "component": "sheet-trigger",
+              "children": [
+                {
+                  "component": "button",
+                  "props": {
+                    "variant": "outline"
+                  },
+                  "text": "Customer context"
+                }
+              ]
             },
             {
-              "component": "table-body",
+              "component": "sheet-content",
               "children": [
                 {
-                  "component": "table-row",
+                  "component": "sheet-header",
                   "children": [
-                    { "component": "table-cell", "text": "#4812" },
-                    { "component": "table-cell", "text": "Cannot export billing statement" },
                     {
-                      "component": "table-cell",
-                      "children": [{ "component": "badge", "props": { "variant": "destructive" }, "text": "Urgent" }]
+                      "component": "sheet-title",
+                      "text": "Amara Okafor"
                     },
-                    { "component": "table-cell", "text": "P1" }
+                    {
+                      "component": "sheet-description",
+                      "text": "Scale plan · customer since March 2023 · 14 tickets, 2 open"
+                    }
                   ]
                 },
                 {
-                  "component": "table-row",
+                  "component": "scroll-area",
+                  "props": {
+                    "type": "auto"
+                  },
                   "children": [
-                    { "component": "table-cell", "text": "#4809" },
-                    { "component": "table-cell", "text": "Two-factor codes arrive late" },
                     {
-                      "component": "table-cell",
-                      "children": [{ "component": "badge", "props": { "variant": "secondary" }, "text": "Waiting on customer" }]
+                      "component": "card",
+                      "children": [
+                        {
+                          "component": "card-header",
+                          "children": [
+                            {
+                              "component": "card-title",
+                              "text": "#4812 · Cannot export billing statement"
+                            },
+                            {
+                              "component": "card-description",
+                              "text": "Opened 2 days ago · waiting on engineering"
+                            }
+                          ]
+                        }
+                      ]
                     },
-                    { "component": "table-cell", "text": "P2" }
+                    {
+                      "component": "card",
+                      "children": [
+                        {
+                          "component": "card-header",
+                          "children": [
+                            {
+                              "component": "card-title",
+                              "text": "#4655 · Seat count wrong after downgrade"
+                            },
+                            {
+                              "component": "card-description",
+                              "text": "Resolved 3 weeks ago · refunded $120.00"
+                            }
+                          ]
+                        }
+                      ]
+                    },
+                    {
+                      "component": "card",
+                      "children": [
+                        {
+                          "component": "card-header",
+                          "children": [
+                            {
+                              "component": "card-title",
+                              "text": "#4390 · SSO metadata rejected"
+                            },
+                            {
+                              "component": "card-description",
+                              "text": "Resolved 2 months ago · configuration error on the customer side"
+                            }
+                          ]
+                        }
+                      ]
+                    }
                   ]
                 },
                 {
-                  "component": "table-row",
+                  "component": "sheet-footer",
                   "children": [
-                    { "component": "table-cell", "text": "#4801" },
-                    { "component": "table-cell", "text": "Dark mode contrast on invoices" },
                     {
-                      "component": "table-cell",
-                      "children": [{ "component": "badge", "props": { "variant": "outline" }, "text": "Open" }]
+                      "component": "sheet-close",
+                      "text": "Close"
+                    },
+                    {
+                      "component": "button",
+                      "props": {
+                        "variant": "secondary"
+                      },
+                      "text": "Open full profile"
+                    }
+                  ]
+                }
+              ]
+            }
+          ]
+        }
+      }
+    },
+    {
+      "id": "ex.import-run-status",
+      "intent": "status-feedback",
+      "name": "Import run status",
+      "prompt": "a panel showing the status of a running customer import",
+      "description": "The state of one operation, told in text first: a destructive Alert with a title naming what went wrong and a single action in AlertAction, a determinate Progress with an explicit value named by the FieldLabel beside it, and a Badge whose wording carries the meaning rather than its colour.",
+      "surface": {
+        "dspackSurface": "0.1",
+        "system": "shadcn/ui",
+        "intent": "status-feedback",
+        "root": {
+          "component": "card",
+          "children": [
+            {
+              "component": "card-header",
+              "children": [
+                {
+                  "component": "card-title",
+                  "text": "Customer import"
+                },
+                {
+                  "component": "card-description",
+                  "text": "Batch 3311 · started 09:42 · source northwind-crm.csv"
+                },
+                {
+                  "component": "badge",
+                  "props": {
+                    "variant": "destructive"
+                  },
+                  "text": "Needs attention"
+                }
+              ]
+            },
+            {
+              "component": "card-content",
+              "children": [
+                {
+                  "component": "alert",
+                  "props": {
+                    "variant": "destructive"
+                  },
+                  "children": [
+                    {
+                      "component": "alert-title",
+                      "text": "312 rows were rejected"
+                    },
+                    {
+                      "component": "alert-description",
+                      "text": "Rows with no billing country were skipped; the rest of the batch continued. Fix the source file and retry only the rejected rows."
+                    },
+                    {
+                      "component": "alert-action",
+                      "children": [
+                        {
+                          "component": "button",
+                          "props": {
+                            "variant": "outline",
+                            "size": "sm"
+                          },
+                          "text": "Download error report"
+                        }
+                      ]
+                    }
+                  ]
+                },
+                {
+                  "component": "field",
+                  "props": {
+                    "orientation": "vertical"
+                  },
+                  "children": [
+                    {
+                      "component": "field-label",
+                      "text": "Rows processed"
+                    },
+                    {
+                      "component": "progress",
+                      "id": "import-progress",
+                      "props": {
+                        "value": 74
+                      }
+                    },
+                    {
+                      "component": "field-description",
+                      "text": "3,561 of 4,812 rows · about 4 minutes remaining"
+                    }
+                  ]
+                },
+                {
+                  "component": "separator",
+                  "props": {
+                    "decorative": true,
+                    "orientation": "horizontal"
+                  }
+                }
+              ]
+            },
+            {
+              "component": "card-footer",
+              "children": [
+                {
+                  "component": "button",
+                  "props": {
+                    "variant": "outline"
+                  },
+                  "text": "Pause import"
+                },
+                {
+                  "component": "button",
+                  "text": "Retry rejected rows"
+                }
+              ]
+            }
+          ]
+        }
+      }
+    },
+    {
+      "id": "ex.orders-table-loading",
+      "intent": "loading-state",
+      "name": "Orders table loading state",
+      "prompt": "the loading state for a table of recent orders",
+      "description": "The placeholder keeps the shape of what is coming: the real Table structure with real column headers, and Skeletons sized like the cell contents so nothing reflows when the rows land. Every Skeleton is aria-hidden and holds no controls; the loading state is announced once, by the Spinner that names what is loading.",
+      "surface": {
+        "dspackSurface": "0.1",
+        "system": "shadcn/ui",
+        "intent": "loading-state",
+        "root": {
+          "component": "card",
+          "children": [
+            {
+              "component": "card-header",
+              "children": [
+                {
+                  "component": "card-title",
+                  "text": "Orders"
+                },
+                {
+                  "component": "card-description",
+                  "text": "The 50 most recent orders"
+                },
+                {
+                  "component": "spinner",
+                  "props": {
+                    "className": "size-4",
+                    "aria-label": "Loading orders"
+                  }
+                }
+              ]
+            },
+            {
+              "component": "table",
+              "children": [
+                {
+                  "component": "table-caption",
+                  "text": "Recent orders. Rows are still loading."
+                },
+                {
+                  "component": "table-header",
+                  "children": [
+                    {
+                      "component": "table-row",
+                      "children": [
+                        {
+                          "component": "table-head",
+                          "text": "Order"
+                        },
+                        {
+                          "component": "table-head",
+                          "text": "Customer"
+                        },
+                        {
+                          "component": "table-head",
+                          "text": "Status"
+                        },
+                        {
+                          "component": "table-head",
+                          "text": "Total"
+                        }
+                      ]
+                    }
+                  ]
+                },
+                {
+                  "component": "table-body",
+                  "children": [
+                    {
+                      "component": "table-row",
+                      "children": [
+                        {
+                          "component": "table-cell",
+                          "children": [
+                            {
+                              "component": "skeleton",
+                              "props": {
+                                "className": "h-4 w-16",
+                                "aria-hidden": true
+                              }
+                            }
+                          ]
+                        },
+                        {
+                          "component": "table-cell",
+                          "children": [
+                            {
+                              "component": "skeleton",
+                              "props": {
+                                "className": "h-4 w-40",
+                                "aria-hidden": true
+                              }
+                            }
+                          ]
+                        },
+                        {
+                          "component": "table-cell",
+                          "children": [
+                            {
+                              "component": "skeleton",
+                              "props": {
+                                "className": "h-5 w-24 rounded-full",
+                                "aria-hidden": true
+                              }
+                            }
+                          ]
+                        },
+                        {
+                          "component": "table-cell",
+                          "children": [
+                            {
+                              "component": "skeleton",
+                              "props": {
+                                "className": "h-4 w-14",
+                                "aria-hidden": true
+                              }
+                            }
+                          ]
+                        }
+                      ]
+                    },
+                    {
+                      "component": "table-row",
+                      "children": [
+                        {
+                          "component": "table-cell",
+                          "children": [
+                            {
+                              "component": "skeleton",
+                              "props": {
+                                "className": "h-4 w-16",
+                                "aria-hidden": true
+                              }
+                            }
+                          ]
+                        },
+                        {
+                          "component": "table-cell",
+                          "children": [
+                            {
+                              "component": "skeleton",
+                              "props": {
+                                "className": "h-4 w-40",
+                                "aria-hidden": true
+                              }
+                            }
+                          ]
+                        },
+                        {
+                          "component": "table-cell",
+                          "children": [
+                            {
+                              "component": "skeleton",
+                              "props": {
+                                "className": "h-5 w-24 rounded-full",
+                                "aria-hidden": true
+                              }
+                            }
+                          ]
+                        },
+                        {
+                          "component": "table-cell",
+                          "children": [
+                            {
+                              "component": "skeleton",
+                              "props": {
+                                "className": "h-4 w-14",
+                                "aria-hidden": true
+                              }
+                            }
+                          ]
+                        }
+                      ]
                     },
-                    { "component": "table-cell", "text": "P3" }
+                    {
+                      "component": "table-row",
+                      "children": [
+                        {
+                          "component": "table-cell",
+                          "children": [
+                            {
+                              "component": "skeleton",
+                              "props": {
+                                "className": "h-4 w-16",
+                                "aria-hidden": true
+                              }
+                            }
+                          ]
+                        },
+                        {
+                          "component": "table-cell",
+                          "children": [
+                            {
+                              "component": "skeleton",
+                              "props": {
+                                "className": "h-4 w-40",
+                                "aria-hidden": true
+                              }
+                            }
+                          ]
+                        },
+                        {
+                          "component": "table-cell",
+                          "children": [
+                            {
+                              "component": "skeleton",
+                              "props": {
+                                "className": "h-5 w-24 rounded-full",
+                                "aria-hidden": true
+                              }
+                            }
+                          ]
+                        },
+                        {
+                          "component": "table-cell",
+                          "children": [
+                            {
+                              "component": "skeleton",
+                              "props": {
+                                "className": "h-4 w-14",
+                                "aria-hidden": true
+                              }
+                            }
+                          ]
+                        }
+                      ]
+                    }
                   ]
                 }
               ]
@@ -1280,14 +9555,30 @@
           "installCommand": "npx shadcn@latest add alert-dialog",
           "guidance": "Built on @radix-ui/react-alert-dialog.",
           "subComponents": {
-            "alert-dialog-trigger": { "exportName": "AlertDialogTrigger" },
-            "alert-dialog-content": { "exportName": "AlertDialogContent" },
-            "alert-dialog-header": { "exportName": "AlertDialogHeader" },
-            "alert-dialog-title": { "exportName": "AlertDialogTitle" },
-            "alert-dialog-description": { "exportName": "AlertDialogDescription" },
-            "alert-dialog-footer": { "exportName": "AlertDialogFooter" },
-            "alert-dialog-action": { "exportName": "AlertDialogAction" },
-            "alert-dialog-cancel": { "exportName": "AlertDialogCancel" }
+            "alert-dialog-trigger": {
+              "exportName": "AlertDialogTrigger"
+            },
+            "alert-dialog-content": {
+              "exportName": "AlertDialogContent"
+            },
+            "alert-dialog-header": {
+              "exportName": "AlertDialogHeader"
+            },
+            "alert-dialog-title": {
+              "exportName": "AlertDialogTitle"
+            },
+            "alert-dialog-description": {
+              "exportName": "AlertDialogDescription"
+            },
+            "alert-dialog-footer": {
+              "exportName": "AlertDialogFooter"
+            },
+            "alert-dialog-action": {
+              "exportName": "AlertDialogAction"
+            },
+            "alert-dialog-cancel": {
+              "exportName": "AlertDialogCancel"
+            }
           }
         },
         "dialog": {
@@ -1295,13 +9586,27 @@
           "installCommand": "npx shadcn@latest add dialog",
           "guidance": "Built on @radix-ui/react-dialog.",
           "subComponents": {
-            "dialog-trigger": { "exportName": "DialogTrigger" },
-            "dialog-content": { "exportName": "DialogContent" },
-            "dialog-header": { "exportName": "DialogHeader" },
-            "dialog-title": { "exportName": "DialogTitle" },
-            "dialog-description": { "exportName": "DialogDescription" },
-            "dialog-footer": { "exportName": "DialogFooter" },
-            "dialog-close": { "exportName": "DialogClose" }
+            "dialog-trigger": {
+              "exportName": "DialogTrigger"
+            },
+            "dialog-content": {
+              "exportName": "DialogContent"
+            },
+            "dialog-header": {
+              "exportName": "DialogHeader"
+            },
+            "dialog-title": {
+              "exportName": "DialogTitle"
+            },
+            "dialog-description": {
+              "exportName": "DialogDescription"
+            },
+            "dialog-footer": {
+              "exportName": "DialogFooter"
+            },
+            "dialog-close": {
+              "exportName": "DialogClose"
+            }
           }
         },
         "card": {
@@ -1309,11 +9614,21 @@
           "installCommand": "npx shadcn@latest add card",
           "guidance": "Pure HTML/CSS components — no Radix dependency.",
           "subComponents": {
-            "card-header": { "exportName": "CardHeader" },
-            "card-title": { "exportName": "CardTitle" },
-            "card-description": { "exportName": "CardDescription" },
-            "card-content": { "exportName": "CardContent" },
-            "card-footer": { "exportName": "CardFooter" }
+            "card-header": {
+              "exportName": "CardHeader"
+            },
+            "card-title": {
+              "exportName": "CardTitle"
+            },
+            "card-description": {
+              "exportName": "CardDescription"
+            },
+            "card-content": {
+              "exportName": "CardContent"
+            },
+            "card-footer": {
+              "exportName": "CardFooter"
+            }
           }
         },
         "input": {
@@ -1333,18 +9648,42 @@
           "installCommand": "npx shadcn@latest add dropdown-menu",
           "guidance": "Built on @radix-ui/react-dropdown-menu.",
           "subComponents": {
-            "dropdown-menu-trigger": { "exportName": "DropdownMenuTrigger" },
-            "dropdown-menu-content": { "exportName": "DropdownMenuContent" },
-            "dropdown-menu-item": { "exportName": "DropdownMenuItem" },
-            "dropdown-menu-checkbox-item": { "exportName": "DropdownMenuCheckboxItem" },
-            "dropdown-menu-radio-group": { "exportName": "DropdownMenuRadioGroup" },
-            "dropdown-menu-radio-item": { "exportName": "DropdownMenuRadioItem" },
-            "dropdown-menu-label": { "exportName": "DropdownMenuLabel" },
-            "dropdown-menu-separator": { "exportName": "DropdownMenuSeparator" },
-            "dropdown-menu-group": { "exportName": "DropdownMenuGroup" },
-            "dropdown-menu-sub": { "exportName": "DropdownMenuSub" },
-            "dropdown-menu-sub-trigger": { "exportName": "DropdownMenuSubTrigger" },
-            "dropdown-menu-sub-content": { "exportName": "DropdownMenuSubContent" }
+            "dropdown-menu-trigger": {
+              "exportName": "DropdownMenuTrigger"
+            },
+            "dropdown-menu-content": {
+              "exportName": "DropdownMenuContent"
+            },
+            "dropdown-menu-item": {
+              "exportName": "DropdownMenuItem"
+            },
+            "dropdown-menu-checkbox-item": {
+              "exportName": "DropdownMenuCheckboxItem"
+            },
+            "dropdown-menu-radio-group": {
+              "exportName": "DropdownMenuRadioGroup"
+            },
+            "dropdown-menu-radio-item": {
+              "exportName": "DropdownMenuRadioItem"
+            },
+            "dropdown-menu-label": {
+              "exportName": "DropdownMenuLabel"
+            },
+            "dropdown-menu-separator": {
+              "exportName": "DropdownMenuSeparator"
+            },
+            "dropdown-menu-group": {
+              "exportName": "DropdownMenuGroup"
+            },
+            "dropdown-menu-sub": {
+              "exportName": "DropdownMenuSub"
+            },
+            "dropdown-menu-sub-trigger": {
+              "exportName": "DropdownMenuSubTrigger"
+            },
+            "dropdown-menu-sub-content": {
+              "exportName": "DropdownMenuSubContent"
+            }
           }
         },
         "table": {
@@ -1352,13 +9691,27 @@
           "installCommand": "npx shadcn@latest add table",
           "guidance": "Pure HTML/CSS table primitives — no Radix dependency. Table renders a <table> wrapped in a horizontally scrollable container; the sub-components map directly to the native thead, tbody, tfoot, tr, th, td, and caption elements. The primitives are presentational only: sorting, filtering, pagination, and row selection are typically composed with TanStack Table (@tanstack/react-table) on top of them, where the headless library owns the data state and these components render the resulting rows and cells.",
           "subComponents": {
-            "table-header": { "exportName": "TableHeader" },
-            "table-body": { "exportName": "TableBody" },
-            "table-footer": { "exportName": "TableFooter" },
-            "table-row": { "exportName": "TableRow" },
-            "table-head": { "exportName": "TableHead" },
-            "table-cell": { "exportName": "TableCell" },
-            "table-caption": { "exportName": "TableCaption" }
+            "table-header": {
+              "exportName": "TableHeader"
+            },
+            "table-body": {
+              "exportName": "TableBody"
+            },
+            "table-footer": {
+              "exportName": "TableFooter"
+            },
+            "table-row": {
+              "exportName": "TableRow"
+            },
+            "table-head": {
+              "exportName": "TableHead"
+            },
+            "table-cell": {
+              "exportName": "TableCell"
+            },
+            "table-caption": {
+              "exportName": "TableCaption"
+            }
           }
         }
       }
@@ -1387,11 +9740,26 @@
   },
   "layout": {
     "breakpoints": {
-      "sm": { "minWidth": "640px", "description": "Small devices and large phones in landscape." },
-      "md": { "minWidth": "768px", "description": "Tablets." },
-      "lg": { "minWidth": "1024px", "description": "Small desktops and laptops." },
-      "xl": { "minWidth": "1280px", "description": "Standard desktops." },
-      "2xl": { "minWidth": "1536px", "description": "Large desktops." }
+      "sm": {
+        "minWidth": "640px",
+        "description": "Small devices and large phones in landscape."
+      },
+      "md": {
+        "minWidth": "768px",
+        "description": "Tablets."
+      },
+      "lg": {
+        "minWidth": "1024px",
+        "description": "Small desktops and laptops."
+      },
+      "xl": {
+        "minWidth": "1280px",
+        "description": "Standard desktops."
+      },
+      "2xl": {
+        "minWidth": "1536px",
+        "description": "Large desktops."
+      }
     },
     "grid": {
       "columns": 12,
@@ -1399,9 +9767,18 @@
       "description": "Use the 12-column grid for page-level layout. Component-level layout should use flexbox or CSS grid directly."
     },
     "containers": {
-      "default": { "maxWidth": "1280px", "description": "Standard content container for most pages." },
-      "narrow": { "maxWidth": "768px", "description": "For focused reading experiences, forms, and auth flows." },
-      "wide": { "maxWidth": "1536px", "description": "For data-dense views like dashboards and admin panels." }
+      "default": {
+        "maxWidth": "1280px",
+        "description": "Standard content container for most pages."
+      },
+      "narrow": {
+        "maxWidth": "768px",
+        "description": "For focused reading experiences, forms, and auth flows."
+      },
+      "wide": {
+        "maxWidth": "1536px",
+        "description": "For data-dense views like dashboards and admin panels."
+      }
     },
     "spacingScale": {
       "baseUnit": "0.25rem",
diff --git a/package-lock.json b/package-lock.json
index f3dbcf7..220777c 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -18,7 +18,7 @@
         "ds-mcp": "dist/index.js"
       },
       "devDependencies": {
-        "@aestheticfunction/dspack-gen": "git+https://github.com/aestheticfunction/dspack-gen.git#c5bfd6de979f811466c6ba1e1c0f978defc4236f",
+        "@aestheticfunction/dspack-gen": "git+https://github.com/aestheticfunction/dspack-gen.git#5203569cb8d066ad545307500c2ae3f2adaa0239",
         "@types/minimist": "^1.2.5",
         "@types/node": "^20.0.0",
         "esbuild": "^0.25.0",
@@ -29,24 +29,27 @@
       }
     },
     "node_modules/@aestheticfunction/dspack-emit": {
-      "version": "0.3.1",
-      "resolved": "https://registry.npmjs.org/@aestheticfunction/dspack-emit/-/dspack-emit-0.3.1.tgz",
-      "integrity": "sha512-0vCFP5rvWGoIPvnBlB3puXkhoJhEyq/FQHrfj3JfPwf37WfASZb5ZOK3tPzB8ZhZTFkxvhjrvHeEYgRDOGm04w==",
+      "version": "0.7.0",
+      "resolved": "https://registry.npmjs.org/@aestheticfunction/dspack-emit/-/dspack-emit-0.7.0.tgz",
+      "integrity": "sha512-uD61qcAo/kNeYP5OMVKDfV6gI79cP9HNz4B0aQJ5cSDcsMdDDT2GZv8syLFeYfYH9ED14ZbC2i7p52S03NJeDw==",
       "dev": true,
       "license": "Apache-2.0",
       "dependencies": {
         "ajv": "^8.17.1",
         "ajv-formats": "^3.0.1"
+      },
+      "bin": {
+        "dspack-emit": "dist/cli.js"
       }
     },
     "node_modules/@aestheticfunction/dspack-gen": {
-      "version": "0.1.2",
-      "resolved": "git+ssh://git@github.com/aestheticfunction/dspack-gen.git#c5bfd6de979f811466c6ba1e1c0f978defc4236f",
-      "integrity": "sha512-g6XqqAzicd/3s9E9PRD3ua7q8hvrrHthqpy9CPTPVlQzIQAm28n7qwhg9QN8SN9pijAacdIDtFXpEtU8z7hT4Q==",
+      "version": "0.5.0",
+      "resolved": "git+ssh://git@github.com/aestheticfunction/dspack-gen.git#5203569cb8d066ad545307500c2ae3f2adaa0239",
+      "integrity": "sha512-5CMaM8YmV4bX1gNfQTuZOergdKk1we2FuLnGgRfcC0hP1BlCRgVqnVpBLLo2CEx7XC2odT0MYPgHxPTXN3qD5g==",
       "dev": true,
       "license": "Apache-2.0",
       "dependencies": {
-        "@aestheticfunction/dspack-emit": "^0.3.1",
+        "@aestheticfunction/dspack-emit": "^0.7.0",
         "@anthropic-ai/sdk": "^0.109.1",
         "ajv": "^8.17.1",
         "ajv-formats": "^3.0.1",
diff --git a/package.json b/package.json
index dcd5978..32e9f97 100644
--- a/package.json
+++ b/package.json
@@ -63,7 +63,7 @@
     "zod": "^3.25 || ^4.0"
   },
   "devDependencies": {
-    "@aestheticfunction/dspack-gen": "git+https://github.com/aestheticfunction/dspack-gen.git#c5bfd6de979f811466c6ba1e1c0f978defc4236f",
+    "@aestheticfunction/dspack-gen": "git+https://github.com/aestheticfunction/dspack-gen.git#5203569cb8d066ad545307500c2ae3f2adaa0239",
     "@types/minimist": "^1.2.5",
     "esbuild": "^0.25.0",
     "@types/node": "^20.0.0",
diff --git a/scripts/check-sync.mjs b/scripts/check-sync.mjs
index 779ade6..391bb29 100644
--- a/scripts/check-sync.mjs
+++ b/scripts/check-sync.mjs
@@ -3,7 +3,8 @@
  * Copy drift check (dspack-gen#7, ecosystem-wide).
  *
  * ds-mcp deliberately carries byte copies of shared artifacts: the shadcn
- * v0.4 contract (source of truth: the dspack spec repo) and the F1 lint
+ * v0.4 contract and the four dspack JSON Schemas the loader validates
+ * against (source of truth: the dspack spec repo) and the F1 lint
  * goldens (source of truth: dspack-gen — the goldens pin validate-ui's
  * semantics to the pinned dependency's linter, on purpose). The price of
  * copies is silent drift; this script makes drift loud: every entry must
@@ -22,6 +23,17 @@ const MANIFEST = [
       "https://raw.githubusercontent.com/aestheticfunction/dspack/main/examples/shadcn-ui.dspack.json",
     note: "the v0.4 example contract — copy of the spec repo's source of truth",
   },
+  // The loader compiles these four schemas with ajv and rejects any dspack
+  // file that fails validation, so a stale copy is not cosmetic: it makes
+  // ds-mcp refuse contracts the spec considers valid. v0.1–v0.3 are frozen
+  // and should never move; v0.4 is amendable (§4.3 added requiredCategories
+  // to required-composition after this copy was first taken, which is
+  // exactly the silent drift these entries now catch).
+  ...["0.1", "0.2", "0.3", "0.4"].map((v) => ({
+    local: `src/schema/dspack.v${v}.schema.json`,
+    source: `https://raw.githubusercontent.com/aestheticfunction/dspack/main/schema/dspack.v${v}.schema.json`,
+    note: `the v${v} dspack JSON Schema — copy of the spec repo's source of truth`,
+  })),
   {
     local: "src/tests/fixtures/F1-dialog-for-delete.dsurface.json",
     source:
@@ -40,6 +52,19 @@ const MANIFEST = [
       "https://raw.githubusercontent.com/aestheticfunction/dspack-gen/main/fixtures/golden/context/shadcn.destructive-action.json",
     note: "golden generation context — pins get-generation-context's served output to dspack-gen's compiler",
   },
+  {
+    // The golden context above is compiled FROM this contract, so the two
+    // are only meaningful as a pair. They used to be implicitly paired via
+    // examples/shadcn-ui-v04.dspack.json, which held byte-identical content;
+    // that stopped being true when the spec repo's example advanced to 3.2.0
+    // while dspack-gen's fixture stayed at 2.3.0. Tracking the compiler's
+    // own input explicitly keeps the golden test a test of compiler
+    // semantics rather than of whichever contract ds-mcp happens to ship.
+    local: "src/tests/fixtures/shadcn.v0_4.contract.json",
+    source:
+      "https://raw.githubusercontent.com/aestheticfunction/dspack-gen/main/fixtures/shadcn.v0_4.dspack.json",
+    note: "the contract dspack-gen compiled the golden context from — the golden's other half",
+  },
 ];
 
 const write = process.argv.includes("--write");
diff --git a/src/schema/dspack.v0.4.schema.json b/src/schema/dspack.v0.4.schema.json
index e288828..9840c9e 100644
--- a/src/schema/dspack.v0.4.schema.json
+++ b/src/schema/dspack.v0.4.schema.json
@@ -1,1554 +1,1586 @@
 {
-  "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://github.com/aestheticfunction/dspack/blob/main/schema/dspack.v0.4.schema.json",
-  "title": "dspack v0.4",
-  "description": "Schema for dspack v0.4 — a JSON format for representing design system corpora. Backward-compatible with v0.1–v0.3 documents; adds component categories (a contract-defined category registry referenced by component metadata and rules) and the required-props rule type.",
-  "type": "object",
-  "required": [
-    "dspack",
-    "name"
-  ],
-  "properties": {
-    "$schema": {
-      "type": "string",
-      "description": "URI reference to this JSON Schema. Optional; consumers MUST NOT require this property."
+ "$schema": "https://json-schema.org/draft/2020-12/schema",
+ "$id": "https://github.com/aestheticfunction/dspack/blob/main/schema/dspack.v0.4.schema.json",
+ "title": "dspack v0.4",
+ "description": "Schema for dspack v0.4 \u2014 a JSON format for representing design system corpora. Backward-compatible with v0.1\u2013v0.3 documents; adds component categories (a contract-defined category registry referenced by component metadata and rules) and the required-props rule type.",
+ "type": "object",
+ "required": [
+  "dspack",
+  "name"
+ ],
+ "properties": {
+  "$schema": {
+   "type": "string",
+   "description": "URI reference to this JSON Schema. Optional; consumers MUST NOT require this property."
+  },
+  "dspack": {
+   "type": "string",
+   "const": "0.4",
+   "description": "Specification version. MUST be \"0.4\" for documents conforming to this version."
+  },
+  "name": {
+   "type": "string",
+   "minLength": 1,
+   "description": "Human-readable name of the design system."
+  },
+  "description": {
+   "type": "string",
+   "description": "Brief description of the design system's purpose and scope."
+  },
+  "version": {
+   "type": "string",
+   "description": "Version of the design system content (not the spec version)."
+  },
+  "metadata": {
+   "$ref": "#/$defs/metadata"
+  },
+  "tokens": {
+   "type": "object",
+   "description": "Token definitions organized by category.",
+   "propertyNames": {
+    "pattern": "^[a-z][a-z0-9-]*$"
+   },
+   "additionalProperties": {
+    "$ref": "#/$defs/tokenCategory"
+   }
+  },
+  "components": {
+   "type": "object",
+   "description": "Component definitions keyed by component ID.",
+   "propertyNames": {
+    "pattern": "^[a-z][a-z0-9-]*$"
+   },
+   "additionalProperties": {
+    "$ref": "#/$defs/componentEntry"
+   }
+  },
+  "categories": {
+   "type": "object",
+   "description": "Contract-defined component category registry. Categories are the contract's own taxonomy (dspack bakes none in); component/sub-component metadata and category-based rule fields reference these ids. Referenced ids MUST be registered here.",
+   "propertyNames": {
+    "pattern": "^[a-z][a-z0-9-]*$"
+   },
+   "additionalProperties": {
+    "$ref": "#/$defs/categoryEntry"
+   }
+  },
+  "patterns": {
+   "type": "array",
+   "description": "Pattern entries describing preferred ways of combining components.",
+   "items": {
+    "$ref": "#/$defs/patternEntry"
+   }
+  },
+  "antiPatterns": {
+   "type": "array",
+   "description": "Anti-pattern entries describing approaches that are deliberately ruled out.",
+   "items": {
+    "$ref": "#/$defs/antiPatternEntry"
+   }
+  },
+  "intents": {
+   "type": "array",
+   "description": "Named generation intents \u2014 the vocabulary that scopes governance rules and examples. Referenced by rules[].appliesTo.intents and examples[].intent, and declared by callers when requesting generation.",
+   "items": {
+    "$ref": "#/$defs/intentEntry"
+   }
+  },
+  "rules": {
+   "type": "array",
+   "description": "Machine-checkable governance rules, evaluated deterministically over dspack surface documents. Each rule is a typed, structured predicate plus a human-readable rationale. Evaluation semantics per type are normative in the v0.3 specification (the three original types) and the v0.4 specification (required-props, forbiddenCategories).",
+   "items": {
+    "$ref": "#/$defs/ruleEntry"
+   }
+  },
+  "examples": {
+   "type": "array",
+   "description": "Compilable example surfaces tied to named intents. Examples serve double duty as documentation and few-shot exemplars; each surface must validate against the dspack surface schema and the contract vocabulary.",
+   "items": {
+    "$ref": "#/$defs/exampleEntry"
+   }
+  },
+  "frameworkBindings": {
+   "type": "object",
+   "description": "Framework-specific information keyed by framework identifier.",
+   "propertyNames": {
+    "pattern": "^[a-z][a-z0-9-]*$"
+   },
+   "additionalProperties": {
+    "$ref": "#/$defs/frameworkBinding"
+   }
+  },
+  "themes": {
+   "type": "object",
+   "description": "Named sets of token overrides representing alternative visual modes.",
+   "propertyNames": {
+    "pattern": "^[a-z][a-z0-9-]*$"
+   },
+   "additionalProperties": {
+    "$ref": "#/$defs/themeEntry"
+   }
+  },
+  "layout": {
+   "$ref": "#/$defs/layoutPrimitives"
+  }
+ },
+ "additionalProperties": true,
+ "$defs": {
+  "metadata": {
+   "type": "object",
+   "description": "Extensible metadata about the dspack file.",
+   "properties": {
+    "generatedBy": {
+     "type": "string",
+     "description": "Tool or process that created this file."
     },
-    "dspack": {
-      "type": "string",
-      "const": "0.4",
-      "description": "Specification version. MUST be \"0.4\" for documents conforming to this version."
+    "generatedAt": {
+     "type": "string",
+     "format": "date-time",
+     "description": "ISO 8601 datetime when the file was generated."
     },
-    "name": {
-      "type": "string",
-      "minLength": 1,
-      "description": "Human-readable name of the design system."
+    "source": {
+     "type": "string",
+     "description": "URL or description of the upstream source."
     },
+    "license": {
+     "type": "string",
+     "description": "SPDX license identifier or freeform description."
+    }
+   },
+   "additionalProperties": true
+  },
+  "tokenCategory": {
+   "type": "object",
+   "description": "A category of tokens.",
+   "required": [
+    "values"
+   ],
+   "properties": {
     "description": {
-      "type": "string",
-      "description": "Brief description of the design system's purpose and scope."
+     "type": "string",
+     "description": "What this category covers."
     },
-    "version": {
-      "type": "string",
-      "description": "Version of the design system content (not the spec version)."
+    "tier": {
+     "type": "string",
+     "enum": [
+      "primitive",
+      "semantic",
+      "component"
+     ],
+     "description": "Default abstraction level for tokens in this category."
     },
-    "metadata": {
-      "$ref": "#/$defs/metadata"
+    "values": {
+     "type": "object",
+     "description": "Map of token name to token entry.",
+     "propertyNames": {
+      "pattern": "^[a-z][a-z0-9-]*$"
+     },
+     "additionalProperties": {
+      "$ref": "#/$defs/tokenEntry"
+     }
+    }
+   },
+   "additionalProperties": true
+  },
+  "tokenEntry": {
+   "type": "object",
+   "description": "A single token definition.",
+   "required": [
+    "value"
+   ],
+   "properties": {
+    "value": {
+     "type": "string",
+     "description": "The resolved value of the token."
     },
-    "tokens": {
-      "type": "object",
-      "description": "Token definitions organized by category.",
-      "propertyNames": {
-        "pattern": "^[a-z][a-z0-9-]*$"
-      },
-      "additionalProperties": {
-        "$ref": "#/$defs/tokenCategory"
-      }
+    "description": {
+     "type": "string",
+     "description": "Semantic meaning of the token."
     },
-    "components": {
-      "type": "object",
-      "description": "Component definitions keyed by component ID.",
-      "propertyNames": {
-        "pattern": "^[a-z][a-z0-9-]*$"
+    "type": {
+     "type": "string",
+     "description": "The value type (e.g., color, dimension, fontFamily)."
+    },
+    "deprecated": {
+     "type": "boolean",
+     "description": "Whether this token is deprecated.",
+     "default": false
+    },
+    "aliases": {
+     "type": "array",
+     "items": {
+      "type": "string"
+     },
+     "description": "Other names by which this token is known."
+    },
+    "status": {
+     "oneOf": [
+      {
+       "type": "string",
+       "enum": [
+        "draft",
+        "experimental",
+        "stable",
+        "deprecated"
+       ]
       },
-      "additionalProperties": {
-        "$ref": "#/$defs/componentEntry"
+      {
+       "$ref": "#/$defs/statusObject"
       }
+     ],
+     "description": "Lifecycle stage. String for uniform status, object for per-platform granularity."
     },
-    "categories": {
-      "type": "object",
-      "description": "Contract-defined component category registry. Categories are the contract's own taxonomy (dspack bakes none in); component/sub-component metadata and category-based rule fields reference these ids. Referenced ids MUST be registered here.",
-      "propertyNames": {
-        "pattern": "^[a-z][a-z0-9-]*$"
+    "aliasOf": {
+     "oneOf": [
+      {
+       "type": "string",
+       "description": "Token name that this token aliases."
       },
-      "additionalProperties": {
-        "$ref": "#/$defs/categoryEntry"
+      {
+       "$ref": "#/$defs/aliasReference"
       }
+     ],
+     "description": "Token that this token aliases. String for unambiguous names, object for cross-category disambiguation."
     },
-    "patterns": {
-      "type": "array",
-      "description": "Pattern entries describing preferred ways of combining components.",
-      "items": {
-        "$ref": "#/$defs/patternEntry"
-      }
+    "tier": {
+     "type": "string",
+     "enum": [
+      "primitive",
+      "semantic",
+      "component"
+     ],
+     "description": "Abstraction level of this token, overriding the category default."
+    }
+   },
+   "additionalProperties": true
+  },
+  "statusObject": {
+   "type": "object",
+   "description": "Lifecycle status with per-platform granularity.",
+   "required": [
+    "default"
+   ],
+   "properties": {
+    "default": {
+     "type": "string",
+     "enum": [
+      "draft",
+      "experimental",
+      "stable",
+      "deprecated"
+     ],
+     "description": "Default lifecycle stage when no platform-specific override applies."
     },
-    "antiPatterns": {
-      "type": "array",
-      "description": "Anti-pattern entries describing approaches that are deliberately ruled out.",
-      "items": {
-        "$ref": "#/$defs/antiPatternEntry"
-      }
+    "platforms": {
+     "type": "object",
+     "description": "Map of platform/framework ID to platform status object.",
+     "propertyNames": {
+      "pattern": "^[a-z][a-z0-9-]*$"
+     },
+     "additionalProperties": {
+      "$ref": "#/$defs/platformStatus"
+     }
+    }
+   },
+   "additionalProperties": true
+  },
+  "platformStatus": {
+   "type": "object",
+   "description": "Lifecycle status for a specific platform.",
+   "required": [
+    "stage"
+   ],
+   "properties": {
+    "stage": {
+     "type": "string",
+     "enum": [
+      "draft",
+      "experimental",
+      "stable",
+      "deprecated"
+     ],
+     "description": "Lifecycle stage for this platform."
     },
-    "intents": {
-      "type": "array",
-      "description": "Named generation intents — the vocabulary that scopes governance rules and examples. Referenced by rules[].appliesTo.intents and examples[].intent, and declared by callers when requesting generation.",
-      "items": {
-        "$ref": "#/$defs/intentEntry"
-      }
+    "since": {
+     "type": "string",
+     "description": "Version of the design system content at which this stage took effect."
     },
-    "rules": {
-      "type": "array",
-      "description": "Machine-checkable governance rules, evaluated deterministically over dspack surface documents. Each rule is a typed, structured predicate plus a human-readable rationale. Evaluation semantics per type are normative in the v0.3 specification (the three original types) and the v0.4 specification (required-props, forbiddenCategories).",
-      "items": {
-        "$ref": "#/$defs/ruleEntry"
-      }
+    "migrateTo": {
+     "type": "string",
+     "description": "Component ID or token name of the recommended replacement."
     },
-    "examples": {
-      "type": "array",
-      "description": "Compilable example surfaces tied to named intents. Examples serve double duty as documentation and few-shot exemplars; each surface must validate against the dspack surface schema and the contract vocabulary.",
-      "items": {
-        "$ref": "#/$defs/exampleEntry"
-      }
+    "note": {
+     "type": "string",
+     "description": "Prose migration guidance or context for this platform's status."
+    }
+   },
+   "additionalProperties": true
+  },
+  "aliasReference": {
+   "type": "object",
+   "description": "Structured token alias reference for cross-category disambiguation.",
+   "required": [
+    "category",
+    "token"
+   ],
+   "properties": {
+    "category": {
+     "type": "string",
+     "description": "Token category name containing the referenced token."
     },
-    "frameworkBindings": {
-      "type": "object",
-      "description": "Framework-specific information keyed by framework identifier.",
-      "propertyNames": {
-        "pattern": "^[a-z][a-z0-9-]*$"
-      },
-      "additionalProperties": {
-        "$ref": "#/$defs/frameworkBinding"
-      }
+    "token": {
+     "type": "string",
+     "description": "Token name within that category."
+    }
+   },
+   "additionalProperties": true
+  },
+  "componentEntry": {
+   "type": "object",
+   "description": "A component definition.",
+   "required": [
+    "name",
+    "description"
+   ],
+   "properties": {
+    "name": {
+     "type": "string",
+     "minLength": 1,
+     "description": "Human-readable display name."
+    },
+    "description": {
+     "type": "string",
+     "description": "What the component is for."
     },
-    "themes": {
-      "type": "object",
-      "description": "Named sets of token overrides representing alternative visual modes.",
-      "propertyNames": {
-        "pattern": "^[a-z][a-z0-9-]*$"
+    "whenToUse": {
+     "type": "string",
+     "description": "Guidance on when to use this component."
+    },
+    "whenNotToUse": {
+     "type": "string",
+     "description": "Guidance on when to choose a different component."
+    },
+    "props": {
+     "type": "object",
+     "description": "Map of prop name to prop descriptor.",
+     "additionalProperties": {
+      "$ref": "#/$defs/propDescriptor"
+     }
+    },
+    "tokens": {
+     "type": "array",
+     "items": {
+      "type": "string"
+     },
+     "description": "Token names this component depends on."
+    },
+    "relatedComponents": {
+     "type": "array",
+     "items": {
+      "type": "string"
+     },
+     "description": "Component IDs of related components."
+    },
+    "tags": {
+     "type": "array",
+     "items": {
+      "type": "string"
+     },
+     "description": "Freeform classification tags."
+    },
+    "deprecated": {
+     "type": "boolean",
+     "description": "Whether this component is deprecated.",
+     "default": false
+    },
+    "deprecatedMessage": {
+     "type": "string",
+     "description": "What to use instead of this component."
+    },
+    "status": {
+     "oneOf": [
+      {
+       "type": "string",
+       "enum": [
+        "draft",
+        "experimental",
+        "stable",
+        "deprecated"
+       ]
       },
-      "additionalProperties": {
-        "$ref": "#/$defs/themeEntry"
+      {
+       "$ref": "#/$defs/statusObject"
       }
+     ],
+     "description": "Lifecycle stage. String for uniform status, object for per-platform granularity."
+    },
+    "accessibility": {
+     "$ref": "#/$defs/accessibilityConstraints"
+    },
+    "composition": {
+     "$ref": "#/$defs/compositionRules"
     },
-    "layout": {
-      "$ref": "#/$defs/layoutPrimitives"
+    "constraints": {
+     "type": "array",
+     "description": "Structured usage constraints.",
+     "items": {
+      "$ref": "#/$defs/constraintEntry"
+     }
+    },
+    "categories": {
+     "type": "array",
+     "description": "Category ids this entry belongs to; each MUST be registered in the top-level categories registry.",
+     "items": {
+      "type": "string"
+     },
+     "minItems": 1
     }
+   },
+   "additionalProperties": true
   },
-  "additionalProperties": true,
-  "$defs": {
-    "metadata": {
-      "type": "object",
-      "description": "Extensible metadata about the dspack file.",
-      "properties": {
-        "generatedBy": {
-          "type": "string",
-          "description": "Tool or process that created this file."
-        },
-        "generatedAt": {
-          "type": "string",
-          "format": "date-time",
-          "description": "ISO 8601 datetime when the file was generated."
-        },
-        "source": {
-          "type": "string",
-          "description": "URL or description of the upstream source."
-        },
-        "license": {
-          "type": "string",
-          "description": "SPDX license identifier or freeform description."
-        }
-      },
-      "additionalProperties": true
+  "propDescriptor": {
+   "type": "object",
+   "description": "Describes a single component prop.",
+   "required": [
+    "type"
+   ],
+   "properties": {
+    "type": {
+     "type": "string",
+     "description": "The value type of the prop (e.g., string, number, boolean, enum)."
     },
-    "tokenCategory": {
-      "type": "object",
-      "description": "A category of tokens.",
-      "required": [
-        "values"
-      ],
-      "properties": {
-        "description": {
-          "type": "string",
-          "description": "What this category covers."
-        },
-        "tier": {
-          "type": "string",
-          "enum": [
-            "primitive",
-            "semantic",
-            "component"
-          ],
-          "description": "Default abstraction level for tokens in this category."
-        },
-        "values": {
-          "type": "object",
-          "description": "Map of token name to token entry.",
-          "propertyNames": {
-            "pattern": "^[a-z][a-z0-9-]*$"
-          },
-          "additionalProperties": {
-            "$ref": "#/$defs/tokenEntry"
-          }
-        }
-      },
-      "additionalProperties": true
+    "description": {
+     "type": "string",
+     "description": "What this prop controls."
     },
-    "tokenEntry": {
-      "type": "object",
-      "description": "A single token definition.",
-      "required": [
-        "value"
-      ],
-      "properties": {
-        "value": {
-          "type": "string",
-          "description": "The resolved value of the token."
-        },
-        "description": {
-          "type": "string",
-          "description": "Semantic meaning of the token."
-        },
-        "type": {
-          "type": "string",
-          "description": "The value type (e.g., color, dimension, fontFamily)."
-        },
-        "deprecated": {
-          "type": "boolean",
-          "description": "Whether this token is deprecated.",
-          "default": false
-        },
-        "aliases": {
-          "type": "array",
-          "items": {
-            "type": "string"
-          },
-          "description": "Other names by which this token is known."
-        },
-        "status": {
-          "oneOf": [
-            {
-              "type": "string",
-              "enum": [
-                "draft",
-                "experimental",
-                "stable",
-                "deprecated"
-              ]
-            },
-            {
-              "$ref": "#/$defs/statusObject"
-            }
-          ],
-          "description": "Lifecycle stage. String for uniform status, object for per-platform granularity."
-        },
-        "aliasOf": {
-          "oneOf": [
-            {
-              "type": "string",
-              "description": "Token name that this token aliases."
-            },
-            {
-              "$ref": "#/$defs/aliasReference"
-            }
-          ],
-          "description": "Token that this token aliases. String for unambiguous names, object for cross-category disambiguation."
-        },
-        "tier": {
-          "type": "string",
-          "enum": [
-            "primitive",
-            "semantic",
-            "component"
-          ],
-          "description": "Abstraction level of this token, overriding the category default."
-        }
-      },
-      "additionalProperties": true
+    "values": {
+     "type": "array",
+     "description": "For enum type, the allowed values. Items may be bare values or value descriptor objects.",
+     "items": {
+      "oneOf": [
+       {
+        "type": "string"
+       },
+       {
+        "type": "number"
+       },
+       {
+        "type": "boolean"
+       },
+       {
+        "$ref": "#/$defs/valueDescriptor"
+       }
+      ]
+     }
     },
-    "statusObject": {
-      "type": "object",
-      "description": "Lifecycle status with per-platform granularity.",
-      "required": [
-        "default"
-      ],
-      "properties": {
-        "default": {
-          "type": "string",
-          "enum": [
-            "draft",
-            "experimental",
-            "stable",
-            "deprecated"
-          ],
-          "description": "Default lifecycle stage when no platform-specific override applies."
-        },
-        "platforms": {
-          "type": "object",
-          "description": "Map of platform/framework ID to platform status object.",
-          "propertyNames": {
-            "pattern": "^[a-z][a-z0-9-]*$"
-          },
-          "additionalProperties": {
-            "$ref": "#/$defs/platformStatus"
-          }
-        }
-      },
-      "additionalProperties": true
+    "default": {
+     "description": "Default value of the prop."
     },
-    "platformStatus": {
-      "type": "object",
-      "description": "Lifecycle status for a specific platform.",
-      "required": [
-        "stage"
-      ],
-      "properties": {
-        "stage": {
-          "type": "string",
-          "enum": [
-            "draft",
-            "experimental",
-            "stable",
-            "deprecated"
-          ],
-          "description": "Lifecycle stage for this platform."
-        },
-        "since": {
-          "type": "string",
-          "description": "Version of the design system content at which this stage took effect."
-        },
-        "migrateTo": {
-          "type": "string",
-          "description": "Component ID or token name of the recommended replacement."
-        },
-        "note": {
-          "type": "string",
-          "description": "Prose migration guidance or context for this platform's status."
-        }
-      },
-      "additionalProperties": true
+    "required": {
+     "type": "boolean",
+     "description": "Whether this prop must be provided.",
+     "default": false
     },
-    "aliasReference": {
-      "type": "object",
-      "description": "Structured token alias reference for cross-category disambiguation.",
-      "required": [
-        "category",
-        "token"
-      ],
-      "properties": {
-        "category": {
-          "type": "string",
-          "description": "Token category name containing the referenced token."
-        },
-        "token": {
-          "type": "string",
-          "description": "Token name within that category."
-        }
-      },
-      "additionalProperties": true
+    "propRole": {
+     "type": "string",
+     "enum": [
+      "flag",
+      "dimension",
+      "choice",
+      "slot",
+      "handler",
+      "content",
+      "state"
+     ],
+     "description": "Semantic role of this prop."
+    }
+   },
+   "additionalProperties": true
+  },
+  "valueDescriptor": {
+   "type": "object",
+   "description": "Describes a single allowed value for an enum prop.",
+   "required": [
+    "value"
+   ],
+   "properties": {
+    "value": {
+     "description": "The actual enum value."
     },
-    "componentEntry": {
-      "type": "object",
-      "description": "A component definition.",
-      "required": [
-        "name",
-        "description"
-      ],
-      "properties": {
-        "name": {
-          "type": "string",
-          "minLength": 1,
-          "description": "Human-readable display name."
-        },
-        "description": {
-          "type": "string",
-          "description": "What the component is for."
-        },
-        "whenToUse": {
-          "type": "string",
-          "description": "Guidance on when to use this component."
-        },
-        "whenNotToUse": {
-          "type": "string",
-          "description": "Guidance on when to choose a different component."
-        },
-        "props": {
-          "type": "object",
-          "description": "Map of prop name to prop descriptor.",
-          "additionalProperties": {
-            "$ref": "#/$defs/propDescriptor"
-          }
-        },
-        "tokens": {
-          "type": "array",
-          "items": {
-            "type": "string"
-          },
-          "description": "Token names this component depends on."
-        },
-        "relatedComponents": {
-          "type": "array",
-          "items": {
-            "type": "string"
-          },
-          "description": "Component IDs of related components."
-        },
-        "tags": {
-          "type": "array",
-          "items": {
-            "type": "string"
-          },
-          "description": "Freeform classification tags."
-        },
-        "deprecated": {
-          "type": "boolean",
-          "description": "Whether this component is deprecated.",
-          "default": false
-        },
-        "deprecatedMessage": {
-          "type": "string",
-          "description": "What to use instead of this component."
-        },
-        "status": {
-          "oneOf": [
-            {
-              "type": "string",
-              "enum": [
-                "draft",
-                "experimental",
-                "stable",
-                "deprecated"
-              ]
-            },
-            {
-              "$ref": "#/$defs/statusObject"
-            }
-          ],
-          "description": "Lifecycle stage. String for uniform status, object for per-platform granularity."
-        },
-        "accessibility": {
-          "$ref": "#/$defs/accessibilityConstraints"
-        },
-        "composition": {
-          "$ref": "#/$defs/compositionRules"
-        },
-        "constraints": {
-          "type": "array",
-          "description": "Structured usage constraints.",
-          "items": {
-            "$ref": "#/$defs/constraintEntry"
-          }
-        },
-        "categories": {
-          "type": "array",
-          "description": "Category ids this entry belongs to; each MUST be registered in the top-level categories registry.",
-          "items": {
-            "type": "string"
-          },
-          "minItems": 1
-        }
-      },
-      "additionalProperties": true
+    "description": {
+     "type": "string",
+     "description": "When to choose this value."
     },
-    "propDescriptor": {
-      "type": "object",
-      "description": "Describes a single component prop.",
-      "required": [
-        "type"
-      ],
-      "properties": {
-        "type": {
-          "type": "string",
-          "description": "The value type of the prop (e.g., string, number, boolean, enum)."
-        },
-        "description": {
-          "type": "string",
-          "description": "What this prop controls."
-        },
-        "values": {
-          "type": "array",
-          "description": "For enum type, the allowed values. Items may be bare values or value descriptor objects.",
-          "items": {
-            "oneOf": [
-              {
-                "type": "string"
-              },
-              {
-                "type": "number"
-              },
-              {
-                "type": "boolean"
-              },
-              {
-                "$ref": "#/$defs/valueDescriptor"
-              }
-            ]
-          }
-        },
-        "default": {
-          "description": "Default value of the prop."
-        },
-        "required": {
-          "type": "boolean",
-          "description": "Whether this prop must be provided.",
-          "default": false
-        },
-        "propRole": {
-          "type": "string",
-          "enum": [
-            "flag",
-            "dimension",
-            "choice",
-            "slot",
-            "handler",
-            "content",
-            "state"
-          ],
-          "description": "Semantic role of this prop."
-        }
-      },
-      "additionalProperties": true
+    "deprecated": {
+     "type": "boolean",
+     "description": "Whether this specific value is deprecated.",
+     "default": false
+    }
+   },
+   "additionalProperties": true
+  },
+  "accessibilityConstraints": {
+   "type": "object",
+   "description": "Accessibility constraints and expectations for a component.",
+   "properties": {
+    "role": {
+     "type": "string",
+     "description": "WAI-ARIA role this component fulfills."
     },
-    "valueDescriptor": {
-      "type": "object",
-      "description": "Describes a single allowed value for an enum prop.",
-      "required": [
-        "value"
-      ],
-      "properties": {
-        "value": {
-          "description": "The actual enum value."
-        },
-        "description": {
-          "type": "string",
-          "description": "When to choose this value."
-        },
-        "deprecated": {
-          "type": "boolean",
-          "description": "Whether this specific value is deprecated.",
-          "default": false
-        }
-      },
-      "additionalProperties": true
+    "requiredAttributes": {
+     "type": "array",
+     "description": "HTML or ARIA attributes that must be present for correct accessible usage.",
+     "items": {
+      "$ref": "#/$defs/attributeDescriptor"
+     }
     },
-    "accessibilityConstraints": {
-      "type": "object",
-      "description": "Accessibility constraints and expectations for a component.",
-      "properties": {
-        "role": {
-          "type": "string",
-          "description": "WAI-ARIA role this component fulfills."
-        },
-        "requiredAttributes": {
-          "type": "array",
-          "description": "HTML or ARIA attributes that must be present for correct accessible usage.",
-          "items": {
-            "$ref": "#/$defs/attributeDescriptor"
-          }
-        },
-        "keyboardInteractions": {
-          "type": "array",
-          "description": "Expected keyboard behaviors.",
-          "items": {
-            "$ref": "#/$defs/keyboardInteraction"
-          }
-        },
-        "contrastRequirement": {
-          "type": "string",
-          "description": "Minimum contrast ratio or WCAG level."
-        },
-        "focusManagement": {
-          "type": "string",
-          "description": "Prose description of focus behavior expectations."
-        },
-        "labelRequirement": {
-          "type": "string",
-          "enum": [
-            "required-visible",
-            "required-accessible-name",
-            "required-aria",
-            "optional",
-            "none"
-          ],
-          "description": "How the component must be labeled."
-        },
-        "notes": {
-          "type": "string",
-          "description": "Additional accessibility guidance in prose."
-        }
-      },
-      "additionalProperties": true
+    "keyboardInteractions": {
+     "type": "array",
+     "description": "Expected keyboard behaviors.",
+     "items": {
+      "$ref": "#/$defs/keyboardInteraction"
+     }
     },
-    "attributeDescriptor": {
-      "type": "object",
-      "description": "Describes a required HTML or ARIA attribute for accessible usage.",
-      "required": [
-        "attribute"
-      ],
-      "properties": {
-        "attribute": {
-          "type": "string",
-          "description": "The attribute name (e.g., aria-label, aria-describedby, id, type)."
-        },
-        "description": {
-          "type": "string",
-          "description": "When and how to provide this attribute."
-        },
-        "condition": {
-          "type": "string",
-          "description": "Condition under which this attribute is required."
-        }
-      },
-      "additionalProperties": true
+    "contrastRequirement": {
+     "type": "string",
+     "description": "Minimum contrast ratio or WCAG level."
     },
-    "keyboardInteraction": {
-      "type": "object",
-      "description": "Describes an expected keyboard behavior.",
-      "required": [
-        "key",
-        "description"
-      ],
-      "properties": {
-        "key": {
-          "type": "string",
-          "description": "The key or key combination."
-        },
-        "description": {
-          "type": "string",
-          "description": "What this key does in the context of this component."
-        }
-      },
-      "additionalProperties": true
+    "focusManagement": {
+     "type": "string",
+     "description": "Prose description of focus behavior expectations."
     },
-    "compositionRules": {
-      "type": "object",
-      "description": "Rules governing how a component composes with other components.",
-      "properties": {
-        "subComponents": {
-          "type": "array",
-          "description": "Sub-components that belong to this compound component.",
-          "items": {
-            "$ref": "#/$defs/subComponentDescriptor"
-          }
-        },
-        "requiredChildren": {
-          "type": "array",
-          "items": {
-            "type": "string"
-          },
-          "description": "Component IDs or sub-component IDs that must appear as descendants."
-        },
-        "allowedChildren": {
-          "type": "array",
-          "items": {
-            "type": "string"
-          },
-          "description": "Component IDs or sub-component IDs that may appear as direct children."
-        },
-        "requiredParent": {
-          "type": "string",
-          "description": "Component ID or sub-component ID that must be an ancestor."
-        },
-        "allowedParents": {
-          "type": "array",
-          "items": {
-            "type": "string"
-          },
-          "description": "Component IDs or sub-component IDs that may be the parent."
-        },
-        "requiredSiblings": {
-          "type": "array",
-          "items": {
-            "type": "string"
-          },
-          "description": "Component IDs or sub-component IDs that must also be present among siblings."
-        },
-        "notes": {
-          "type": "string",
-          "description": "Prose description of composition constraints not captured by structured fields."
-        }
-      },
-      "additionalProperties": true
+    "labelRequirement": {
+     "type": "string",
+     "enum": [
+      "required-visible",
+      "required-accessible-name",
+      "required-aria",
+      "optional",
+      "none"
+     ],
+     "description": "How the component must be labeled."
     },
-    "subComponentDescriptor": {
-      "type": "object",
-      "description": "Describes a sub-component of a compound component.",
-      "required": [
-        "id",
-        "name"
-      ],
-      "properties": {
-        "id": {
-          "type": "string",
-          "pattern": "^[a-z][a-z0-9-]*$",
-          "description": "Identifier for the sub-component. Should be parent-prefixed."
-        },
-        "name": {
-          "type": "string",
-          "minLength": 1,
-          "description": "Human-readable display name."
-        },
-        "description": {
-          "type": "string",
-          "description": "What this sub-component is for."
-        },
-        "required": {
-          "type": "boolean",
-          "description": "Whether this sub-component must be present when the parent is used.",
-          "default": false
-        },
-        "slot": {
-          "type": "string",
-          "description": "Named slot this sub-component fills."
-        },
-        "acceptsChildren": {
-          "type": "string",
-          "enum": [
-            "any",
-            "text",
-            "components",
-            "none"
-          ],
-          "description": "What this sub-component expects as children."
-        },
-        "categories": {
-          "type": "array",
-          "description": "Category ids this entry belongs to; each MUST be registered in the top-level categories registry.",
-          "items": {
-            "type": "string"
-          },
-          "minItems": 1
-        }
-      },
-      "additionalProperties": true
+    "notes": {
+     "type": "string",
+     "description": "Additional accessibility guidance in prose."
+    }
+   },
+   "additionalProperties": true
+  },
+  "attributeDescriptor": {
+   "type": "object",
+   "description": "Describes a required HTML or ARIA attribute for accessible usage.",
+   "required": [
+    "attribute"
+   ],
+   "properties": {
+    "attribute": {
+     "type": "string",
+     "description": "The attribute name (e.g., aria-label, aria-describedby, id, type)."
     },
-    "constraintEntry": {
-      "type": "object",
-      "description": "A structured usage constraint.",
-      "required": [
-        "context",
-        "rule",
-        "severity"
-      ],
-      "properties": {
-        "context": {
-          "type": "string",
-          "description": "The situation or condition this constraint applies to."
-        },
-        "rule": {
-          "type": "string",
-          "description": "What to do or not do."
-        },
-        "severity": {
-          "type": "string",
-          "enum": [
-            "must",
-            "should",
-            "should-not",
-            "must-not"
-          ],
-          "description": "RFC 2119 strength of the constraint."
-        }
-      },
-      "additionalProperties": true
+    "description": {
+     "type": "string",
+     "description": "When and how to provide this attribute."
     },
-    "patternEntry": {
-      "type": "object",
-      "description": "A pattern describing a preferred way of combining components.",
-      "required": [
-        "id",
-        "name",
-        "description"
-      ],
-      "properties": {
-        "id": {
-          "type": "string",
-          "pattern": "^[a-z][a-z0-9-]*$",
-          "description": "Unique identifier for this pattern."
-        },
-        "name": {
-          "type": "string",
-          "minLength": 1,
-          "description": "Human-readable name."
-        },
-        "description": {
-          "type": "string",
-          "description": "What problem this pattern addresses."
-        },
-        "intent": {
-          "type": "string",
-          "description": "The underlying design goal or UX objective."
-        },
-        "context": {
-          "type": "string",
-          "description": "When this pattern applies."
-        },
-        "components": {
-          "type": "array",
-          "items": {
-            "type": "string"
-          },
-          "description": "Component IDs involved in this pattern."
-        },
-        "guidance": {
-          "type": "string",
-          "description": "Prose guidance on how to apply the pattern correctly."
-        },
-        "relatedPatterns": {
-          "type": "array",
-          "items": {
-            "type": "string"
-          },
-          "description": "Pattern IDs of related patterns."
-        },
-        "tags": {
-          "type": "array",
-          "items": {
-            "type": "string"
-          },
-          "description": "Freeform classification tags."
-        }
-      },
-      "additionalProperties": true
+    "condition": {
+     "type": "string",
+     "description": "Condition under which this attribute is required."
+    }
+   },
+   "additionalProperties": true
+  },
+  "keyboardInteraction": {
+   "type": "object",
+   "description": "Describes an expected keyboard behavior.",
+   "required": [
+    "key",
+    "description"
+   ],
+   "properties": {
+    "key": {
+     "type": "string",
+     "description": "The key or key combination."
     },
-    "antiPatternEntry": {
-      "type": "object",
-      "description": "An anti-pattern describing an approach that is deliberately ruled out.",
-      "required": [
-        "id",
-        "name",
-        "description",
-        "reason"
-      ],
-      "properties": {
-        "id": {
-          "type": "string",
-          "pattern": "^[a-z][a-z0-9-]*$",
-          "description": "Unique identifier for this anti-pattern."
-        },
-        "name": {
-          "type": "string",
-          "minLength": 1,
-          "description": "Human-readable name describing what not to do."
-        },
-        "description": {
-          "type": "string",
-          "description": "What this anti-pattern is."
-        },
-        "reason": {
-          "type": "string",
-          "description": "Why this approach is ruled out."
-        },
-        "severity": {
-          "type": "string",
-          "enum": [
-            "must-not",
-            "should-not",
-            "discouraged"
-          ],
-          "description": "Strength of the prohibition. Defaults to should-not.",
-          "default": "should-not"
-        },
-        "insteadUse": {
-          "type": "string",
-          "description": "Pattern ID of the preferred approach."
-        },
-        "components": {
-          "type": "array",
-          "items": {
-            "type": "string"
-          },
-          "description": "Component IDs involved in this anti-pattern."
-        },
-        "tags": {
-          "type": "array",
-          "items": {
-            "type": "string"
-          },
-          "description": "Freeform classification tags."
-        }
-      },
-      "additionalProperties": true
+    "description": {
+     "type": "string",
+     "description": "What this key does in the context of this component."
+    }
+   },
+   "additionalProperties": true
+  },
+  "compositionRules": {
+   "type": "object",
+   "description": "Rules governing how a component composes with other components.",
+   "properties": {
+    "subComponents": {
+     "type": "array",
+     "description": "Sub-components that belong to this compound component.",
+     "items": {
+      "$ref": "#/$defs/subComponentDescriptor"
+     }
     },
-    "intentEntry": {
-      "type": "object",
-      "description": "A named generation intent: what kind of UI is being requested. Intents scope governance rules and select examples.",
-      "required": [
-        "id",
-        "description"
+    "requiredChildren": {
+     "type": "array",
+     "items": {
+      "type": "string"
+     },
+     "description": "Component IDs or sub-component IDs that must appear as descendants."
+    },
+    "allowedChildren": {
+     "type": "array",
+     "items": {
+      "type": "string"
+     },
+     "description": "Component IDs or sub-component IDs that may appear as direct children."
+    },
+    "requiredParent": {
+     "type": "string",
+     "description": "Component ID or sub-component ID that must be an ancestor."
+    },
+    "allowedParents": {
+     "type": "array",
+     "items": {
+      "type": "string"
+     },
+     "description": "Component IDs or sub-component IDs that may be the parent."
+    },
+    "requiredSiblings": {
+     "type": "array",
+     "items": {
+      "type": "string"
+     },
+     "description": "Component IDs or sub-component IDs that must also be present among siblings."
+    },
+    "notes": {
+     "type": "string",
+     "description": "Prose description of composition constraints not captured by structured fields."
+    }
+   },
+   "additionalProperties": true
+  },
+  "subComponentDescriptor": {
+   "type": "object",
+   "description": "Describes a sub-component of a compound component.",
+   "required": [
+    "id",
+    "name"
+   ],
+   "properties": {
+    "id": {
+     "type": "string",
+     "pattern": "^[a-z][a-z0-9-]*$",
+     "description": "Identifier for the sub-component. Should be parent-prefixed."
+    },
+    "name": {
+     "type": "string",
+     "minLength": 1,
+     "description": "Human-readable display name."
+    },
+    "description": {
+     "type": "string",
+     "description": "What this sub-component is for."
+    },
+    "required": {
+     "type": "boolean",
+     "description": "Whether this sub-component must be present when the parent is used.",
+     "default": false
+    },
+    "slot": {
+     "type": "string",
+     "description": "Named slot this sub-component fills."
+    },
+    "acceptsChildren": {
+     "type": "string",
+     "enum": [
+      "any",
+      "text",
+      "components",
+      "none"
+     ],
+     "description": "What this sub-component expects as children."
+    },
+    "categories": {
+     "type": "array",
+     "description": "Category ids this entry belongs to; each MUST be registered in the top-level categories registry.",
+     "items": {
+      "type": "string"
+     },
+     "minItems": 1
+    }
+   },
+   "additionalProperties": true
+  },
+  "constraintEntry": {
+   "type": "object",
+   "description": "A structured usage constraint.",
+   "required": [
+    "context",
+    "rule",
+    "severity"
+   ],
+   "properties": {
+    "context": {
+     "type": "string",
+     "description": "The situation or condition this constraint applies to."
+    },
+    "rule": {
+     "type": "string",
+     "description": "What to do or not do."
+    },
+    "severity": {
+     "type": "string",
+     "enum": [
+      "must",
+      "should",
+      "should-not",
+      "must-not"
+     ],
+     "description": "RFC 2119 strength of the constraint."
+    }
+   },
+   "additionalProperties": true
+  },
+  "patternEntry": {
+   "type": "object",
+   "description": "A pattern describing a preferred way of combining components.",
+   "required": [
+    "id",
+    "name",
+    "description"
+   ],
+   "properties": {
+    "id": {
+     "type": "string",
+     "pattern": "^[a-z][a-z0-9-]*$",
+     "description": "Unique identifier for this pattern."
+    },
+    "name": {
+     "type": "string",
+     "minLength": 1,
+     "description": "Human-readable name."
+    },
+    "description": {
+     "type": "string",
+     "description": "What problem this pattern addresses."
+    },
+    "intent": {
+     "type": "string",
+     "description": "The underlying design goal or UX objective."
+    },
+    "context": {
+     "type": "string",
+     "description": "When this pattern applies."
+    },
+    "components": {
+     "type": "array",
+     "items": {
+      "type": "string"
+     },
+     "description": "Component IDs involved in this pattern."
+    },
+    "guidance": {
+     "type": "string",
+     "description": "Prose guidance on how to apply the pattern correctly."
+    },
+    "relatedPatterns": {
+     "type": "array",
+     "items": {
+      "type": "string"
+     },
+     "description": "Pattern IDs of related patterns."
+    },
+    "tags": {
+     "type": "array",
+     "items": {
+      "type": "string"
+     },
+     "description": "Freeform classification tags."
+    }
+   },
+   "additionalProperties": true
+  },
+  "antiPatternEntry": {
+   "type": "object",
+   "description": "An anti-pattern describing an approach that is deliberately ruled out.",
+   "required": [
+    "id",
+    "name",
+    "description",
+    "reason"
+   ],
+   "properties": {
+    "id": {
+     "type": "string",
+     "pattern": "^[a-z][a-z0-9-]*$",
+     "description": "Unique identifier for this anti-pattern."
+    },
+    "name": {
+     "type": "string",
+     "minLength": 1,
+     "description": "Human-readable name describing what not to do."
+    },
+    "description": {
+     "type": "string",
+     "description": "What this anti-pattern is."
+    },
+    "reason": {
+     "type": "string",
+     "description": "Why this approach is ruled out."
+    },
+    "severity": {
+     "type": "string",
+     "enum": [
+      "must-not",
+      "should-not",
+      "discouraged"
+     ],
+     "description": "Strength of the prohibition. Defaults to should-not.",
+     "default": "should-not"
+    },
+    "insteadUse": {
+     "type": "string",
+     "description": "Pattern ID of the preferred approach."
+    },
+    "components": {
+     "type": "array",
+     "items": {
+      "type": "string"
+     },
+     "description": "Component IDs involved in this anti-pattern."
+    },
+    "tags": {
+     "type": "array",
+     "items": {
+      "type": "string"
+     },
+     "description": "Freeform classification tags."
+    }
+   },
+   "additionalProperties": true
+  },
+  "intentEntry": {
+   "type": "object",
+   "description": "A named generation intent: what kind of UI is being requested. Intents scope governance rules and select examples.",
+   "required": [
+    "id",
+    "description"
+   ],
+   "properties": {
+    "id": {
+     "type": "string",
+     "pattern": "^[a-z][a-z0-9-]*$",
+     "description": "Unique identifier for this intent."
+    },
+    "name": {
+     "type": "string",
+     "description": "Human-readable display name."
+    },
+    "description": {
+     "type": "string",
+     "description": "What kind of requested UI this intent covers. Written for both humans and generation prompts."
+    },
+    "relatedPatterns": {
+     "type": "array",
+     "description": "IDs of patterns that document how to satisfy this intent.",
+     "items": {
+      "type": "string"
+     }
+    },
+    "tags": {
+     "type": "array",
+     "description": "Free-form tags for grouping and search.",
+     "items": {
+      "type": "string"
+     }
+    }
+   },
+   "patternProperties": {
+    "^x-": {}
+   },
+   "additionalProperties": false
+  },
+  "ruleEntry": {
+   "type": "object",
+   "description": "A machine-checkable governance rule. The type field selects the evaluation algorithm (normative semantics in the v0.3/v0.4 specs). Linters MUST fail loudly on unknown types \u2014 never skip silently. Contract severity uses RFC 2119 terms; tools map must\u2192error and should\u2192warn.",
+   "required": [
+    "id",
+    "type",
+    "severity",
+    "rationale"
+   ],
+   "properties": {
+    "id": {
+     "type": "string",
+     "pattern": "^rule\\.[a-z0-9.-]+$",
+     "description": "Unique, stable identifier for this rule (rule.* namespace)."
+    },
+    "type": {
+     "type": "string",
+     "enum": [
+      "component-choice",
+      "required-composition",
+      "forbidden-composition",
+      "required-props"
+     ],
+     "description": "The rule type, selecting the evaluation algorithm. New types are added in future spec versions only (additive)."
+    },
+    "severity": {
+     "type": "string",
+     "enum": [
+      "must",
+      "should"
+     ],
+     "description": "RFC 2119 strength. Tools map must\u2192error (triggers repair/failure) and should\u2192warn (reported only)."
+    },
+    "rationale": {
+     "type": "string",
+     "minLength": 1,
+     "description": "Why this rule exists. Shown verbatim in lint findings, repair feedback, and audit reports."
+    },
+    "appliesTo": {
+     "type": "object",
+     "description": "Scope of the rule. Absent means universal (fires for every surface).",
+     "properties": {
+      "intents": {
+       "type": "array",
+       "description": "Intent IDs this rule fires for.",
+       "items": {
+        "type": "string"
+       },
+       "minItems": 1
+      }
+     },
+     "patternProperties": {
+      "^x-": {}
+     },
+     "additionalProperties": false
+    },
+    "examples": {
+     "type": "array",
+     "description": "IDs of examples demonstrating compliance; included in repair feedback as corrected references.",
+     "items": {
+      "type": "string"
+     }
+    },
+    "tags": {
+     "type": "array",
+     "description": "Free-form tags for grouping and search.",
+     "items": {
+      "type": "string"
+     }
+    }
+   },
+   "allOf": [
+    {
+     "if": {
+      "properties": {
+       "type": {
+        "const": "component-choice"
+       }
+      }
+     },
+     "then": {
+      "anyOf": [
+       {
+        "required": [
+         "require"
+        ]
+       },
+       {
+        "required": [
+         "forbid"
+        ]
+       }
       ],
       "properties": {
-        "id": {
-          "type": "string",
-          "pattern": "^[a-z][a-z0-9-]*$",
-          "description": "Unique identifier for this intent."
-        },
-        "name": {
-          "type": "string",
-          "description": "Human-readable display name."
-        },
-        "description": {
-          "type": "string",
-          "description": "What kind of requested UI this intent covers. Written for both humans and generation prompts."
-        },
-        "relatedPatterns": {
-          "type": "array",
-          "description": "IDs of patterns that document how to satisfy this intent.",
-          "items": {
-            "type": "string"
-          }
-        },
-        "tags": {
-          "type": "array",
-          "description": "Free-form tags for grouping and search.",
-          "items": {
-            "type": "string"
-          }
-        }
-      },
-      "patternProperties": {
-        "^x-": {}
-      },
-      "additionalProperties": false
+       "require": {
+        "type": "array",
+        "description": "Component IDs that MUST each appear at least once in the surface.",
+        "items": {
+         "type": "string"
+        },
+        "minItems": 1
+       },
+       "forbid": {
+        "type": "array",
+        "description": "Component IDs that MUST NOT appear in the surface.",
+        "items": {
+         "type": "string"
+        },
+        "minItems": 1
+       }
+      }
+     }
     },
-    "ruleEntry": {
-      "type": "object",
-      "description": "A machine-checkable governance rule. The type field selects the evaluation algorithm (normative semantics in the v0.3/v0.4 specs). Linters MUST fail loudly on unknown types — never skip silently. Contract severity uses RFC 2119 terms; tools map must→error and should→warn.",
+    {
+     "if": {
+      "properties": {
+       "type": {
+        "const": "required-composition"
+       }
+      }
+     },
+     "then": {
       "required": [
-        "id",
-        "type",
-        "severity",
-        "rationale"
+       "component"
+      ],
+      "anyOf": [
+       {
+        "required": [
+         "requiredSubComponents"
+        ]
+       },
+       {
+        "required": [
+         "requiredProps"
+        ]
+       },
+       {
+        "required": [
+         "requiredCategories"
+        ]
+       }
       ],
       "properties": {
-        "id": {
-          "type": "string",
-          "pattern": "^rule\\.[a-z0-9.-]+$",
-          "description": "Unique, stable identifier for this rule (rule.* namespace)."
-        },
-        "type": {
-          "type": "string",
-          "enum": [
-            "component-choice",
-            "required-composition",
-            "forbidden-composition",
-            "required-props"
-          ],
-          "description": "The rule type, selecting the evaluation algorithm. New types are added in future spec versions only (additive)."
-        },
-        "severity": {
-          "type": "string",
-          "enum": [
-            "must",
-            "should"
-          ],
-          "description": "RFC 2119 strength. Tools map must→error (triggers repair/failure) and should→warn (reported only)."
-        },
-        "rationale": {
-          "type": "string",
-          "minLength": 1,
-          "description": "Why this rule exists. Shown verbatim in lint findings, repair feedback, and audit reports."
-        },
-        "appliesTo": {
-          "type": "object",
-          "description": "Scope of the rule. Absent means universal (fires for every surface).",
-          "properties": {
-            "intents": {
-              "type": "array",
-              "description": "Intent IDs this rule fires for.",
-              "items": {
-                "type": "string"
-              },
-              "minItems": 1
-            }
-          },
-          "patternProperties": {
-            "^x-": {}
+       "component": {
+        "type": "string",
+        "description": "Component ID every instance of which is checked."
+       },
+       "requiredSubComponents": {
+        "type": "array",
+        "description": "Sub-components that MUST appear among each matching node's descendants.",
+        "items": {
+         "type": "object",
+         "required": [
+          "id"
+         ],
+         "properties": {
+          "id": {
+           "type": "string",
+           "description": "Sub-component ID that must be present."
           },
-          "additionalProperties": false
-        },
-        "examples": {
-          "type": "array",
-          "description": "IDs of examples demonstrating compliance; included in repair feedback as corrected references.",
-          "items": {
-            "type": "string"
+          "min": {
+           "type": "integer",
+           "minimum": 1,
+           "default": 1,
+           "description": "Minimum number of occurrences among descendants."
           }
-        },
-        "tags": {
-          "type": "array",
-          "description": "Free-form tags for grouping and search.",
-          "items": {
-            "type": "string"
-          }
-        }
-      },
-      "allOf": [
-        {
-          "if": {
-            "properties": {
-              "type": {
-                "const": "component-choice"
-              }
-            }
+         },
+         "patternProperties": {
+          "^x-": {}
+         },
+         "additionalProperties": false
+        },
+        "minItems": 1
+       },
+       "requiredProps": {
+        "type": "array",
+        "description": "Prop constraints that MUST hold on each matching node (or on descendant sub-component nodes when 'on' is given).",
+        "items": {
+         "type": "object",
+         "required": [
+          "prop",
+          "oneOf"
+         ],
+         "properties": {
+          "on": {
+           "type": "string",
+           "description": "Sub-component ID the constraint applies to; absent means the matching component node itself."
           },
-          "then": {
-            "anyOf": [
-              {
-                "required": [
-                  "require"
-                ]
-              },
-              {
-                "required": [
-                  "forbid"
-                ]
-              }
-            ],
-            "properties": {
-              "require": {
-                "type": "array",
-                "description": "Component IDs that MUST each appear at least once in the surface.",
-                "items": {
-                  "type": "string"
-                },
-                "minItems": 1
-              },
-              "forbid": {
-                "type": "array",
-                "description": "Component IDs that MUST NOT appear in the surface.",
-                "items": {
-                  "type": "string"
-                },
-                "minItems": 1
-              }
-            }
-          }
-        },
-        {
-          "if": {
-            "properties": {
-              "type": {
-                "const": "required-composition"
-              }
-            }
-          },
-          "then": {
-            "required": [
-              "component"
-            ],
-            "anyOf": [
-              {
-                "required": [
-                  "requiredSubComponents"
-                ]
-              },
-              {
-                "required": [
-                  "requiredProps"
-                ]
-              }
-            ],
-            "properties": {
-              "component": {
-                "type": "string",
-                "description": "Component ID every instance of which is checked."
-              },
-              "requiredSubComponents": {
-                "type": "array",
-                "description": "Sub-components that MUST appear among each matching node's descendants.",
-                "items": {
-                  "type": "object",
-                  "required": [
-                    "id"
-                  ],
-                  "properties": {
-                    "id": {
-                      "type": "string",
-                      "description": "Sub-component ID that must be present."
-                    },
-                    "min": {
-                      "type": "integer",
-                      "minimum": 1,
-                      "default": 1,
-                      "description": "Minimum number of occurrences among descendants."
-                    }
-                  },
-                  "patternProperties": {
-                    "^x-": {}
-                  },
-                  "additionalProperties": false
-                },
-                "minItems": 1
-              },
-              "requiredProps": {
-                "type": "array",
-                "description": "Prop constraints that MUST hold on each matching node (or on descendant sub-component nodes when 'on' is given).",
-                "items": {
-                  "type": "object",
-                  "required": [
-                    "prop",
-                    "oneOf"
-                  ],
-                  "properties": {
-                    "on": {
-                      "type": "string",
-                      "description": "Sub-component ID the constraint applies to; absent means the matching component node itself."
-                    },
-                    "prop": {
-                      "type": "string",
-                      "description": "Prop name the constraint applies to."
-                    },
-                    "oneOf": {
-                      "type": "array",
-                      "description": "Allowed values; the prop MUST be present and take one of these.",
-                      "minItems": 1
-                    }
-                  },
-                  "patternProperties": {
-                    "^x-": {}
-                  },
-                  "additionalProperties": false
-                },
-                "minItems": 1
-              }
-            }
-          }
-        },
-        {
-          "if": {
-            "properties": {
-              "type": {
-                "const": "forbidden-composition"
-              }
-            }
+          "prop": {
+           "type": "string",
+           "description": "Prop name the constraint applies to."
           },
-          "then": {
-            "required": [
-              "component"
-            ],
-            "anyOf": [
-              {
-                "required": [
-                  "forbiddenDescendants"
-                ]
-              },
-              {
-                "required": [
-                  "forbiddenProps"
-                ]
-              },
-              {
-                "required": [
-                  "forbiddenCategories"
-                ]
-              }
-            ],
-            "properties": {
-              "component": {
-                "type": "string",
-                "description": "Component ID every instance of which is checked."
-              },
-              "forbiddenDescendants": {
-                "type": "array",
-                "description": "Component or sub-component IDs that MUST NOT appear among a matching node's descendants.",
-                "items": {
-                  "type": "string"
-                },
-                "minItems": 1
-              },
-              "forbiddenProps": {
-                "type": "array",
-                "description": "Prop values that MUST NOT be used on matching nodes (or on descendant sub-component nodes when 'on' is given).",
-                "items": {
-                  "type": "object",
-                  "required": [
-                    "prop",
-                    "values"
-                  ],
-                  "properties": {
-                    "on": {
-                      "type": "string",
-                      "description": "Sub-component ID the constraint applies to; absent means the matching component node itself."
-                    },
-                    "prop": {
-                      "type": "string",
-                      "description": "Prop name the constraint applies to."
-                    },
-                    "values": {
-                      "type": "array",
-                      "description": "Forbidden values for the prop.",
-                      "minItems": 1
-                    }
-                  },
-                  "patternProperties": {
-                    "^x-": {}
-                  },
-                  "additionalProperties": false
-                },
-                "minItems": 1
-              },
-              "forbiddenCategories": {
-                "type": "array",
-                "description": "Category ids: no descendant of a matching node may belong to any of these categories. Each id MUST be registered in the top-level categories registry.",
-                "items": {
-                  "type": "string"
-                },
-                "minItems": 1
-              }
-            }
+          "oneOf": {
+           "type": "array",
+           "description": "Allowed values; the prop MUST be present and take one of these.",
+           "minItems": 1
           }
-        },
-        {
-          "if": {
-            "properties": {
-              "type": {
-                "const": "required-props"
-              }
-            }
+         },
+         "patternProperties": {
+          "^x-": {}
+         },
+         "additionalProperties": false
+        },
+        "minItems": 1
+       },
+       "requiredCategories": {
+        "type": "array",
+        "minItems": 1,
+        "description": "Categories from which at least `min` descendants MUST appear beneath each matching node. Membership within one category is naturally OR across its components; multiple entries are independently required (AND), matching requiredSubComponents. The 2026-08-07 amendment, lifted from the \u00a76 ceiling on measured evidence.",
+        "items": {
+         "type": "object",
+         "required": [
+          "id"
+         ],
+         "properties": {
+          "id": {
+           "type": "string",
+           "description": "Category id (must be registered in the document's categories)."
           },
-          "then": {
-            "required": [
-              "component"
-            ],
-            "anyOf": [
-              {
-                "required": [
-                  "requiredText"
-                ]
-              },
-              {
-                "required": [
-                  "requiredProps"
-                ]
-              }
-            ],
-            "properties": {
-              "component": {
-                "type": "string",
-                "description": "Component or sub-component ID whose instances are checked (unlike other rule types, sub-component ids are accepted here)."
-              },
-              "within": {
-                "type": "string",
-                "description": "Optional scope: a component or sub-component ID. When present, only nodes with an ancestor matching this id are checked, and every node matching `within` MUST contain at least one node matching `component`."
-              },
-              "requiredText": {
-                "const": true,
-                "description": "The matching node MUST carry non-empty text. Where the text may live is set by `textScope`: its own `text` field only (the default, \"self\") or anywhere in its subtree (\"subtree\")."
-              },
-              "textScope": {
-                "type": "string",
-                "enum": [
-                  "self",
-                  "subtree"
-                ],
-                "default": "self",
-                "description": "Where requiredText looks for the text: \"self\" (the node's own `text` field — the default) or \"subtree\" (direct text on the node or any descendant; for compound wrappers whose documented projections lift a label from within). Amendment 2026-07-04, on PR-15 evidence."
-              },
-              "requiredProps": {
-                "type": "array",
-                "description": "Props that MUST be present directly on the matching node's `props`. Unlike required-composition's requiredProps, entries have no `on` (the rule's component IS the target) and `oneOf` is optional (presence-only when absent).",
-                "items": {
-                  "type": "object",
-                  "required": [
-                    "prop"
-                  ],
-                  "properties": {
-                    "prop": {
-                      "type": "string",
-                      "description": "Prop name that must be present on the node itself."
-                    },
-                    "oneOf": {
-                      "type": "array",
-                      "minItems": 1,
-                      "description": "Optional allowed values; when present the prop value MUST be a member."
-                    }
-                  },
-                  "patternProperties": {
-                    "^x-": {}
-                  },
-                  "additionalProperties": false
-                },
-                "minItems": 1
-              }
-            },
-            "dependentRequired": {
-              "textScope": [
-                "requiredText"
-              ]
-            }
+          "min": {
+           "type": "integer",
+           "minimum": 1,
+           "default": 1,
+           "description": "Minimum number of member descendants."
           }
+         },
+         "patternProperties": {
+          "^x-": {}
+         },
+         "additionalProperties": false
         }
-      ]
+       }
+      }
+     }
     },
-    "exampleEntry": {
-      "type": "object",
-      "description": "A compilable example surface tied to a named intent. Serves as documentation and as a few-shot exemplar for generation.",
-      "required": [
-        "id",
-        "intent",
-        "surface"
-      ],
+    {
+     "if": {
       "properties": {
-        "id": {
-          "type": "string",
-          "pattern": "^ex\\.[a-z0-9.-]+$",
-          "description": "Unique identifier for this example (ex.* namespace)."
-        },
-        "intent": {
-          "type": "string",
-          "description": "Intent ID this example demonstrates."
-        },
-        "name": {
-          "type": "string",
-          "description": "Human-readable display name."
-        },
-        "description": {
-          "type": "string",
-          "description": "What the example shows and why it is correct."
-        },
-        "prompt": {
-          "type": "string",
-          "description": "A representative user request this example answers; used as the user turn in few-shot blocks."
-        },
-        "surface": {
-          "type": "object",
-          "description": "A dspack surface document. Validated against dspack.surface.v0_1.schema.json plus the contract vocabulary by tooling; kept loose here to avoid a cross-file $ref."
-        }
-      },
-      "patternProperties": {
-        "^x-": {}
-      },
-      "additionalProperties": false
-    },
-    "frameworkBinding": {
-      "type": "object",
-      "description": "Framework-specific information for the design system.",
+       "type": {
+        "const": "forbidden-composition"
+       }
+      }
+     },
+     "then": {
       "required": [
-        "name"
+       "component"
+      ],
+      "anyOf": [
+       {
+        "required": [
+         "forbiddenDescendants"
+        ]
+       },
+       {
+        "required": [
+         "forbiddenProps"
+        ]
+       },
+       {
+        "required": [
+         "forbiddenCategories"
+        ]
+       }
       ],
       "properties": {
-        "name": {
-          "type": "string",
-          "minLength": 1,
-          "description": "Human-readable framework name."
-        },
-        "package": {
-          "type": "string",
-          "description": "Primary package name."
-        },
-        "installCommand": {
-          "type": "string",
-          "description": "How to install the framework binding."
-        },
-        "description": {
-          "type": "string",
-          "description": "What this binding provides."
-        },
-        "guidance": {
-          "type": "string",
-          "description": "Framework-wide guidance."
-        },
-        "components": {
-          "type": "object",
-          "description": "Per-component framework details keyed by component ID.",
-          "propertyNames": {
-            "pattern": "^[a-z][a-z0-9-]*$"
+       "component": {
+        "type": "string",
+        "description": "Component ID every instance of which is checked."
+       },
+       "forbiddenDescendants": {
+        "type": "array",
+        "description": "Component or sub-component IDs that MUST NOT appear among a matching node's descendants.",
+        "items": {
+         "type": "string"
+        },
+        "minItems": 1
+       },
+       "forbiddenProps": {
+        "type": "array",
+        "description": "Prop values that MUST NOT be used on matching nodes (or on descendant sub-component nodes when 'on' is given).",
+        "items": {
+         "type": "object",
+         "required": [
+          "prop",
+          "values"
+         ],
+         "properties": {
+          "on": {
+           "type": "string",
+           "description": "Sub-component ID the constraint applies to; absent means the matching component node itself."
           },
-          "additionalProperties": {
-            "$ref": "#/$defs/componentBinding"
-          }
-        }
-      },
-      "additionalProperties": true
-    },
-    "componentBinding": {
-      "type": "object",
-      "description": "Framework-specific details for a single component.",
-      "properties": {
-        "importPath": {
-          "type": "string",
-          "description": "Where to import the component."
-        },
-        "installCommand": {
-          "type": "string",
-          "description": "Component-specific install command."
-        },
-        "exportName": {
-          "type": "string",
-          "description": "Named export if different from the component name."
-        },
-        "guidance": {
-          "type": "string",
-          "description": "Framework-specific usage guidance for this component."
-        },
-        "subComponents": {
-          "type": "object",
-          "description": "Map of sub-component ID to sub-component binding.",
-          "propertyNames": {
-            "pattern": "^[a-z][a-z0-9-]*$"
+          "prop": {
+           "type": "string",
+           "description": "Prop name the constraint applies to."
           },
-          "additionalProperties": {
-            "$ref": "#/$defs/subComponentBinding"
+          "values": {
+           "type": "array",
+           "description": "Forbidden values for the prop.",
+           "minItems": 1
           }
-        }
-      },
-      "additionalProperties": true
+         },
+         "patternProperties": {
+          "^x-": {}
+         },
+         "additionalProperties": false
+        },
+        "minItems": 1
+       },
+       "forbiddenCategories": {
+        "type": "array",
+        "description": "Category ids: no descendant of a matching node may belong to any of these categories. Each id MUST be registered in the top-level categories registry.",
+        "items": {
+         "type": "string"
+        },
+        "minItems": 1
+       }
+      }
+     }
     },
-    "subComponentBinding": {
-      "type": "object",
-      "description": "Framework-specific details for a sub-component.",
+    {
+     "if": {
       "properties": {
-        "exportName": {
-          "type": "string",
-          "description": "Named export for this sub-component."
-        },
-        "importPath": {
-          "type": "string",
-          "description": "Import path if different from the parent component's import path."
-        }
-      },
-      "additionalProperties": true
-    },
-    "themeEntry": {
-      "type": "object",
-      "description": "A named set of token overrides representing an alternative visual mode.",
+       "type": {
+        "const": "required-props"
+       }
+      }
+     },
+     "then": {
       "required": [
-        "name",
-        "overrides"
+       "component"
+      ],
+      "anyOf": [
+       {
+        "required": [
+         "requiredText"
+        ]
+       },
+       {
+        "required": [
+         "requiredProps"
+        ]
+       }
       ],
       "properties": {
-        "name": {
-          "type": "string",
-          "minLength": 1,
-          "description": "Human-readable theme name."
-        },
-        "description": {
-          "type": "string",
-          "description": "What this theme is for."
-        },
-        "overrides": {
-          "type": "object",
-          "description": "Map of token reference (category.tokenName) to overridden resolved value.",
-          "propertyNames": {
-            "pattern": "^[a-z][a-z0-9-]*\\.[a-z][a-z0-9-]*$"
+       "component": {
+        "type": "string",
+        "description": "Component or sub-component ID whose instances are checked (unlike other rule types, sub-component ids are accepted here)."
+       },
+       "within": {
+        "type": "string",
+        "description": "Optional scope: a component or sub-component ID. When present, only nodes with an ancestor matching this id are checked, and every node matching `within` MUST contain at least one node matching `component`."
+       },
+       "requiredText": {
+        "const": true,
+        "description": "The matching node MUST carry non-empty text. Where the text may live is set by `textScope`: its own `text` field only (the default, \"self\") or anywhere in its subtree (\"subtree\")."
+       },
+       "textScope": {
+        "type": "string",
+        "enum": [
+         "self",
+         "subtree"
+        ],
+        "default": "self",
+        "description": "Where requiredText looks for the text: \"self\" (the node's own `text` field \u2014 the default) or \"subtree\" (direct text on the node or any descendant; for compound wrappers whose documented projections lift a label from within). Amendment 2026-07-04, on PR-15 evidence."
+       },
+       "requiredProps": {
+        "type": "array",
+        "description": "Props that MUST be present directly on the matching node's `props`. Unlike required-composition's requiredProps, entries have no `on` (the rule's component IS the target) and `oneOf` is optional (presence-only when absent).",
+        "items": {
+         "type": "object",
+         "required": [
+          "prop"
+         ],
+         "properties": {
+          "prop": {
+           "type": "string",
+           "description": "Prop name that must be present on the node itself."
           },
-          "additionalProperties": {
-            "type": "string"
+          "oneOf": {
+           "type": "array",
+           "minItems": 1,
+           "description": "Optional allowed values; when present the prop value MUST be a member."
           }
-        }
+         },
+         "patternProperties": {
+          "^x-": {}
+         },
+         "additionalProperties": false
+        },
+        "minItems": 1
+       }
       },
-      "additionalProperties": true
+      "dependentRequired": {
+       "textScope": [
+        "requiredText"
+       ]
+      }
+     }
+    }
+   ]
+  },
+  "exampleEntry": {
+   "type": "object",
+   "description": "A compilable example surface tied to a named intent. Serves as documentation and as a few-shot exemplar for generation.",
+   "required": [
+    "id",
+    "intent",
+    "surface"
+   ],
+   "properties": {
+    "id": {
+     "type": "string",
+     "pattern": "^ex\\.[a-z0-9.-]+$",
+     "description": "Unique identifier for this example (ex.* namespace)."
     },
-    "layoutPrimitives": {
-      "type": "object",
-      "description": "Layout system primitives: breakpoints, grid, containers, and spacing scale.",
-      "properties": {
-        "breakpoints": {
-          "type": "object",
-          "description": "Named responsive breakpoints.",
-          "additionalProperties": {
-            "$ref": "#/$defs/breakpointEntry"
-          }
-        },
-        "grid": {
-          "$ref": "#/$defs/gridConfig"
-        },
-        "containers": {
-          "type": "object",
-          "description": "Named container width configurations.",
-          "additionalProperties": {
-            "$ref": "#/$defs/containerEntry"
-          }
-        },
-        "spacingScale": {
-          "$ref": "#/$defs/spacingScaleConfig"
-        }
-      },
-      "additionalProperties": true
+    "intent": {
+     "type": "string",
+     "description": "Intent ID this example demonstrates."
     },
-    "breakpointEntry": {
-      "type": "object",
-      "description": "A responsive breakpoint definition.",
-      "required": [
-        "minWidth"
-      ],
-      "properties": {
-        "minWidth": {
-          "type": "string",
-          "description": "Minimum viewport width for this breakpoint."
-        },
-        "description": {
-          "type": "string",
-          "description": "What this breakpoint targets."
-        }
-      },
-      "additionalProperties": true
+    "name": {
+     "type": "string",
+     "description": "Human-readable display name."
     },
-    "gridConfig": {
-      "type": "object",
-      "description": "Grid system parameters.",
-      "properties": {
-        "columns": {
-          "type": "number",
-          "description": "Number of columns in the grid system."
-        },
-        "gutter": {
-          "type": "string",
-          "description": "Default gutter width between columns."
-        },
-        "margin": {
-          "type": "string",
-          "description": "Default outer margin of the grid container."
-        },
-        "description": {
-          "type": "string",
-          "description": "Guidance on grid usage."
-        }
-      },
-      "additionalProperties": true
+    "description": {
+     "type": "string",
+     "description": "What the example shows and why it is correct."
     },
-    "containerEntry": {
-      "type": "object",
-      "description": "A container width configuration.",
-      "required": [
-        "maxWidth"
-      ],
-      "properties": {
-        "maxWidth": {
-          "type": "string",
-          "description": "Maximum width of this container."
-        },
-        "description": {
-          "type": "string",
-          "description": "When to use this container size."
-        }
-      },
-      "additionalProperties": true
+    "prompt": {
+     "type": "string",
+     "description": "A representative user request this example answers; used as the user turn in few-shot blocks."
     },
-    "spacingScaleConfig": {
-      "type": "object",
-      "description": "Spacing scale system description.",
-      "properties": {
-        "baseUnit": {
-          "type": "string",
-          "description": "The fundamental unit of the spacing scale."
-        },
-        "description": {
-          "type": "string",
-          "description": "How the scale is constructed."
-        }
-      },
-      "additionalProperties": true
+    "surface": {
+     "type": "object",
+     "description": "A dspack surface document. Validated against dspack.surface.v0_1.schema.json plus the contract vocabulary by tooling; kept loose here to avoid a cross-file $ref."
+    }
+   },
+   "patternProperties": {
+    "^x-": {}
+   },
+   "additionalProperties": false
+  },
+  "frameworkBinding": {
+   "type": "object",
+   "description": "Framework-specific information for the design system.",
+   "required": [
+    "name"
+   ],
+   "properties": {
+    "name": {
+     "type": "string",
+     "minLength": 1,
+     "description": "Human-readable framework name."
     },
-    "categoryEntry": {
-      "type": "object",
-      "description": "A component category: a named role components/sub-components can declare and rules can select by.",
-      "required": [
-        "description"
-      ],
-      "properties": {
-        "name": {
-          "type": "string",
-          "description": "Display name."
-        },
-        "description": {
-          "type": "string",
-          "minLength": 1,
-          "description": "What membership in this category means; written for maintainers and reviewers."
-        }
-      },
-      "patternProperties": {
-        "^x-": {}
-      },
-      "additionalProperties": false
+    "package": {
+     "type": "string",
+     "description": "Primary package name."
+    },
+    "installCommand": {
+     "type": "string",
+     "description": "How to install the framework binding."
+    },
+    "description": {
+     "type": "string",
+     "description": "What this binding provides."
+    },
+    "guidance": {
+     "type": "string",
+     "description": "Framework-wide guidance."
+    },
+    "components": {
+     "type": "object",
+     "description": "Per-component framework details keyed by component ID.",
+     "propertyNames": {
+      "pattern": "^[a-z][a-z0-9-]*$"
+     },
+     "additionalProperties": {
+      "$ref": "#/$defs/componentBinding"
+     }
+    }
+   },
+   "additionalProperties": true
+  },
+  "componentBinding": {
+   "type": "object",
+   "description": "Framework-specific details for a single component.",
+   "properties": {
+    "importPath": {
+     "type": "string",
+     "description": "Where to import the component."
+    },
+    "installCommand": {
+     "type": "string",
+     "description": "Component-specific install command."
+    },
+    "exportName": {
+     "type": "string",
+     "description": "Named export if different from the component name."
+    },
+    "guidance": {
+     "type": "string",
+     "description": "Framework-specific usage guidance for this component."
+    },
+    "subComponents": {
+     "type": "object",
+     "description": "Map of sub-component ID to sub-component binding.",
+     "propertyNames": {
+      "pattern": "^[a-z][a-z0-9-]*$"
+     },
+     "additionalProperties": {
+      "$ref": "#/$defs/subComponentBinding"
+     }
+    }
+   },
+   "additionalProperties": true
+  },
+  "subComponentBinding": {
+   "type": "object",
+   "description": "Framework-specific details for a sub-component.",
+   "properties": {
+    "exportName": {
+     "type": "string",
+     "description": "Named export for this sub-component."
+    },
+    "importPath": {
+     "type": "string",
+     "description": "Import path if different from the parent component's import path."
+    }
+   },
+   "additionalProperties": true
+  },
+  "themeEntry": {
+   "type": "object",
+   "description": "A named set of token overrides representing an alternative visual mode.",
+   "required": [
+    "name",
+    "overrides"
+   ],
+   "properties": {
+    "name": {
+     "type": "string",
+     "minLength": 1,
+     "description": "Human-readable theme name."
+    },
+    "description": {
+     "type": "string",
+     "description": "What this theme is for."
+    },
+    "overrides": {
+     "type": "object",
+     "description": "Map of token reference (category.tokenName) to overridden resolved value.",
+     "propertyNames": {
+      "pattern": "^[a-z][a-z0-9-]*\\.[a-z][a-z0-9-]*$"
+     },
+     "additionalProperties": {
+      "type": "string"
+     }
+    }
+   },
+   "additionalProperties": true
+  },
+  "layoutPrimitives": {
+   "type": "object",
+   "description": "Layout system primitives: breakpoints, grid, containers, and spacing scale.",
+   "properties": {
+    "breakpoints": {
+     "type": "object",
+     "description": "Named responsive breakpoints.",
+     "additionalProperties": {
+      "$ref": "#/$defs/breakpointEntry"
+     }
+    },
+    "grid": {
+     "$ref": "#/$defs/gridConfig"
+    },
+    "containers": {
+     "type": "object",
+     "description": "Named container width configurations.",
+     "additionalProperties": {
+      "$ref": "#/$defs/containerEntry"
+     }
+    },
+    "spacingScale": {
+     "$ref": "#/$defs/spacingScaleConfig"
+    }
+   },
+   "additionalProperties": true
+  },
+  "breakpointEntry": {
+   "type": "object",
+   "description": "A responsive breakpoint definition.",
+   "required": [
+    "minWidth"
+   ],
+   "properties": {
+    "minWidth": {
+     "type": "string",
+     "description": "Minimum viewport width for this breakpoint."
+    },
+    "description": {
+     "type": "string",
+     "description": "What this breakpoint targets."
+    }
+   },
+   "additionalProperties": true
+  },
+  "gridConfig": {
+   "type": "object",
+   "description": "Grid system parameters.",
+   "properties": {
+    "columns": {
+     "type": "number",
+     "description": "Number of columns in the grid system."
+    },
+    "gutter": {
+     "type": "string",
+     "description": "Default gutter width between columns."
+    },
+    "margin": {
+     "type": "string",
+     "description": "Default outer margin of the grid container."
+    },
+    "description": {
+     "type": "string",
+     "description": "Guidance on grid usage."
+    }
+   },
+   "additionalProperties": true
+  },
+  "containerEntry": {
+   "type": "object",
+   "description": "A container width configuration.",
+   "required": [
+    "maxWidth"
+   ],
+   "properties": {
+    "maxWidth": {
+     "type": "string",
+     "description": "Maximum width of this container."
+    },
+    "description": {
+     "type": "string",
+     "description": "When to use this container size."
+    }
+   },
+   "additionalProperties": true
+  },
+  "spacingScaleConfig": {
+   "type": "object",
+   "description": "Spacing scale system description.",
+   "properties": {
+    "baseUnit": {
+     "type": "string",
+     "description": "The fundamental unit of the spacing scale."
+    },
+    "description": {
+     "type": "string",
+     "description": "How the scale is constructed."
+    }
+   },
+   "additionalProperties": true
+  },
+  "categoryEntry": {
+   "type": "object",
+   "description": "A component category: a named role components/sub-components can declare and rules can select by.",
+   "required": [
+    "description"
+   ],
+   "properties": {
+    "name": {
+     "type": "string",
+     "description": "Display name."
+    },
+    "description": {
+     "type": "string",
+     "minLength": 1,
+     "description": "What membership in this category means; written for maintainers and reviewers."
     }
+   },
+   "patternProperties": {
+    "^x-": {}
+   },
+   "additionalProperties": false
   }
+ }
 }
diff --git a/src/tests/fixtures/shadcn.destructive-action.context.json b/src/tests/fixtures/shadcn.destructive-action.context.json
index eb088b3..07964f4 100644
--- a/src/tests/fixtures/shadcn.destructive-action.context.json
+++ b/src/tests/fixtures/shadcn.destructive-action.context.json
@@ -1,5 +1,5 @@
 {
-  "system": "You generate user interface surfaces for the \"shadcn/ui\" design system. You must respond\nwith a single JSON object conforming to the provided schema — a dspack surface document.\n\n## Component vocabulary\nYou may use only these components (with the listed props and allowed values):\n- button — An interactive element that triggers an action when activated. Built on a native button element with support for Radix UI Slot composition via asChild. Props: variant ∈ {default, destructive, outline, secondary, ghost, link}; size ∈ {default, sm, lg, icon}; disabled; asChild.\n- alert-dialog — A modal dialog that interrupts the user with important content and expects a response. Built on Radix UI AlertDialog. Renders with a required action and a cancel option. The user cannot dismiss it by clicking the overlay or pressing Escape — they must choose an explicit action. Props: open; onOpenChange. Sub-components (used as children): alert-dialog-trigger, alert-dialog-content, alert-dialog-header, alert-dialog-title, alert-dialog-description, alert-dialog-footer, alert-dialog-action, alert-dialog-cancel.\n- dialog — A modal window that appears over the page content. Built on Radix UI Dialog. Can be dismissed by clicking the overlay, pressing Escape, or activating a close button. Props: open; onOpenChange; modal. Sub-components (used as children): dialog-trigger, dialog-content, dialog-header, dialog-title, dialog-description, dialog-footer, dialog-close.\n- card — A container for grouping related content and actions. Provides visual separation through a bordered surface. Props: className. Sub-components (used as children): card-header, card-title, card-description, card-content, card-footer.\n- input — A single-line text input field built on the native <input> element. Supports all standard HTML input types. Props: type; placeholder; disabled.\n- badge — A small label for categorization, status indication, or metadata. Renders as an inline element. Props: variant ∈ {default, secondary, outline, destructive}.\n- dropdown-menu — A menu that appears on activation of a trigger element. Built on Radix UI DropdownMenu. Supports items, checkboxes, radio groups, sub-menus, separators, and keyboard navigation. Props: open; onOpenChange; modal. Sub-components (used as children): dropdown-menu-trigger, dropdown-menu-content, dropdown-menu-item, dropdown-menu-checkbox-item, dropdown-menu-radio-group, dropdown-menu-radio-item, dropdown-menu-label, dropdown-menu-separator, dropdown-menu-group, dropdown-menu-sub, dropdown-menu-sub-trigger, dropdown-menu-sub-content.\n- table — A set of primitives for presenting tabular data with a meaningful row-and-column relationship. These are thin, presentational wrappers over the native table elements — Table renders a <table> inside a horizontally scrollable container, and the sub-components render thead, tbody, tfoot, tr, th, td, and caption. There is no built-in sorting, filtering, pagination, or selection; those are composed on top. Sub-components (used as children): table-header, table-body, table-footer, table-row, table-head, table-cell, table-caption.\n\n## Governance rules in effect (intent: destructive-action)\nThese are hard requirements. Surfaces violating them will be rejected:\n1. [rule.destructive-requires-alertdialog / must] Use alert-dialog for this surface; dialog is forbidden. Why: Dialog can be dismissed by clicking the overlay or pressing Escape, so a user can bypass a destructive confirmation without making a conscious choice. AlertDialog forces an explicit confirm/cancel decision and is announced with greater urgency by screen readers.\n2. [rule.alertdialog-requires-cancel / must] Every alert-dialog must contain alert-dialog-cancel and alert-dialog-title. Why: A confirmation without an explicit cancel action and a title naming the consequence funnels the user toward the destructive action; the title is also required for aria-labelledby.\n3. [rule.button-no-interactive-descendants / must] Never place button or input inside a button. Why: Nested interactive elements create ambiguous click targets and are an accessibility violation: screen readers cannot determine intent and click handling varies across browsers.\n4. [rule.trigger-carries-label / must] Every alert-dialog-trigger must contain non-empty text (its own `text` field or a descendant's). Why: The trigger must present an accessible label: non-empty text somewhere under the trigger. Protocol projections lift the label from the trigger's subtree (preferring a label-bearing button; lifts are audited) — a trigger with no label text anywhere yields a control with no accessible name and an instance downstream emitters must refuse.\n5. [rule.alertdialog-no-nested-overlays / must] never place overlay-category components (alert-dialog, dialog, dropdown-menu) inside alert-dialog. Why: An alert dialog is a single focused interruption. Stacking another overlay (dialog, dropdown menu, another alert dialog) inside it breaks focus containment and dismiss semantics and buries the confirmation decision under a second layer.\n\n## Design intent\nIntent \"destructive-action\": The requested UI performs an irreversible or high-consequence operation: deleting records or accounts, revoking access, removing members.\nRelated pattern \"Destructive Action Confirmation\": Use AlertDialog, not Dialog, for destructive confirmations. The trigger should clearly indicate the destructive nature of the action. Inside the AlertDialog, provide a clear title stating what will happen, a description of the consequences, and two actions: a cancel option and a confirm option. The confirm button MUST use the destructive variant. Place the cancel action before the confirm action in the footer. The description should state specifically what will be affected (e.g., 'This will permanently delete 3 projects and all associated data').\n\nOutput only the JSON object. No commentary.",
+  "system": "You generate user interface surfaces for the \"shadcn/ui\" design system. You must respond\nwith a single JSON object conforming to the provided schema — a dspack surface document.\n\n## Component vocabulary\nYou may use only these components (with the listed props and allowed values):\n- button — An interactive element that triggers an action when activated. Built on a native button element with support for Radix UI Slot composition via asChild. Props: variant ∈ {default, destructive, outline, secondary, ghost, link}; size ∈ {default, sm, lg, icon}; disabled; asChild.\n- alert-dialog — A modal dialog that interrupts the user with important content and expects a response. Built on Radix UI AlertDialog. Renders with a required action and a cancel option. The user cannot dismiss it by clicking the overlay or pressing Escape — they must choose an explicit action. Props: open; onOpenChange. Sub-components (used as children): alert-dialog-trigger, alert-dialog-content, alert-dialog-header, alert-dialog-title, alert-dialog-description, alert-dialog-footer, alert-dialog-action, alert-dialog-cancel. Composition: AlertDialogContent must contain AlertDialogTitle and AlertDialogDescription for accessibility. AlertDialogAction and AlertDialogCancel must appear in AlertDialogFooter.\n- dialog — A modal window that appears over the page content. Built on Radix UI Dialog. Can be dismissed by clicking the overlay, pressing Escape, or activating a close button. Props: open; onOpenChange; modal. Sub-components (used as children): dialog-trigger, dialog-content, dialog-header, dialog-title, dialog-description, dialog-footer, dialog-close.\n- card — A container for grouping related content and actions. Provides visual separation through a bordered surface. Props: className. Sub-components (used as children): card-header, card-title, card-description, card-content, card-footer.\n- input — A single-line text input field built on the native <input> element. Supports all standard HTML input types. Props: type; placeholder; disabled.\n- badge — A small label for categorization, status indication, or metadata. Renders as an inline element. Props: variant ∈ {default, secondary, outline, destructive}.\n- dropdown-menu — A menu that appears on activation of a trigger element. Built on Radix UI DropdownMenu. Supports items, checkboxes, radio groups, sub-menus, separators, and keyboard navigation. Props: open; onOpenChange; modal. Sub-components (used as children): dropdown-menu-trigger, dropdown-menu-content, dropdown-menu-item, dropdown-menu-checkbox-item, dropdown-menu-radio-group, dropdown-menu-radio-item, dropdown-menu-label, dropdown-menu-separator, dropdown-menu-group, dropdown-menu-sub, dropdown-menu-sub-trigger, dropdown-menu-sub-content.\n- table — A set of primitives for presenting tabular data with a meaningful row-and-column relationship. These are thin, presentational wrappers over the native table elements — Table renders a <table> inside a horizontally scrollable container, and the sub-components render thead, tbody, tfoot, tr, th, td, and caption. There is no built-in sorting, filtering, pagination, or selection; those are composed on top. Sub-components (used as children): table-header, table-body, table-footer, table-row, table-head, table-cell, table-caption. Composition: TableRow must appear inside TableHeader, TableBody, or TableFooter — not directly under Table. Header cells use TableHead (th); data cells use TableCell (td).\n\n## Governance rules in effect (intent: destructive-action)\nThese are hard requirements. Surfaces violating them will be rejected:\n1. [rule.destructive-requires-alertdialog / must] Use alert-dialog for this surface; dialog is forbidden. Why: Dialog can be dismissed by clicking the overlay or pressing Escape, so a user can bypass a destructive confirmation without making a conscious choice. AlertDialog forces an explicit confirm/cancel decision and is announced with greater urgency by screen readers.\n2. [rule.alertdialog-requires-cancel / must] Every alert-dialog must contain alert-dialog-cancel and alert-dialog-title. Why: A confirmation without an explicit cancel action and a title naming the consequence funnels the user toward the destructive action; the title is also required for aria-labelledby.\n3. [rule.button-no-interactive-descendants / must] Never place button or input inside a button. Why: Nested interactive elements create ambiguous click targets and are an accessibility violation: screen readers cannot determine intent and click handling varies across browsers.\n4. [rule.trigger-carries-label / must] Every alert-dialog-trigger must contain non-empty text (its own `text` field or a descendant's). Why: The trigger must present an accessible label: non-empty text somewhere under the trigger. Protocol projections lift the label from the trigger's subtree (preferring a label-bearing button; lifts are audited) — a trigger with no label text anywhere yields a control with no accessible name and an instance downstream emitters must refuse.\n5. [rule.alertdialog-no-nested-overlays / must] never place overlay-category components (alert-dialog, dialog, dropdown-menu) inside alert-dialog. Why: An alert dialog is a single focused interruption. Stacking another overlay (dialog, dropdown menu, another alert dialog) inside it breaks focus containment and dismiss semantics and buries the confirmation decision under a second layer.\n\n## Design intent\nIntent \"destructive-action\": The requested UI performs an irreversible or high-consequence operation: deleting records or accounts, revoking access, removing members.\nRelated pattern \"Destructive Action Confirmation\": Use AlertDialog, not Dialog, for destructive confirmations. The trigger should clearly indicate the destructive nature of the action. Inside the AlertDialog, provide a clear title stating what will happen, a description of the consequences, and two actions: a cancel option and a confirm option. The confirm button MUST use the destructive variant. Place the cancel action before the confirm action in the footer. The description should state specifically what will be affected (e.g., 'This will permanently delete 3 projects and all associated data').\n\nOutput only the JSON object. No commentary.",
   "schema": {
     "$schema": "https://json-schema.org/draft/2020-12/schema",
     "type": "object",
diff --git a/src/tests/fixtures/shadcn.v0_4.contract.json b/src/tests/fixtures/shadcn.v0_4.contract.json
new file mode 100644
index 0000000..6ebd8d7
--- /dev/null
+++ b/src/tests/fixtures/shadcn.v0_4.contract.json
@@ -0,0 +1,1411 @@
+{
+  "$schema": "../schema/dspack.v0.4.schema.json",
+  "dspack": "0.4",
+  "name": "shadcn/ui",
+  "description": "A collection of reusable components built with Radix UI and Tailwind CSS. Components are copied into your project, not installed as a dependency.",
+  "version": "2.3.0",
+  "metadata": {
+    "source": "https://ui.shadcn.com",
+    "license": "MIT"
+  },
+  "tokens": {
+    "color-primitives": {
+      "description": "Raw color palette values. These are the base colors from which semantic tokens are derived.",
+      "tier": "primitive",
+      "values": {
+        "white": {
+          "value": "hsl(0, 0%, 100%)",
+          "type": "color"
+        },
+        "slate-950": {
+          "value": "hsl(222.2, 84%, 4.9%)",
+          "type": "color"
+        },
+        "slate-900": {
+          "value": "hsl(222.2, 47.4%, 11.2%)",
+          "type": "color"
+        },
+        "slate-50": {
+          "value": "hsl(210, 40%, 98%)",
+          "type": "color"
+        },
+        "slate-100": {
+          "value": "hsl(210, 40%, 96.1%)",
+          "type": "color"
+        },
+        "slate-400": {
+          "value": "hsl(215.4, 16.3%, 46.9%)",
+          "type": "color"
+        },
+        "slate-200": {
+          "value": "hsl(214.3, 31.8%, 91.4%)",
+          "type": "color"
+        },
+        "red-500": {
+          "value": "hsl(0, 84.2%, 60.2%)",
+          "type": "color"
+        },
+        "blue-500": {
+          "value": "hsl(217.2, 91.2%, 59.8%)",
+          "type": "color"
+        }
+      }
+    },
+    "color": {
+      "description": "Semantic color tokens. Values shown are the default light theme.",
+      "tier": "semantic",
+      "values": {
+        "background": {
+          "value": "hsl(0, 0%, 100%)",
+          "description": "Default page background color.",
+          "type": "color",
+          "aliasOf": {
+            "category": "color-primitives",
+            "token": "white"
+          }
+        },
+        "foreground": {
+          "value": "hsl(222.2, 84%, 4.9%)",
+          "description": "Default text color.",
+          "type": "color",
+          "aliasOf": {
+            "category": "color-primitives",
+            "token": "slate-950"
+          }
+        },
+        "primary": {
+          "value": "hsl(222.2, 47.4%, 11.2%)",
+          "description": "Primary brand color used for prominent interactive elements and emphasis.",
+          "type": "color",
+          "aliasOf": {
+            "category": "color-primitives",
+            "token": "slate-900"
+          }
+        },
+        "primary-foreground": {
+          "value": "hsl(210, 40%, 98%)",
+          "description": "Text color on primary-colored backgrounds.",
+          "type": "color",
+          "aliasOf": {
+            "category": "color-primitives",
+            "token": "slate-50"
+          }
+        },
+        "secondary": {
+          "value": "hsl(210, 40%, 96.1%)",
+          "description": "Secondary color for less prominent interactive elements.",
+          "type": "color",
+          "aliasOf": {
+            "category": "color-primitives",
+            "token": "slate-100"
+          }
+        },
+        "secondary-foreground": {
+          "value": "hsl(222.2, 47.4%, 11.2%)",
+          "description": "Text color on secondary-colored backgrounds.",
+          "type": "color",
+          "aliasOf": {
+            "category": "color-primitives",
+            "token": "slate-900"
+          }
+        },
+        "muted": {
+          "value": "hsl(210, 40%, 96.1%)",
+          "description": "Muted background color for subtle UI areas.",
+          "type": "color",
+          "aliasOf": {
+            "category": "color-primitives",
+            "token": "slate-100"
+          }
+        },
+        "muted-foreground": {
+          "value": "hsl(215.4, 16.3%, 46.9%)",
+          "description": "Text color for de-emphasized or secondary text.",
+          "type": "color",
+          "aliasOf": {
+            "category": "color-primitives",
+            "token": "slate-400"
+          }
+        },
+        "accent": {
+          "value": "hsl(210, 40%, 96.1%)",
+          "description": "Accent color for highlights and hover states.",
+          "type": "color",
+          "aliasOf": {
+            "category": "color-primitives",
+            "token": "slate-100"
+          }
+        },
+        "destructive": {
+          "value": "hsl(0, 84.2%, 60.2%)",
+          "description": "Color for destructive actions such as delete or remove.",
+          "type": "color",
+          "aliasOf": {
+            "category": "color-primitives",
+            "token": "red-500"
+          }
+        },
+        "destructive-foreground": {
+          "value": "hsl(210, 40%, 98%)",
+          "description": "Text color on destructive-colored backgrounds.",
+          "type": "color",
+          "aliasOf": {
+            "category": "color-primitives",
+            "token": "slate-50"
+          }
+        },
+        "border": {
+          "value": "hsl(214.3, 31.8%, 91.4%)",
+          "description": "Default border color.",
+          "type": "color",
+          "aliasOf": {
+            "category": "color-primitives",
+            "token": "slate-200"
+          }
+        },
+        "ring": {
+          "value": "hsl(222.2, 84%, 4.9%)",
+          "description": "Focus ring color for interactive elements.",
+          "type": "color",
+          "aliasOf": {
+            "category": "color-primitives",
+            "token": "slate-950"
+          }
+        }
+      }
+    },
+    "spacing": {
+      "description": "Spacing scale based on a 4px (0.25rem) base unit at the default root font size.",
+      "values": {
+        "sp-1": {
+          "value": "0.25rem",
+          "description": "4px. Smallest spacing unit, used for tight internal padding.",
+          "type": "dimension"
+        },
+        "sp-2": {
+          "value": "0.5rem",
+          "description": "8px. Small spacing, used for gaps between related elements.",
+          "type": "dimension"
+        },
+        "sp-4": {
+          "value": "1rem",
+          "description": "16px. Standard spacing for padding and margins.",
+          "type": "dimension"
+        },
+        "sp-6": {
+          "value": "1.5rem",
+          "description": "24px. Medium spacing for section padding.",
+          "type": "dimension"
+        },
+        "sp-8": {
+          "value": "2rem",
+          "description": "32px. Large spacing for major section separation.",
+          "type": "dimension"
+        }
+      }
+    },
+    "border-radius": {
+      "description": "Border radius tokens.",
+      "values": {
+        "radius": {
+          "value": "0.5rem",
+          "description": "Default border radius for components.",
+          "type": "borderRadius"
+        },
+        "radius-sm": {
+          "value": "calc(0.5rem - 4px)",
+          "description": "Smaller border radius for nested or compact elements.",
+          "type": "borderRadius"
+        },
+        "radius-lg": {
+          "value": "calc(0.5rem + 4px)",
+          "description": "Larger border radius for prominent containers.",
+          "type": "borderRadius"
+        }
+      }
+    }
+  },
+  "components": {
+    "button": {
+      "name": "Button",
+      "description": "An interactive element that triggers an action when activated. Built on a native button element with support for Radix UI Slot composition via asChild.",
+      "status": "stable",
+      "whenToUse": "Use for primary actions, form submissions, dialog confirmations, and any interaction that performs an operation. Choose the variant that matches the action's importance and tone.",
+      "whenNotToUse": "Do not use for navigation between pages or views. Use a Link component or anchor element instead. Do not use for toggling state; use Toggle or Switch.",
+      "props": {
+        "variant": {
+          "type": "enum",
+          "propRole": "choice",
+          "values": [
+            { "value": "default", "description": "Standard button for primary page actions." },
+            { "value": "destructive", "description": "For irreversible actions like delete. Uses destructive color tokens." },
+            { "value": "outline", "description": "Bordered button for secondary actions that need clear affordance." },
+            { "value": "secondary", "description": "De-emphasized button for supplementary actions." },
+            { "value": "ghost", "description": "Minimal button for toolbar actions or inline controls. No background until hovered." },
+            { "value": "link", "description": "Renders as a text link. Use for inline navigation-like actions within prose." }
+          ],
+          "default": "default",
+          "description": "Visual treatment. Use destructive for irreversible actions, ghost for toolbar actions, link for inline text actions."
+        },
+        "size": {
+          "type": "enum",
+          "propRole": "dimension",
+          "values": [
+            { "value": "default", "description": "Standard size, suitable for most contexts." },
+            { "value": "sm", "description": "Compact size for dense UIs or inline actions." },
+            { "value": "lg", "description": "Large size for prominent calls to action." },
+            { "value": "icon", "description": "Square aspect ratio for icon-only buttons." }
+          ],
+          "default": "default",
+          "description": "Button size. Use icon for square icon-only buttons."
+        },
+        "disabled": {
+          "type": "boolean",
+          "propRole": "flag",
+          "default": false,
+          "description": "Whether the button is non-interactive. Conveys that the action is unavailable."
+        },
+        "asChild": {
+          "type": "boolean",
+          "propRole": "flag",
+          "default": false,
+          "description": "When true, merges props and behavior onto the child element instead of rendering a <button>. Used for composing with router Link components."
+        }
+      },
+      "accessibility": {
+        "role": "button",
+        "keyboardInteractions": [
+          { "key": "Enter", "description": "Activates the button." },
+          { "key": "Space", "description": "Activates the button." }
+        ],
+        "labelRequirement": "required-accessible-name",
+        "requiredAttributes": [
+          {
+            "attribute": "aria-label",
+            "condition": "when the button contains only an icon and no visible text",
+            "description": "Provide a text description of the button's action for screen readers."
+          }
+        ]
+      },
+      "constraints": [
+        {
+          "context": "An action that submits a form, confirms a dialog, or triggers a side effect",
+          "rule": "Use Button",
+          "severity": "should"
+        },
+        {
+          "context": "Navigation between pages or views",
+          "rule": "Use a Link component or anchor element instead of Button",
+          "severity": "must-not"
+        },
+        {
+          "context": "Toggling a boolean state (on/off, show/hide)",
+          "rule": "Use Toggle or Switch instead of Button",
+          "severity": "should-not"
+        },
+        {
+          "context": "A destructive or irreversible action",
+          "rule": "Use the destructive variant",
+          "severity": "must"
+        }
+      ],
+      "tokens": ["primary", "primary-foreground", "secondary", "secondary-foreground", "destructive", "destructive-foreground", "border", "ring", "radius"],
+      "relatedComponents": ["toggle"],
+      "tags": ["interactive", "form", "action"],
+      "categories": ["interactive"]
+    },
+    "alert-dialog": {
+      "name": "Alert Dialog",
+      "description": "A modal dialog that interrupts the user with important content and expects a response. Built on Radix UI AlertDialog. Renders with a required action and a cancel option. The user cannot dismiss it by clicking the overlay or pressing Escape — they must choose an explicit action.",
+      "status": "stable",
+      "whenToUse": "Use for confirming destructive or irreversible actions: deleting records, discarding unsaved changes, revoking access. Use when the consequence of proceeding is significant enough that the user should explicitly acknowledge it.",
+      "whenNotToUse": "Do not use for informational messages or non-destructive confirmations. Use Dialog for those. Do not use when the user should be able to dismiss without choosing — that is what Dialog provides.",
+      "props": {
+        "open": {
+          "type": "boolean",
+          "propRole": "state",
+          "description": "Controlled open state of the dialog."
+        },
+        "onOpenChange": {
+          "type": "function",
+          "propRole": "handler",
+          "description": "Callback fired when the open state changes."
+        }
+      },
+      "accessibility": {
+        "role": "alertdialog",
+        "requiredAttributes": [
+          {
+            "attribute": "aria-labelledby",
+            "description": "Must reference the AlertDialogTitle element."
+          },
+          {
+            "attribute": "aria-describedby",
+            "description": "Must reference the AlertDialogDescription element."
+          }
+        ],
+        "keyboardInteractions": [
+          { "key": "Tab", "description": "Moves focus between focusable elements within the dialog. Focus is trapped inside." },
+          { "key": "Escape", "description": "Does NOT close the dialog. User must select an explicit action." },
+          { "key": "Enter", "description": "Activates the focused button." },
+          { "key": "Space", "description": "Activates the focused button." }
+        ],
+        "focusManagement": "On open, focus moves to the cancel button (least destructive action). On close, focus returns to the trigger element. Focus is trapped within the dialog while open.",
+        "labelRequirement": "required-visible"
+      },
+      "composition": {
+        "subComponents": [
+          {
+            "id": "alert-dialog-trigger",
+            "name": "AlertDialogTrigger",
+            "description": "The element that opens the alert dialog.",
+            "required": true,
+            "slot": "trigger",
+            "acceptsChildren": "components",
+            "categories": ["interactive"]
+          },
+          {
+            "id": "alert-dialog-content",
+            "name": "AlertDialogContent",
+            "description": "The container for the dialog's content, rendered in a portal.",
+            "required": true,
+            "slot": "content",
+            "acceptsChildren": "components"
+          },
+          {
+            "id": "alert-dialog-header",
+            "name": "AlertDialogHeader",
+            "description": "Groups the title and description at the top of the dialog.",
+            "slot": "header",
+            "acceptsChildren": "components"
+          },
+          {
+            "id": "alert-dialog-title",
+            "name": "AlertDialogTitle",
+            "description": "The title of the alert dialog. Rendered as an h2. Referenced by aria-labelledby.",
+            "required": true,
+            "acceptsChildren": "text"
+          },
+          {
+            "id": "alert-dialog-description",
+            "name": "AlertDialogDescription",
+            "description": "A description providing additional context about the alert. Referenced by aria-describedby.",
+            "required": true,
+            "acceptsChildren": "text"
+          },
+          {
+            "id": "alert-dialog-footer",
+            "name": "AlertDialogFooter",
+            "description": "Contains the action and cancel buttons.",
+            "slot": "footer",
+            "acceptsChildren": "components"
+          },
+          {
+            "id": "alert-dialog-action",
+            "name": "AlertDialogAction",
+            "description": "The button that confirms the destructive action.",
+            "required": true,
+            "acceptsChildren": "text",
+            "categories": ["interactive"]
+          },
+          {
+            "id": "alert-dialog-cancel",
+            "name": "AlertDialogCancel",
+            "description": "The button that cancels and closes the dialog.",
+            "required": true,
+            "acceptsChildren": "text",
+            "categories": ["interactive"]
+          }
+        ],
+        "notes": "AlertDialogContent must contain AlertDialogTitle and AlertDialogDescription for accessibility. AlertDialogAction and AlertDialogCancel must appear in AlertDialogFooter. Place cancel before confirm in reading order."
+      },
+      "constraints": [
+        {
+          "context": "Confirming a destructive or irreversible action",
+          "rule": "Use AlertDialog instead of Dialog",
+          "severity": "must"
+        },
+        {
+          "context": "Informational messages or non-destructive confirmations",
+          "rule": "Use Dialog instead of AlertDialog",
+          "severity": "must-not"
+        },
+        {
+          "context": "Cases where the user should be able to dismiss without choosing an action",
+          "rule": "Use Dialog instead of AlertDialog",
+          "severity": "must-not"
+        }
+      ],
+      "tokens": ["background", "foreground", "primary", "primary-foreground", "destructive", "destructive-foreground", "border", "radius"],
+      "relatedComponents": ["dialog", "button"],
+      "tags": ["modal", "confirmation", "destructive", "accessibility"],
+      "categories": ["overlay"]
+    },
+    "dialog": {
+      "name": "Dialog",
+      "description": "A modal window that appears over the page content. Built on Radix UI Dialog. Can be dismissed by clicking the overlay, pressing Escape, or activating a close button.",
+      "status": "stable",
+      "whenToUse": "Use for forms, settings panels, detail views, or any content that benefits from focused attention without leaving the current page. Appropriate when the user should be able to dismiss the content without taking an action.",
+      "whenNotToUse": "Do not use for confirming destructive actions. Use AlertDialog instead — it prevents accidental dismissal. Do not use for simple, brief messages; use a toast or inline alert.",
+      "props": {
+        "open": {
+          "type": "boolean",
+          "propRole": "state",
+          "description": "Controlled open state of the dialog."
+        },
+        "onOpenChange": {
+          "type": "function",
+          "propRole": "handler",
+          "description": "Callback fired when the open state changes."
+        },
+        "modal": {
+          "type": "boolean",
+          "propRole": "flag",
+          "default": true,
+          "description": "Whether the dialog blocks interaction with the rest of the page."
+        }
+      },
+      "accessibility": {
+        "role": "dialog",
+        "requiredAttributes": [
+          {
+            "attribute": "aria-labelledby",
+            "description": "Must reference the DialogTitle element."
+          }
+        ],
+        "keyboardInteractions": [
+          { "key": "Tab", "description": "Moves focus between focusable elements within the dialog. Focus is trapped inside." },
+          { "key": "Escape", "description": "Closes the dialog and returns focus to the trigger." },
+          { "key": "Enter", "description": "Activates the focused interactive element." }
+        ],
+        "focusManagement": "On open, focus moves to the first focusable element inside the dialog. On close, focus returns to the trigger element. Focus is trapped within the dialog while open.",
+        "labelRequirement": "required-visible"
+      },
+      "composition": {
+        "subComponents": [
+          {
+            "id": "dialog-trigger",
+            "name": "DialogTrigger",
+            "description": "The element that opens the dialog.",
+            "slot": "trigger",
+            "acceptsChildren": "components",
+            "categories": ["interactive"]
+          },
+          {
+            "id": "dialog-content",
+            "name": "DialogContent",
+            "description": "The container for the dialog's content, rendered in a portal.",
+            "required": true,
+            "slot": "content",
+            "acceptsChildren": "components"
+          },
+          {
+            "id": "dialog-header",
+            "name": "DialogHeader",
+            "description": "Groups the title and description at the top of the dialog.",
+            "slot": "header",
+            "acceptsChildren": "components"
+          },
+          {
+            "id": "dialog-title",
+            "name": "DialogTitle",
+            "description": "The title of the dialog. Referenced by aria-labelledby.",
+            "required": true,
+            "acceptsChildren": "text"
+          },
+          {
+            "id": "dialog-description",
+            "name": "DialogDescription",
+            "description": "A description providing additional context.",
+            "acceptsChildren": "text"
+          },
+          {
+            "id": "dialog-footer",
+            "name": "DialogFooter",
+            "description": "Contains action buttons.",
+            "slot": "footer",
+            "acceptsChildren": "components"
+          },
+          {
+            "id": "dialog-close",
+            "name": "DialogClose",
+            "description": "A button that closes the dialog.",
+            "acceptsChildren": "text",
+            "categories": ["interactive"]
+          }
+        ]
+      },
+      "constraints": [
+        {
+          "context": "Forms, settings panels, or detail views requiring focused attention",
+          "rule": "Use Dialog",
+          "severity": "should"
+        },
+        {
+          "context": "Confirming destructive actions",
+          "rule": "Use AlertDialog instead of Dialog",
+          "severity": "must-not"
+        }
+      ],
+      "tokens": ["background", "foreground", "border", "radius"],
+      "relatedComponents": ["alert-dialog"],
+      "tags": ["modal", "overlay", "form"],
+      "categories": ["overlay"]
+    },
+    "card": {
+      "name": "Card",
+      "description": "A container for grouping related content and actions. Provides visual separation through a bordered surface.",
+      "status": "stable",
+      "whenToUse": "Use to group related information into a distinct visual unit. Appropriate for dashboard widgets, summary panels, list items with detail, or any content that benefits from visual containment.",
+      "whenNotToUse": "Do not nest Cards inside other Cards. If content hierarchy is needed, use headings and spacing within a single Card. Do not use as a clickable element — wrap content in an interactive element instead.",
+      "props": {
+        "className": {
+          "type": "string",
+          "propRole": "content",
+          "description": "Additional CSS classes for customization."
+        }
+      },
+      "composition": {
+        "subComponents": [
+          {
+            "id": "card-header",
+            "name": "CardHeader",
+            "description": "Contains the title and optional description at the top of the card.",
+            "slot": "header",
+            "acceptsChildren": "components"
+          },
+          {
+            "id": "card-title",
+            "name": "CardTitle",
+            "description": "The title of the card.",
+            "acceptsChildren": "text"
+          },
+          {
+            "id": "card-description",
+            "name": "CardDescription",
+            "description": "A description below the title.",
+            "acceptsChildren": "text"
+          },
+          {
+            "id": "card-content",
+            "name": "CardContent",
+            "description": "The main content area of the card.",
+            "slot": "content",
+            "acceptsChildren": "any"
+          },
+          {
+            "id": "card-footer",
+            "name": "CardFooter",
+            "description": "Contains action buttons or supplementary information.",
+            "slot": "footer",
+            "acceptsChildren": "components"
+          }
+        ]
+      },
+      "constraints": [
+        {
+          "context": "Nesting Cards inside other Cards",
+          "rule": "Use headings and spacing within a single Card instead",
+          "severity": "must-not"
+        },
+        {
+          "context": "A clickable surface",
+          "rule": "Wrap Card content in an interactive element; do not make Card itself clickable",
+          "severity": "should-not"
+        }
+      ],
+      "tokens": ["background", "foreground", "border", "radius", "muted", "muted-foreground"],
+      "relatedComponents": ["button"],
+      "tags": ["layout", "container", "surface"]
+    },
+    "input": {
+      "name": "Input",
+      "description": "A single-line text input field built on the native <input> element. Supports all standard HTML input types.",
+      "status": "stable",
+      "whenToUse": "Use for short-form text entry: names, email addresses, search queries, numeric values. Choose the appropriate HTML type attribute for the content (email, password, number, etc.).",
+      "whenNotToUse": "Do not use for multi-line text. Use Textarea instead. Do not use for selecting from a predefined set of options; use Select or RadioGroup.",
+      "props": {
+        "type": {
+          "type": "string",
+          "propRole": "choice",
+          "default": "text",
+          "description": "HTML input type (text, email, password, number, search, etc.)."
+        },
+        "placeholder": {
+          "type": "string",
+          "propRole": "content",
+          "description": "Placeholder text shown when the input is empty."
+        },
+        "disabled": {
+          "type": "boolean",
+          "propRole": "flag",
+          "default": false,
+          "description": "Whether the input is non-interactive."
+        }
+      },
+      "accessibility": {
+        "labelRequirement": "required-visible",
+        "requiredAttributes": [
+          {
+            "attribute": "id",
+            "description": "Required for associating the input with its <label> element via htmlFor."
+          }
+        ],
+        "notes": "Every Input must have an associated <label> element. The label must be visible, not just provided via aria-label. Placeholder text is not a substitute for a label."
+      },
+      "constraints": [
+        {
+          "context": "Multi-line text entry",
+          "rule": "Use Textarea instead of Input",
+          "severity": "must-not"
+        },
+        {
+          "context": "Selecting from a predefined set of options",
+          "rule": "Use Select or RadioGroup instead of Input",
+          "severity": "should-not"
+        }
+      ],
+      "tokens": ["background", "foreground", "border", "ring", "radius-sm"],
+      "relatedComponents": [],
+      "tags": ["form", "input", "text"],
+      "categories": ["interactive"]
+    },
+    "badge": {
+      "name": "Badge",
+      "description": "A small label for categorization, status indication, or metadata. Renders as an inline element.",
+      "status": "experimental",
+      "whenToUse": "Use to display status (active, pending, archived), categories, tags, or counts. Appropriate for metadata that should be scannable at a glance.",
+      "whenNotToUse": "Do not use as a button or interactive element. If the badge should trigger an action, wrap it in a button or use a different component.",
+      "props": {
+        "variant": {
+          "type": "enum",
+          "propRole": "choice",
+          "values": [
+            { "value": "default", "description": "Standard badge for general categorization." },
+            { "value": "secondary", "description": "De-emphasized badge for supplementary metadata." },
+            { "value": "outline", "description": "Bordered badge for subtle labeling." },
+            { "value": "destructive", "description": "Indicates errors or critical status." }
+          ],
+          "default": "default",
+          "description": "Visual treatment. Use destructive to indicate errors or critical status."
+        }
+      },
+      "accessibility": {
+        "labelRequirement": "none",
+        "notes": "Badge is a presentational element. If the badge conveys status that is not also communicated through surrounding text, use aria-label on the badge or ensure the status is programmatically determinable through other means."
+      },
+      "tokens": ["primary", "primary-foreground", "secondary", "secondary-foreground", "destructive", "destructive-foreground", "border"],
+      "relatedComponents": [],
+      "tags": ["display", "status", "label"]
+    },
+    "dropdown-menu": {
+      "name": "Dropdown Menu",
+      "description": "A menu that appears on activation of a trigger element. Built on Radix UI DropdownMenu. Supports items, checkboxes, radio groups, sub-menus, separators, and keyboard navigation.",
+      "status": "stable",
+      "whenToUse": "Use when a set of actions or options needs to be accessible from a single trigger without taking up permanent screen space. Appropriate for overflow menus, context-sensitive actions, and settings with multiple choices.",
+      "whenNotToUse": "Do not use for navigation — use a navigation menu or links. Do not use when the options should always be visible; use RadioGroup or a set of Buttons instead.",
+      "props": {
+        "open": {
+          "type": "boolean",
+          "propRole": "state",
+          "description": "Controlled open state."
+        },
+        "onOpenChange": {
+          "type": "function",
+          "propRole": "handler",
+          "description": "Callback fired when the open state changes."
+        },
+        "modal": {
+          "type": "boolean",
+          "propRole": "flag",
+          "default": true,
+          "description": "Whether the menu blocks interaction with the rest of the page."
+        }
+      },
+      "accessibility": {
+        "role": "menu",
+        "keyboardInteractions": [
+          { "key": "Arrow Down", "description": "Moves focus to the next menu item." },
+          { "key": "Arrow Up", "description": "Moves focus to the previous menu item." },
+          { "key": "Enter", "description": "Activates the focused menu item." },
+          { "key": "Space", "description": "Activates the focused menu item." },
+          { "key": "Escape", "description": "Closes the menu and returns focus to the trigger." }
+        ],
+        "focusManagement": "On open, focus moves to the first menu item. On close, focus returns to the trigger. Arrow keys cycle through items.",
+        "labelRequirement": "required-accessible-name"
+      },
+      "composition": {
+        "subComponents": [
+          {
+            "id": "dropdown-menu-trigger",
+            "name": "DropdownMenuTrigger",
+            "description": "The element that opens the dropdown menu.",
+            "required": true,
+            "slot": "trigger",
+            "acceptsChildren": "components",
+            "categories": ["interactive"]
+          },
+          {
+            "id": "dropdown-menu-content",
+            "name": "DropdownMenuContent",
+            "description": "The container for menu items, rendered in a portal.",
+            "required": true,
+            "slot": "content",
+            "acceptsChildren": "components"
+          },
+          {
+            "id": "dropdown-menu-item",
+            "name": "DropdownMenuItem",
+            "description": "A single actionable item in the menu.",
+            "acceptsChildren": "text",
+            "categories": ["interactive"]
+          },
+          {
+            "id": "dropdown-menu-checkbox-item",
+            "name": "DropdownMenuCheckboxItem",
+            "description": "A menu item that can be toggled on/off.",
+            "acceptsChildren": "text",
+            "categories": ["interactive"]
+          },
+          {
+            "id": "dropdown-menu-radio-group",
+            "name": "DropdownMenuRadioGroup",
+            "description": "Groups radio items for mutually exclusive selection.",
+            "acceptsChildren": "components"
+          },
+          {
+            "id": "dropdown-menu-radio-item",
+            "name": "DropdownMenuRadioItem",
+            "description": "A radio-style menu item for single selection within a group.",
+            "acceptsChildren": "text",
+            "categories": ["interactive"]
+          },
+          {
+            "id": "dropdown-menu-label",
+            "name": "DropdownMenuLabel",
+            "description": "A non-interactive label for grouping menu items.",
+            "acceptsChildren": "text"
+          },
+          {
+            "id": "dropdown-menu-separator",
+            "name": "DropdownMenuSeparator",
+            "description": "A visual divider between groups of items.",
+            "acceptsChildren": "none"
+          },
+          {
+            "id": "dropdown-menu-group",
+            "name": "DropdownMenuGroup",
+            "description": "Groups related menu items together.",
+            "acceptsChildren": "components"
+          },
+          {
+            "id": "dropdown-menu-sub",
+            "name": "DropdownMenuSub",
+            "description": "A container for a sub-menu.",
+            "acceptsChildren": "components"
+          },
+          {
+            "id": "dropdown-menu-sub-trigger",
+            "name": "DropdownMenuSubTrigger",
+            "description": "The item that opens a sub-menu on hover or keyboard navigation.",
+            "acceptsChildren": "text",
+            "categories": ["interactive"]
+          },
+          {
+            "id": "dropdown-menu-sub-content",
+            "name": "DropdownMenuSubContent",
+            "description": "The content container for a sub-menu.",
+            "acceptsChildren": "components"
+          }
+        ]
+      },
+      "tokens": ["background", "foreground", "accent", "muted", "muted-foreground", "border", "radius"],
+      "relatedComponents": ["button"],
+      "tags": ["interactive", "menu", "overlay"],
+      "categories": ["interactive", "overlay"]
+    },
+    "table": {
+      "name": "Table",
+      "description": "A set of primitives for presenting tabular data with a meaningful row-and-column relationship. These are thin, presentational wrappers over the native table elements — Table renders a <table> inside a horizontally scrollable container, and the sub-components render thead, tbody, tfoot, tr, th, td, and caption. There is no built-in sorting, filtering, pagination, or selection; those are composed on top.",
+      "status": "experimental",
+      "whenToUse": "Use to display data where each row is a record and each column is a comparable attribute: members and their roles, invoices, audit logs, permission lists. Reach for Table whenever the relationship between rows and columns carries meaning that assistive technology should be able to announce.",
+      "whenNotToUse": "Do not use Table to lay out or align non-tabular content — use CSS grid or flexbox for layout. Do not use a table to present a single record's key/value pairs; use a description list (dl) or a Card instead. For large interactive datasets, still use these primitives for markup but drive state with a headless table library rather than building a bespoke component.",
+      "accessibility": {
+        "role": "table",
+        "requiredAttributes": [
+          {
+            "attribute": "scope",
+            "condition": "on every TableHead (th) cell",
+            "description": "Set scope=\"col\" for column headers and scope=\"row\" for row headers so screen readers can associate each data cell with its header. Header cells must be th elements, not styled td cells."
+          },
+          {
+            "attribute": "aria-sort",
+            "condition": "on the TableHead (th) of a sortable column",
+            "description": "Reflect the column's current sort state as ascending, descending, or none. Only one column may expose a non-none value at a time so the active sort is unambiguous."
+          },
+          {
+            "attribute": "aria-label",
+            "condition": "when the table has no visible TableCaption and no aria-labelledby reference",
+            "description": "Give the table an accessible name with a literal label string so its purpose is announced when it receives focus or is navigated. Prefer a visible TableCaption where one is appropriate."
+          },
+          {
+            "attribute": "aria-labelledby",
+            "condition": "when the table has no visible TableCaption but an existing on-page heading names it",
+            "description": "Reference the id of the visible element that already names the table, instead of duplicating the name in an aria-label. Use either aria-labelledby or aria-label, not both."
+          }
+        ],
+        "labelRequirement": "required-accessible-name",
+        "notes": "Preserve the native semantic structure: real thead, tbody, tfoot, th, and td elements — never reconstruct a table from styled divs, which strips the row/column semantics screen readers depend on. Do NOT use Table for visual layout, alignment, or positioning; that is the job of CSS grid or flexbox. Provide an accessible name through TableCaption (preferred) or aria-label/aria-labelledby. A sortable column header must be a real Button inside the th, with the th carrying aria-sort, so the control is keyboard-operable and announced as a button."
+      },
+      "composition": {
+        "subComponents": [
+          {
+            "id": "table-header",
+            "name": "TableHeader",
+            "description": "The table's header section, rendered as a thead. Contains the header TableRow whose cells are TableHead elements.",
+            "slot": "header",
+            "acceptsChildren": "components"
+          },
+          {
+            "id": "table-body",
+            "name": "TableBody",
+            "description": "The table's body section, rendered as a tbody. Contains the data TableRows.",
+            "slot": "body",
+            "acceptsChildren": "components"
+          },
+          {
+            "id": "table-footer",
+            "name": "TableFooter",
+            "description": "The table's footer section, rendered as a tfoot. Use for summary rows such as totals.",
+            "slot": "footer",
+            "acceptsChildren": "components"
+          },
+          {
+            "id": "table-row",
+            "name": "TableRow",
+            "description": "A single row, rendered as a tr. Lives inside TableHeader, TableBody, or TableFooter and contains TableHead or TableCell elements.",
+            "acceptsChildren": "components"
+          },
+          {
+            "id": "table-head",
+            "name": "TableHead",
+            "description": "A header cell, rendered as a th. Carries scope and, when its column is sortable, aria-sort and a Button that toggles the sort.",
+            "slot": "columnheader",
+            "acceptsChildren": "any"
+          },
+          {
+            "id": "table-cell",
+            "name": "TableCell",
+            "description": "A data cell, rendered as a td. May contain plain text or interactive controls such as a Badge or a row actions menu.",
+            "acceptsChildren": "any"
+          },
+          {
+            "id": "table-caption",
+            "name": "TableCaption",
+            "description": "An accessible caption, rendered as a caption. Describes the table's contents and supplies its accessible name.",
+            "slot": "caption",
+            "acceptsChildren": "text"
+          }
+        ],
+        "notes": "TableRow must appear inside TableHeader, TableBody, or TableFooter — not directly under Table. Header cells use TableHead (th); data cells use TableCell (td). When present, TableCaption is the first child of Table. These primitives carry no data behavior; compose sorting, filtering, pagination, and selection on top of them."
+      },
+      "constraints": [
+        {
+          "context": "Displaying data with a meaningful row-and-column relationship",
+          "rule": "Use Table with semantic TableHeader/TableBody and TableHead/TableCell elements",
+          "severity": "should"
+        },
+        {
+          "context": "Visual layout, alignment, or positioning of non-tabular content",
+          "rule": "Use CSS grid or flexbox instead of Table",
+          "severity": "must-not"
+        },
+        {
+          "context": "Column and row header cells",
+          "rule": "Use TableHead (th) with an explicit scope attribute rather than a styled TableCell (td)",
+          "severity": "must"
+        },
+        {
+          "context": "A sortable column",
+          "rule": "Expose the sort state with aria-sort on the TableHead and make the trigger a real Button",
+          "severity": "must"
+        },
+        {
+          "context": "Sorting, filtering, pagination, or row selection over large datasets",
+          "rule": "Compose a headless table library such as TanStack Table on top of these primitives instead of hand-rolling the state",
+          "severity": "should"
+        },
+        {
+          "context": "Any data table",
+          "rule": "Give the table an accessible name describing its contents — a TableCaption (preferred), or aria-label/aria-labelledby",
+          "severity": "must"
+        }
+      ],
+      "tokens": ["background", "foreground", "muted", "muted-foreground", "border"],
+      "relatedComponents": ["badge", "button", "dropdown-menu"],
+      "tags": ["data", "table", "tabular", "display"]
+    }
+  },
+  "categories": {
+    "interactive": {
+      "name": "Interactive",
+      "description": "Receives pointer or keyboard activation: buttons, inputs, menu items, and trigger/action/cancel sub-components. Category-based composition rules select by this instead of enumerating ids."
+    },
+    "overlay": {
+      "name": "Overlay",
+      "description": "Renders content in a layer above the page with its own focus and dismiss semantics: dialogs, alert dialogs, dropdown menus."
+    }
+  },
+  "patterns": [
+    {
+      "id": "destructive-action-confirmation",
+      "name": "Destructive Action Confirmation",
+      "description": "A confirmation flow for actions that are irreversible or have significant consequences, using AlertDialog to require explicit user acknowledgment.",
+      "intent": "Prevent accidental data loss or irreversible state changes by requiring the user to explicitly confirm before proceeding.",
+      "context": "Use whenever an action cannot be undone: deleting a record, removing a team member, clearing form data, revoking access, or any operation the user might regret if triggered accidentally.",
+      "components": ["alert-dialog", "button"],
+      "guidance": "Use AlertDialog, not Dialog, for destructive confirmations. The trigger should clearly indicate the destructive nature of the action. Inside the AlertDialog, provide a clear title stating what will happen, a description of the consequences, and two actions: a cancel option and a confirm option. The confirm button MUST use the destructive variant. Place the cancel action before the confirm action in the footer. The description should state specifically what will be affected (e.g., 'This will permanently delete 3 projects and all associated data').",
+      "relatedPatterns": [],
+      "tags": ["confirmation", "destructive", "modal", "safety"]
+    },
+    {
+      "id": "form-field-layout",
+      "name": "Form Field Layout",
+      "description": "Standard arrangement of form controls within a Card container, providing consistent structure for data entry interfaces.",
+      "intent": "Give forms a consistent visual structure that groups related inputs, separates them from surrounding content, and provides clear hierarchy through Card sub-components.",
+      "context": "Use for settings panels, profile editors, checkout flows, or any interface where the user enters structured data across multiple fields.",
+      "components": ["card", "input", "button"],
+      "guidance": "Wrap the form in a Card. Use CardHeader with CardTitle and CardDescription to introduce the form's purpose. Place inputs inside CardContent with consistent vertical spacing (space-y-4 or equivalent). Group related fields together. Place primary actions (submit, save) in CardFooter. Labels should be associated with inputs for accessibility. Required fields should be visually indicated.",
+      "relatedPatterns": ["destructive-action-confirmation"],
+      "tags": ["form", "layout", "data-entry"]
+    },
+    {
+      "id": "contextual-actions-menu",
+      "name": "Contextual Actions Menu",
+      "description": "A pattern for exposing a set of context-sensitive actions through a dropdown menu triggered by an icon button.",
+      "intent": "Keep interfaces clean by collecting secondary or overflow actions behind a single trigger, while maintaining discoverability through a familiar interaction pattern.",
+      "context": "Use for row-level actions in tables or lists, overflow menus in toolbars, or any place where multiple actions apply to a single item but showing all of them inline would be visually noisy.",
+      "components": ["dropdown-menu", "button"],
+      "guidance": "Use a Button with the ghost variant and icon size as the DropdownMenuTrigger. A vertical ellipsis icon is the conventional trigger for contextual menus. Group related actions with DropdownMenuGroup and separate groups with DropdownMenuSeparator. Place destructive actions (delete, remove) at the end of the menu, visually distinguished. Include keyboard shortcuts in DropdownMenuItem when available.",
+      "relatedPatterns": ["destructive-action-confirmation"],
+      "tags": ["actions", "menu", "overflow"]
+    },
+    {
+      "id": "data-table-with-row-actions",
+      "name": "Data Table with Row Actions",
+      "description": "An enterprise data table that presents records with a sortable header, a status column, and a trailing column of per-row actions — including destructive ones routed through a confirmation. Composes the Table primitives with Badge for status, a DropdownMenu (via the contextual-actions-menu pattern) for the actions column, and AlertDialog (via the destructive-action-confirmation pattern) for destructive actions.",
+      "intent": "Let users scan and act on a list of records — reviewing each row's status and reaching its actions — without sacrificing the semantics, keyboard access, or safety guarantees that the underlying components provide.",
+      "context": "Use for access-management and administrative surfaces: a members table, a users-and-roles list, an API-keys table, or any view where each row is an entity with a status and a set of actions, some of which (remove, revoke access) are destructive.",
+      "components": ["table", "badge", "button", "dropdown-menu", "alert-dialog"],
+      "guidance": "Build the table from the Table primitives: a TableHeader row of TableHead cells, a TableBody of one TableRow per record, and a TableCaption (or aria-label) naming the table. Make sortable columns real controls — render a ghost Button inside the TableHead and set aria-sort on that TableHead to ascending, descending, or none, with only one column sorted at a time. Render the status column with a Badge whose variant reflects state (for example default or secondary for active and pending, destructive for suspended or revoked); because Badge is presentational, keep the status readable as text so it is announced by assistive technology, not conveyed by color alone. Put per-row actions in a trailing TableCell as a contextual-actions-menu: a ghost icon Button (a vertical ellipsis) as the DropdownMenuTrigger opening a DropdownMenu of actions, with an aria-label on the trigger. Route every destructive row action — remove, revoke access — through the destructive-action-confirmation pattern using AlertDialog, never Dialog, so the action cannot be dismissed by accident; the AlertDialogDescription should name the specific record affected (for example 'This revokes Jordan Lee's access to the Acme workspace'). Do not make the entire TableRow a single clickable target while it also contains its own action controls — that is the nested-interactive-elements anti-pattern, which produces ambiguous click targets and unpredictable behavior for keyboard and screen-reader users; if rows need a primary navigation, expose it as a distinct link or cell control rather than wrapping the row.",
+      "relatedPatterns": ["contextual-actions-menu", "destructive-action-confirmation"],
+      "tags": ["table", "data", "actions", "access-management", "destructive"]
+    }
+  ],
+  "antiPatterns": [
+    {
+      "id": "dialog-for-destructive-actions",
+      "name": "Using Dialog for Destructive Confirmations",
+      "description": "Using the dismissible Dialog component instead of AlertDialog when confirming a destructive or irreversible action.",
+      "reason": "Dialog can be dismissed by clicking the overlay or pressing Escape, which means a user can accidentally bypass the confirmation without making a conscious choice. AlertDialog forces the user to select an explicit action (confirm or cancel), providing a stronger safeguard against accidental destructive operations. This distinction also matters for accessibility: screen readers announce AlertDialog with greater urgency.",
+      "severity": "must-not",
+      "insteadUse": "destructive-action-confirmation",
+      "components": ["dialog", "alert-dialog"],
+      "tags": ["modal", "destructive", "accessibility"]
+    },
+    {
+      "id": "nested-interactive-elements",
+      "name": "Nesting Interactive Elements",
+      "description": "Placing a clickable or focusable element (Button, Link, Input) inside another clickable element (a clickable Card, a Button, or a Link).",
+      "reason": "Nested interactive elements create ambiguous click targets and are a significant accessibility violation. Screen readers cannot determine user intent when interactive elements are nested, and the resulting behavior varies unpredictably across browsers. The outer element may intercept clicks intended for the inner element, or both may fire, leading to unexpected navigation or duplicate actions.",
+      "severity": "must-not",
+      "components": ["button", "card", "input"],
+      "tags": ["accessibility", "interaction", "html-semantics"]
+    },
+    {
+      "id": "div-as-button",
+      "name": "Using a Styled Div as a Button",
+      "description": "Creating a clickable element by adding an onClick handler and visual styles to a <div> or <span> instead of using the Button component or a native <button> element.",
+      "reason": "A styled div lacks keyboard accessibility (not focusable by default, does not respond to Enter or Space), is not announced as a button by screen readers, and does not participate in form submission. The Button component handles all of these concerns. Using a div requires manually re-implementing focus management, keyboard handling, and ARIA attributes — work that is error-prone and already solved by the component.",
+      "severity": "must-not",
+      "components": ["button"],
+      "tags": ["accessibility", "semantics", "component-misuse"]
+    }
+  ],
+  "intents": [
+    {
+      "id": "destructive-action",
+      "name": "Destructive action",
+      "description": "The requested UI performs an irreversible or high-consequence operation: deleting records or accounts, revoking access, removing members.",
+      "relatedPatterns": ["destructive-action-confirmation"]
+    },
+    {
+      "id": "record-collection",
+      "name": "Record collection",
+      "description": "Surfaces that present many records of the same kind — support tickets, orders, members — for scanning and action. Records share uniform fields, so the collection renders as a semantic data table built from the Table primitives; status stays readable as text (badges are appropriate, color is never the only signal). Per-row actions and destructive confirmations follow the data-table-with-row-actions pattern as guidance until the dropdown-menu item vocabulary is specified.",
+      "relatedPatterns": ["data-table-with-row-actions"]
+    }
+  ],
+  "rules": [
+    {
+      "id": "rule.destructive-requires-alertdialog",
+      "type": "component-choice",
+      "severity": "must",
+      "appliesTo": { "intents": ["destructive-action"] },
+      "require": ["alert-dialog"],
+      "forbid": ["dialog"],
+      "rationale": "Dialog can be dismissed by clicking the overlay or pressing Escape, so a user can bypass a destructive confirmation without making a conscious choice. AlertDialog forces an explicit confirm/cancel decision and is announced with greater urgency by screen readers.",
+      "examples": ["ex.delete-account-confirmation"],
+      "tags": ["safety", "accessibility"]
+    },
+    {
+      "id": "rule.alertdialog-requires-cancel",
+      "type": "required-composition",
+      "severity": "must",
+      "component": "alert-dialog",
+      "requiredSubComponents": [
+        { "id": "alert-dialog-cancel", "min": 1 },
+        { "id": "alert-dialog-title", "min": 1 }
+      ],
+      "rationale": "A confirmation without an explicit cancel action and a title naming the consequence funnels the user toward the destructive action; the title is also required for aria-labelledby.",
+      "examples": ["ex.delete-account-confirmation"],
+      "tags": ["safety", "accessibility"]
+    },
+    {
+      "id": "rule.button-no-interactive-descendants",
+      "type": "forbidden-composition",
+      "severity": "must",
+      "component": "button",
+      "forbiddenDescendants": ["button", "input"],
+      "rationale": "Nested interactive elements create ambiguous click targets and are an accessibility violation: screen readers cannot determine intent and click handling varies across browsers.",
+      "examples": ["ex.delete-account-confirmation"],
+      "tags": ["accessibility", "interaction"]
+    },
+    {
+      "id": "rule.trigger-carries-label",
+      "type": "required-props",
+      "severity": "must",
+      "component": "alert-dialog-trigger",
+      "requiredText": true,
+      "textScope": "subtree",
+      "rationale": "The trigger must present an accessible label: non-empty text somewhere under the trigger. Protocol projections lift the label from the trigger's subtree (preferring a label-bearing button; lifts are audited) — a trigger with no label text anywhere yields a control with no accessible name and an instance downstream emitters must refuse.",
+      "examples": ["ex.delete-account-confirmation"],
+      "tags": ["accessibility", "projection"]
+    },
+    {
+      "id": "rule.alertdialog-no-nested-overlays",
+      "type": "forbidden-composition",
+      "severity": "must",
+      "component": "alert-dialog",
+      "forbiddenCategories": ["overlay"],
+      "rationale": "An alert dialog is a single focused interruption. Stacking another overlay (dialog, dropdown menu, another alert dialog) inside it breaks focus containment and dismiss semantics and buries the confirmation decision under a second layer.",
+      "tags": ["accessibility", "interaction"]
+    },
+    {
+      "id": "rule.record-collection-requires-table",
+      "type": "component-choice",
+      "severity": "must",
+      "appliesTo": { "intents": ["record-collection"] },
+      "require": ["table"],
+      "rationale": "The data-table-with-row-actions pattern: a record collection is built from the Table primitives, not prose or ad-hoc stacks. Records share uniform fields; a semantic table is how they stay scannable, sortable, and navigable by assistive technology.",
+      "examples": ["ex.support-ticket-queue"],
+      "tags": ["structure"]
+    },
+    {
+      "id": "rule.table-carries-structure",
+      "type": "required-composition",
+      "severity": "must",
+      "appliesTo": { "intents": ["record-collection"] },
+      "component": "table",
+      "requiredSubComponents": [
+        { "id": "table-header", "min": 1 },
+        { "id": "table-body", "min": 1 }
+      ],
+      "rationale": "The table's own constraints demand semantic structure: header cells as th within a TableHeader so screen readers can associate columns, and records inside a TableBody. A table without both is a grid of divs wearing table styling.",
+      "examples": ["ex.support-ticket-queue"],
+      "tags": ["structure", "accessibility"]
+    },
+    {
+      "id": "rule.table-carries-caption",
+      "type": "required-composition",
+      "severity": "must",
+      "appliesTo": { "intents": ["record-collection"] },
+      "component": "table",
+      "requiredSubComponents": [{ "id": "table-caption", "min": 1 }],
+      "rationale": "The data-table-with-row-actions pattern requires an accessible name via TableCaption or an aria-label. The pattern permits either; the contract can only govern the declarative form, so the caption is the enforceable floor — an aria-label alternative is legitimate but inexpressible in current rule types and remains guidance.",
+      "examples": ["ex.support-ticket-queue"],
+      "tags": ["accessibility"]
+    }
+  ],
+  "examples": [
+    {
+      "id": "ex.delete-account-confirmation",
+      "intent": "destructive-action",
+      "name": "Delete account confirmation",
+      "prompt": "a screen to delete my account",
+      "description": "Card with a destructive entry point; AlertDialog confirmation with explicit consequence text, cancel-before-confirm, destructive confirm variant.",
+      "surface": {
+        "dspackSurface": "0.1",
+        "system": "shadcn/ui",
+        "intent": "destructive-action",
+        "root": {
+          "component": "card",
+          "children": [
+            {
+              "component": "alert-dialog",
+              "children": [
+                {
+                  "component": "alert-dialog-trigger",
+                  "children": [
+                    {
+                      "component": "button",
+                      "props": { "variant": "destructive" },
+                      "text": "Delete account"
+                    }
+                  ]
+                },
+                {
+                  "component": "alert-dialog-content",
+                  "children": [
+                    { "component": "alert-dialog-title", "text": "Delete your account?" },
+                    {
+                      "component": "alert-dialog-description",
+                      "text": "This will permanently delete your account and all associated data. This action cannot be undone."
+                    },
+                    {
+                      "component": "alert-dialog-footer",
+                      "children": [
+                        { "component": "alert-dialog-cancel", "text": "Cancel" },
+                        { "component": "alert-dialog-action", "text": "Delete account" }
+                      ]
+                    }
+                  ]
+                }
+              ]
+            }
+          ]
+        }
+      }
+    },
+    {
+      "id": "ex.support-ticket-queue",
+      "intent": "record-collection",
+      "name": "Support ticket queue",
+      "prompt": "a queue of open support tickets with status and priority",
+      "description": "A semantic data table from the Table primitives: a caption naming the collection, header cells for column association, and ticket rows in the body. Status renders as a Badge whose text stays readable — the variant reflects state, color is never the only signal.",
+      "surface": {
+        "dspackSurface": "0.1",
+        "system": "shadcn/ui",
+        "intent": "record-collection",
+        "root": {
+          "component": "table",
+          "children": [
+            { "component": "table-caption", "text": "Open support tickets, newest first." },
+            {
+              "component": "table-header",
+              "children": [
+                {
+                  "component": "table-row",
+                  "children": [
+                    { "component": "table-head", "text": "Ticket" },
+                    { "component": "table-head", "text": "Subject" },
+                    { "component": "table-head", "text": "Status" },
+                    { "component": "table-head", "text": "Priority" }
+                  ]
+                }
+              ]
+            },
+            {
+              "component": "table-body",
+              "children": [
+                {
+                  "component": "table-row",
+                  "children": [
+                    { "component": "table-cell", "text": "#4812" },
+                    { "component": "table-cell", "text": "Cannot export billing statement" },
+                    {
+                      "component": "table-cell",
+                      "children": [{ "component": "badge", "props": { "variant": "destructive" }, "text": "Urgent" }]
+                    },
+                    { "component": "table-cell", "text": "P1" }
+                  ]
+                },
+                {
+                  "component": "table-row",
+                  "children": [
+                    { "component": "table-cell", "text": "#4809" },
+                    { "component": "table-cell", "text": "Two-factor codes arrive late" },
+                    {
+                      "component": "table-cell",
+                      "children": [{ "component": "badge", "props": { "variant": "secondary" }, "text": "Waiting on customer" }]
+                    },
+                    { "component": "table-cell", "text": "P2" }
+                  ]
+                },
+                {
+                  "component": "table-row",
+                  "children": [
+                    { "component": "table-cell", "text": "#4801" },
+                    { "component": "table-cell", "text": "Dark mode contrast on invoices" },
+                    {
+                      "component": "table-cell",
+                      "children": [{ "component": "badge", "props": { "variant": "outline" }, "text": "Open" }]
+                    },
+                    { "component": "table-cell", "text": "P3" }
+                  ]
+                }
+              ]
+            }
+          ]
+        }
+      }
+    }
+  ],
+  "frameworkBindings": {
+    "react": {
+      "name": "React",
+      "package": "shadcn/ui",
+      "installCommand": "npx shadcn@latest init",
+      "description": "React components built with Radix UI primitives and styled with Tailwind CSS. Components are copied into your project source rather than imported from a package — you own and can modify the code.",
+      "guidance": "Run 'npx shadcn@latest init' to set up the project, then add individual components with 'npx shadcn@latest add <component>'. Components are placed in your project (typically src/components/ui/ or components/ui/) and can be freely modified. Tailwind CSS v4 and a path alias (usually @/) are expected.",
+      "components": {
+        "button": {
+          "importPath": "@/components/ui/button",
+          "installCommand": "npx shadcn@latest add button",
+          "exportName": "Button",
+          "guidance": "Uses class-variance-authority (cva) for variant styles. Supports Radix UI Slot via the asChild prop for composing with router Link components."
+        },
+        "alert-dialog": {
+          "importPath": "@/components/ui/alert-dialog",
+          "installCommand": "npx shadcn@latest add alert-dialog",
+          "guidance": "Built on @radix-ui/react-alert-dialog.",
+          "subComponents": {
+            "alert-dialog-trigger": { "exportName": "AlertDialogTrigger" },
+            "alert-dialog-content": { "exportName": "AlertDialogContent" },
+            "alert-dialog-header": { "exportName": "AlertDialogHeader" },
+            "alert-dialog-title": { "exportName": "AlertDialogTitle" },
+            "alert-dialog-description": { "exportName": "AlertDialogDescription" },
+            "alert-dialog-footer": { "exportName": "AlertDialogFooter" },
+            "alert-dialog-action": { "exportName": "AlertDialogAction" },
+            "alert-dialog-cancel": { "exportName": "AlertDialogCancel" }
+          }
+        },
+        "dialog": {
+          "importPath": "@/components/ui/dialog",
+          "installCommand": "npx shadcn@latest add dialog",
+          "guidance": "Built on @radix-ui/react-dialog.",
+          "subComponents": {
+            "dialog-trigger": { "exportName": "DialogTrigger" },
+            "dialog-content": { "exportName": "DialogContent" },
+            "dialog-header": { "exportName": "DialogHeader" },
+            "dialog-title": { "exportName": "DialogTitle" },
+            "dialog-description": { "exportName": "DialogDescription" },
+            "dialog-footer": { "exportName": "DialogFooter" },
+            "dialog-close": { "exportName": "DialogClose" }
+          }
+        },
+        "card": {
+          "importPath": "@/components/ui/card",
+          "installCommand": "npx shadcn@latest add card",
+          "guidance": "Pure HTML/CSS components — no Radix dependency.",
+          "subComponents": {
+            "card-header": { "exportName": "CardHeader" },
+            "card-title": { "exportName": "CardTitle" },
+            "card-description": { "exportName": "CardDescription" },
+            "card-content": { "exportName": "CardContent" },
+            "card-footer": { "exportName": "CardFooter" }
+          }
+        },
+        "input": {
+          "importPath": "@/components/ui/input",
+          "installCommand": "npx shadcn@latest add input",
+          "exportName": "Input",
+          "guidance": "A styled native <input> element. Forwards all standard HTML input attributes via React.forwardRef."
+        },
+        "badge": {
+          "importPath": "@/components/ui/badge",
+          "installCommand": "npx shadcn@latest add badge",
+          "exportName": "Badge",
+          "guidance": "Uses cva for variant styles. Renders as a <div> by default."
+        },
+        "dropdown-menu": {
+          "importPath": "@/components/ui/dropdown-menu",
+          "installCommand": "npx shadcn@latest add dropdown-menu",
+          "guidance": "Built on @radix-ui/react-dropdown-menu.",
+          "subComponents": {
+            "dropdown-menu-trigger": { "exportName": "DropdownMenuTrigger" },
+            "dropdown-menu-content": { "exportName": "DropdownMenuContent" },
+            "dropdown-menu-item": { "exportName": "DropdownMenuItem" },
+            "dropdown-menu-checkbox-item": { "exportName": "DropdownMenuCheckboxItem" },
+            "dropdown-menu-radio-group": { "exportName": "DropdownMenuRadioGroup" },
+            "dropdown-menu-radio-item": { "exportName": "DropdownMenuRadioItem" },
+            "dropdown-menu-label": { "exportName": "DropdownMenuLabel" },
+            "dropdown-menu-separator": { "exportName": "DropdownMenuSeparator" },
+            "dropdown-menu-group": { "exportName": "DropdownMenuGroup" },
+            "dropdown-menu-sub": { "exportName": "DropdownMenuSub" },
+            "dropdown-menu-sub-trigger": { "exportName": "DropdownMenuSubTrigger" },
+            "dropdown-menu-sub-content": { "exportName": "DropdownMenuSubContent" }
+          }
+        },
+        "table": {
+          "importPath": "@/components/ui/table",
+          "installCommand": "npx shadcn@latest add table",
+          "guidance": "Pure HTML/CSS table primitives — no Radix dependency. Table renders a <table> wrapped in a horizontally scrollable container; the sub-components map directly to the native thead, tbody, tfoot, tr, th, td, and caption elements. The primitives are presentational only: sorting, filtering, pagination, and row selection are typically composed with TanStack Table (@tanstack/react-table) on top of them, where the headless library owns the data state and these components render the resulting rows and cells.",
+          "subComponents": {
+            "table-header": { "exportName": "TableHeader" },
+            "table-body": { "exportName": "TableBody" },
+            "table-footer": { "exportName": "TableFooter" },
+            "table-row": { "exportName": "TableRow" },
+            "table-head": { "exportName": "TableHead" },
+            "table-cell": { "exportName": "TableCell" },
+            "table-caption": { "exportName": "TableCaption" }
+          }
+        }
+      }
+    }
+  },
+  "themes": {
+    "dark": {
+      "name": "Dark",
+      "description": "Dark theme for low-light environments. Inverts the primary background/foreground relationship and adjusts accent colors for sufficient contrast on dark surfaces.",
+      "overrides": {
+        "color.background": "hsl(222.2, 84%, 4.9%)",
+        "color.foreground": "hsl(210, 40%, 98%)",
+        "color.primary": "hsl(210, 40%, 98%)",
+        "color.primary-foreground": "hsl(222.2, 47.4%, 11.2%)",
+        "color.secondary": "hsl(217.2, 32.6%, 17.5%)",
+        "color.secondary-foreground": "hsl(210, 40%, 98%)",
+        "color.muted": "hsl(217.2, 32.6%, 17.5%)",
+        "color.muted-foreground": "hsl(215, 20.2%, 65.1%)",
+        "color.accent": "hsl(217.2, 32.6%, 17.5%)",
+        "color.destructive": "hsl(0, 62.8%, 30.6%)",
+        "color.destructive-foreground": "hsl(210, 40%, 98%)",
+        "color.border": "hsl(217.2, 32.6%, 17.5%)",
+        "color.ring": "hsl(212.7, 26.8%, 83.9%)"
+      }
+    }
+  },
+  "layout": {
+    "breakpoints": {
+      "sm": { "minWidth": "640px", "description": "Small devices and large phones in landscape." },
+      "md": { "minWidth": "768px", "description": "Tablets." },
+      "lg": { "minWidth": "1024px", "description": "Small desktops and laptops." },
+      "xl": { "minWidth": "1280px", "description": "Standard desktops." },
+      "2xl": { "minWidth": "1536px", "description": "Large desktops." }
+    },
+    "grid": {
+      "columns": 12,
+      "gutter": "1rem",
+      "description": "Use the 12-column grid for page-level layout. Component-level layout should use flexbox or CSS grid directly."
+    },
+    "containers": {
+      "default": { "maxWidth": "1280px", "description": "Standard content container for most pages." },
+      "narrow": { "maxWidth": "768px", "description": "For focused reading experiences, forms, and auth flows." },
+      "wide": { "maxWidth": "1536px", "description": "For data-dense views like dashboards and admin panels." }
+    },
+    "spacingScale": {
+      "baseUnit": "0.25rem",
+      "description": "Spacing follows a 4px (0.25rem) base unit. Use multiples: 1 (4px), 2 (8px), 3 (12px), 4 (16px), 5 (20px), 6 (24px), 8 (32px), 10 (40px), 12 (48px), 16 (64px)."
+    }
+  }
+}
diff --git a/src/tests/generation-context-golden.test.ts b/src/tests/generation-context-golden.test.ts
index 9226ddf..26955f0 100644
--- a/src/tests/generation-context-golden.test.ts
+++ b/src/tests/generation-context-golden.test.ts
@@ -6,8 +6,19 @@
  * JSON serialization (the wire shape an MCP client receives). The golden is
  * a byte-synced copy of dspack-gen's own compiler golden
  * (fixtures/golden/context/shadcn.destructive-action.json, tracked in
- * scripts/check-sync.mjs), compiled from the same shadcn v0.4 contract this
- * repo carries as examples/shadcn-ui-v04.dspack.json.
+ * scripts/check-sync.mjs), compiled from dspack-gen's own contract fixture —
+ * carried here as the byte-synced shadcn.v0_4.contract.json.
+ *
+ * "The same contract" is load-bearing, and it used to be implicit: this read
+ * the golden against examples/shadcn-ui-v04.dspack.json, which happened to
+ * hold content identical to dspack-gen's fixture. That coincidence ended
+ * when the spec repo's example advanced to 3.2.0 (34 components, 49 rules)
+ * while dspack-gen's fixture stayed at 2.3.0 (8 components, 8 rules), and
+ * the byte comparison began failing for a reason that had nothing to do
+ * with the compiler. Reading the compiler's own input keeps this a test of
+ * vendored-core semantics; the shipped example is exercised by
+ * generation-tools.test.ts instead. When dspack-gen advances its fixture,
+ * check-sync pulls contract and golden together and this still holds.
  *
  * This is deliberate pinned-semantics coupling, the same posture as the F1
  * lint goldens: if the vendored core's generation schema drifts from the
@@ -28,7 +39,7 @@ import { getGenerationContext } from '../tools/get-generation-context.js';
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const root = join(__dirname, '..', '..');
 
-const doc = loadDspack(join(root, 'examples', 'shadcn-ui-v04.dspack.json'));
+const doc = loadDspack(join(root, 'src', 'tests', 'fixtures', 'shadcn.v0_4.contract.json'));
 const golden = JSON.parse(
   readFileSync(join(root, 'src', 'tests', 'fixtures', 'shadcn.destructive-action.context.json'), 'utf-8'),
 ) as { system: string; schema: unknown; fewshot: unknown };
diff --git a/src/tests/generation-tools.test.ts b/src/tests/generation-tools.test.ts
index f09e776..88c8e07 100644
--- a/src/tests/generation-tools.test.ts
+++ b/src/tests/generation-tools.test.ts
@@ -2,11 +2,17 @@
  * PR-11 acceptance gates: get-generation-context + validate-ui.
  *
  * Fixture provenance (byte copies, drift tracked in dspack-gen#7):
- * - examples/shadcn-ui-v04.dspack.json    == dspack-gen fixtures/shadcn.v0_4.dspack.json
- *                                         == dspack examples/shadcn-ui.dspack.json
+ * - examples/shadcn-ui-v04.dspack.json    == dspack examples/shadcn-ui.dspack.json
  * - src/tests/fixtures/F1-*.dsurface.json == dspack-gen fixtures/golden/violating/F1-*
  * - src/tests/fixtures/F1-*.expected.json == dspack-gen's golden lint report for F1
  *
+ * The shipped example tracks the SPEC repo, and is the contract exercised
+ * here. It is no longer byte-equal to dspack-gen's fixture: the spec repo
+ * advanced to 3.2.0 while dspack-gen's fixture stayed at 2.3.0, so the
+ * compiler golden is paired with its own copy of that older contract (see
+ * generation-context-golden.test.ts). The F1 lint goldens hold against
+ * both, because F1 exercises rules present in each.
+ *
  * The golden equality below is deliberate validator-semantics coupling:
  * validate-ui MUST return exactly what dspack-gen's linter returns — if the
  * pinned dependency's semantics drift from the golden, this fails loudly.
@@ -91,9 +97,15 @@ test('validate-ui evaluates v0.4 rule types (required-props, as amended) through
     },
   });
 
-  // The 2026-07-03 signature shape (label nested in a badge): clean under the amendment.
+  // Label below the trigger rather than on it: clean under the amendment.
+  // The label sits on the button, not on a nested badge as it did before the
+  // contract reached 3.2.0 — that release added rule.button-carries-text
+  // (required-props, default `self` scope), under which a button whose only
+  // text lives in a descendant is itself a violation. The trigger still
+  // carries no text of its own, so this is still exactly what textScope:
+  // subtree buys: the label is projected up from the subtree.
   const nested = validateUi(doc, {
-    surface: surfaceWithTrigger([{ component: 'button', children: [{ component: 'badge', text: 'Delete' }] }]),
+    surface: surfaceWithTrigger([{ component: 'button', text: 'Delete', children: [{ component: 'badge' }] }]),
   });
   assert.ok(nested.found, 'expected found');
   assert.equal(nested.result.report.pass, true);