@utopia-studio-design/design-system-cli 0.1.0 → 0.2.0

package/data/manifests/components.json

@@ -0,0 +1,4780 @@
+{
+  "components": [
+    {
+      "name": "Accordion",
+      "category": "Disclosure",
+      "status": "available",
+      "packageImport": "import { Accordion, AccordionContent, AccordionItem, AccordionTrigger } from '@utopia-studio-design/design-system/Accordion';",
+      "sourcePath": "packages/design-system/src/components/ShadcnPrimitives.tsx",
+      "shadcnFoundation": [
+        "accordion",
+        "Radix Accordion",
+        "shadcn/ui registry",
+        "semantic Utopia wrapper"
+      ],
+      "fallbackToShadcn": "accordion",
+      "requiredTokens": [
+        "--surface",
+        "--surface-hover",
+        "--foreground",
+        "--muted-foreground",
+        "--border",
+        "--radius-surface",
+        "--space-3",
+        "--space-4",
+        "--focus-ring-width",
+        "--motion-duration-expand",
+        "--motion-ease-standard"
+      ],
+      "useWhen": [
+        "A sectioned disclosure list needs keyboard-accessible expand/collapse behavior",
+        "FAQ, settings, or docs content should stay on one page",
+        "One or multiple panels can be open using Radix Accordion semantics"
+      ],
+      "avoidWhen": [
+        "A single disclosure is enough; use Collapsible",
+        "The content is primary navigation; use Side Nav Section",
+        "Opening a panel should route to another page"
+      ],
+      "neverInvent": [
+        "Custom disclosure keyboard behavior",
+        "Raw shadcn theme colors",
+        "Left/right-only indicator placement",
+        "Utopia brand primitives inside reusable component logic",
+        "Motion that bypasses MotionProvider or prefers-reduced-motion"
+      ],
+      "ai": {
+        "props": {
+          "type": "Use single for one open item, multiple for independent open items.",
+          "collapsible": "Allow the active single item to close when the content is optional.",
+          "AccordionItem": "Requires a stable value for Radix state.",
+          "AccordionTrigger": "Visible section title and full hit target.",
+          "AccordionContent": "Panel body. Keep product copy supplied by the app.",
+          "motion": "Optional boolean. Defaults to the MotionProvider policy and disables this component pattern when false."
+        },
+        "arabicFriendly": "Trigger text uses start alignment and indicator sits at inline-end. In dir=\"rtl\", spacing and hit target must mirror without left/right CSS."
+      }
+    },
+    {
+      "name": "Account Status",
+      "category": "Data Display",
+      "status": "available",
+      "packageImport": "import { AccountStatus } from '@utopia-studio-design/design-system/DataDisplay';",
+      "sourcePath": "packages/design-system/src/components/DataDisplay.tsx",
+      "shadcnFoundation": [
+        "avatar",
+        "Radix Avatar",
+        "semantic account/status wrapper",
+        "semantic Utopia wrapper"
+      ],
+      "fallbackToShadcn": "avatar",
+      "requiredTokens": [
+        "--foreground",
+        "--muted-foreground",
+        "--radius-control",
+        "--nav-item-height",
+        "--space-2",
+        "--font-size-supporting",
+        "--line-height-supporting"
+      ],
+      "useWhen": [
+        "Showing a signed-in user, workspace, or account status in Top Nav or Side Nav",
+        "A compact identity row needs Avatar plus label and optional description",
+        "Collapsed side navigation should keep the avatar visible while hiding text"
+      ],
+      "avoidWhen": [
+        "Decorative fake people are needed",
+        "A logo or product mark should use brand assets instead",
+        "A full profile card or account menu is required"
+      ],
+      "neverInvent": [
+        "Fake user identity or status copy",
+        "Background surfaces by default",
+        "Left/right-only layout rules",
+        "Utopia brand primitives inside reusable component logic"
+      ],
+      "ai": {
+        "props": {
+          "avatar": "Optional custom Avatar node. Prefer the design-system Avatar component.",
+          "avatarAlt": "Accessible text for the fallback avatar when avatar is not supplied.",
+          "avatarSrc": "Optional avatar image source.",
+          "avatarFallback": "Fallback initials passed to Avatar.",
+          "label": "Required account, user, workspace, or organization label.",
+          "description": "Optional status, plan, role, or workspace metadata.",
+          "endContent": "Optional trailing status or menu affordance."
+        },
+        "usage": "Use AccountStatus in Top Nav or Side Nav footer. Keep background transparent by default and let the parent surface own framing."
+      }
+    },
+    {
+      "name": "Alert",
+      "category": "Feedback",
+      "status": "available",
+      "packageImport": "import { Alert, AlertDescription, AlertTitle } from '@utopia-studio-design/design-system/Alert';",
+      "sourcePath": "packages/design-system/src/components/ShadcnPrimitives.tsx",
+      "shadcnFoundation": [
+        "alert",
+        "shadcn/ui registry",
+        "semantic status surface",
+        "semantic Utopia wrapper"
+      ],
+      "fallbackToShadcn": "alert",
+      "requiredTokens": [
+        "--surface",
+        "--foreground",
+        "--muted-foreground",
+        "--border",
+        "--radius-surface",
+        "--space-1",
+        "--space-3",
+        "--space-4",
+        "--space-5",
+        "--success",
+        "--success-foreground",
+        "--success-surface",
+        "--success-border",
+        "--success-text",
+        "--warning",
+        "--warning-foreground",
+        "--warning-surface",
+        "--warning-border",
+        "--warning-text",
+        "--destructive",
+        "--destructive-surface",
+        "--destructive-border",
+        "--destructive-text",
+        "--focus-ring-width"
+      ],
+      "useWhen": [
+        "Inline status or system notices need to be announced",
+        "A warning or destructive state should stay in context",
+        "Feedback should not block the user"
+      ],
+      "avoidWhen": [
+        "A blocking confirmation is required; use Alert Dialog",
+        "The message is purely decorative",
+        "The notice needs product-specific localization rules inside the component"
+      ],
+      "neverInvent": [
+        "Product alert copy",
+        "Raw shadcn theme colors",
+        "Left/right-only layout rules",
+        "Utopia brand primitives inside reusable component logic"
+      ],
+      "ai": {
+        "props": {
+          "variant": "Use default, info, success, warning, or destructive. The variant selects the default icon and tokenized status emphasis.",
+          "showIcon": "Defaults to true. Set false for text-only alerts when nearby UI already communicates the status.",
+          "icon": "Optional ReactNode override. Prefer semantic, non-directional lucide icons unless the alert meaning requires direction.",
+          "tone": "Backward-compatible alias for variant. Prefer variant in new code.",
+          "AlertTitle": "Short status headline.",
+          "AlertDescription": "Supporting details; product owns wording and localization."
+        },
+        "arabicFriendly": "Use logical spacing and product-supplied localized copy. Mixed Arabic/English text must wrap without overlapping action or icon slots."
+      }
+    },
+    {
+      "name": "Alert Dialog",
+      "category": "Feedback",
+      "status": "available",
+      "packageImport": "import { AlertDialog, AlertDialogAction, AlertDialogCancel, AlertDialogContent, AlertDialogDescription, AlertDialogFooter, AlertDialogHeader, AlertDialogTitle, AlertDialogTrigger } from '@utopia-studio-design/design-system/AlertDialog';",
+      "sourcePath": "packages/design-system/src/components/ShadcnPrimitives.tsx",
+      "shadcnFoundation": [
+        "alert-dialog",
+        "Radix AlertDialog",
+        "shadcn/ui registry",
+        "semantic Utopia wrapper"
+      ],
+      "fallbackToShadcn": "alert-dialog",
+      "requiredTokens": [
+        "--surface",
+        "--foreground",
+        "--muted-foreground",
+        "--border",
+        "--radius-surface",
+        "--radius-control",
+        "--primary",
+        "--primary-foreground",
+        "--secondary",
+        "--secondary-foreground",
+        "--z-overlay",
+        "--z-modal",
+        "--focus-ring-width",
+        "--overlay",
+        "--modal-surface",
+        "--motion-duration-reveal",
+        "--motion-ease-emphasized"
+      ],
+      "useWhen": [
+        "Destructive confirmations",
+        "Irreversible decisions",
+        "Blocking choices that require explicit acknowledgement and focus trapping"
+      ],
+      "avoidWhen": [
+        "Inline status would be enough",
+        "The action can be undone without confirmation",
+        "The dialog copy is not localized or verified"
+      ],
+      "neverInvent": [
+        "Unreviewed destructive copy",
+        "Raw shadcn theme colors",
+        "Left/right-only footer ordering",
+        "Utopia brand primitives inside reusable component logic",
+        "Motion that bypasses MotionProvider or prefers-reduced-motion"
+      ],
+      "ai": {
+        "props": {
+          "AlertDialogTrigger": "Use asChild with Button for visible trigger controls.",
+          "AlertDialogContent": "Modal content with overlay and semantic surface tokens.",
+          "AlertDialogHeader": "Groups title and description.",
+          "AlertDialogFooter": "Groups cancel/action controls at inline-end.",
+          "AlertDialogCancel": "Non-destructive escape path.",
+          "AlertDialogAction": "Confirmed action; pair destructive wording with product-approved copy.",
+          "motion": "Optional boolean. Defaults to the MotionProvider policy and disables this component pattern when false."
+        },
+        "arabicFriendly": "Footer, text alignment, and modal centering use logical properties. Do not invent Arabic confirmation copy; use supplied localization."
+      }
+    },
+    {
+      "name": "Aspect Ratio",
+      "category": "Layout",
+      "status": "available",
+      "packageImport": "import { AspectRatio } from '@utopia-studio-design/design-system/Layout';",
+      "sourcePath": "packages/design-system/src/components/Layout.tsx",
+      "shadcnFoundation": [
+        "aspect-ratio",
+        "Radix Aspect Ratio",
+        "shadcn/ui registry",
+        "semantic Utopia wrapper"
+      ],
+      "fallbackToShadcn": "aspect-ratio",
+      "requiredTokens": [
+        "--radius-surface",
+        "--surface",
+        "--border"
+      ],
+      "useWhen": [
+        "Media frames need stable dimensions before assets load",
+        "Gallery, thumbnail, video, and preview regions need fixed ratios",
+        "AI-generated templates need layout stability without viewport-based type scaling"
+      ],
+      "avoidWhen": [
+        "Content height is unknown and should grow naturally",
+        "A responsive grid should own the sizing instead",
+        "Text-only cards need normal content flow"
+      ],
+      "neverInvent": [
+        "Viewport-width font scaling",
+        "Unstable media boxes",
+        "Left/right-only layout rules",
+        "Utopia brand primitives inside reusable component logic"
+      ],
+      "ai": {
+        "props": {
+          "ratio": "Number such as 16 / 9, 4 / 3, or 1. Use constants or expressions, not raw string dimensions."
+        },
+        "arabicFriendly": "Aspect ratio is direction-neutral. Content inside still needs dir=\"rtl\" checks for text, controls, and media captions."
+      }
+    },
+    {
+      "name": "Attachment",
+      "category": "Data Display",
+      "status": "available",
+      "packageImport": "import { Attachment, AttachmentAction, AttachmentActions, AttachmentContent, AttachmentDescription, AttachmentGroup, AttachmentMedia, AttachmentTitle, AttachmentTrigger } from '@utopia-studio-design/design-system/Attachment';",
+      "sourcePath": "packages/design-system/src/components/ShadcnPrimitives.tsx",
+      "shadcnFoundation": [
+        "attachment",
+        "shadcn/ui registry",
+        "composable attachment primitives",
+        "semantic Utopia wrapper"
+      ],
+      "fallbackToShadcn": "attachment",
+      "requiredTokens": [
+        "--surface",
+        "--surface-hover",
+        "--surface-strong",
+        "--foreground",
+        "--muted-foreground",
+        "--border",
+        "--primary",
+        "--primary-foreground",
+        "--destructive",
+        "--ring",
+        "--radius-control",
+        "--button-height",
+        "--button-height-sm",
+        "--focus-ring-width",
+        "--duration-fast",
+        "--duration-medium",
+        "--ease-standard"
+      ],
+      "useWhen": [
+        "Files or generated artifacts need a compact preview row",
+        "An upload, processing, error, or done state needs semantic status styling",
+        "A file attachment needs title, description, media, actions, trigger, or grouped layout primitives"
+      ],
+      "avoidWhen": [
+        "A full file manager or product-specific upload workflow is required",
+        "File validation, storage, or localization rules belong in product logic",
+        "Decorative fake files are being generated"
+      ],
+      "neverInvent": [
+        "Fake product file names in production examples",
+        "Raw shadcn theme colors",
+        "Left/right-only action placement",
+        "Utopia brand primitives inside reusable component logic"
+      ],
+      "ai": {
+        "props": {
+          "orientation": "Use horizontal for rows and vertical for stacked previews.",
+          "progress": "Optional 0-100 progress value for uploading or processing states. Product code owns upload math and state changes.",
+          "size": "Use default for normal rows, sm/xs for dense lists.",
+          "state": "Use idle, uploading, processing, error, or done; do not invent custom visual states.",
+          "AttachmentMedia": "Leading media slot for file icon, image thumbnail, spinner, or generated artifact preview. Use variant=\"image\" for thumbnails.",
+          "AttachmentContent": "Text content wrapper containing title and description.",
+          "AttachmentActions": "Inline-end action group for open, remove, retry, or download actions.",
+          "AttachmentTrigger": "Dashed add/upload trigger; product owns file input behavior."
+        },
+        "arabicFriendly": "Use AttachmentMedia at inline-start and AttachmentActions at inline-end. In dir=\"rtl\", action placement, progress, image cards, and truncation must mirror through logical layout. Do not invent Arabic file names or production copy."
+      }
+    },
+    {
+      "name": "Avatar",
+      "category": "Data Display",
+      "status": "available",
+      "packageImport": "import { Avatar, AvatarFallback, AvatarGroup, AvatarImage, AvatarOverflow, AvatarStatusDot } from '@utopia-studio-design/design-system/DataDisplay';",
+      "sourcePath": "packages/design-system/src/components/DataDisplay.tsx",
+      "shadcnFoundation": [
+        "avatar",
+        "Radix Avatar",
+        "semantic Utopia wrapper"
+      ],
+      "fallbackToShadcn": "avatar",
+      "requiredTokens": [
+        "--background",
+        "--secondary",
+        "--secondary-foreground",
+        "--border",
+        "--avatar-size",
+        "--button-height-sm",
+        "--font-size-small",
+        "--font-size-body-lg",
+        "--font-weight-medium",
+        "--success",
+        "--warning",
+        "--destructive",
+        "--muted-foreground"
+      ],
+      "useWhen": [
+        "People or account identifiers",
+        "Team member references with fallback initials",
+        "Entity identity where alt text is known",
+        "A compact team stack needs an overflow count"
+      ],
+      "avoidWhen": [
+        "Decorative profile filler",
+        "Unverified fake people",
+        "A logo or product mark should be used instead"
+      ],
+      "neverInvent": [
+        "Generic fake people",
+        "Left/right-only layout rules",
+        "Utopia brand primitives inside reusable component logic"
+      ],
+      "ai": {
+        "props": {
+          "alt": "Required when src is provided. Use localized, factual identity text; do not invent a fake person.",
+          "children": "Default visual fallback. Prefer initials or a short entity mark when no verified image exists.",
+          "size": "xs, sm, md, or lg. Use sm in dense groups, md for account rows, lg for profile previews.",
+          "src": "Optional verified image URL. Avatar must still render the fallback when the image fails.",
+          "status": "Optional online, busy, away, or offline indicator. Status dot is decorative and mirrors with inline-end.",
+          "AvatarGroup": "Groups multiple avatars with logical overlap and requires an aria-label.",
+          "AvatarOverflow": "Use for localized remaining count such as +3 or +٣. Match its size to grouped avatars.",
+          "AvatarStatusDot": "Internal status indicator; prefer the status prop unless composing a custom avatar."
+        },
+        "arabicFriendly": "Default to initials/fallback when a culturally appropriate verified image is unavailable. Use Arabic initials or localized short labels, logical overlap, inline-end status dots, and Arabic numerals for overflow counts in dir=\"rtl\". Do not fabricate Arabic names or people."
+      }
+    },
+    {
+      "name": "Badge",
+      "category": "Data Display",
+      "status": "available",
+      "packageImport": "import { Badge } from '@utopia-studio-design/design-system/Badge';",
+      "sourcePath": "packages/design-system/src/components/Badge.tsx",
+      "shadcnFoundation": [
+        "badge",
+        "cva"
+      ],
+      "fallbackToShadcn": "badge",
+      "requiredTokens": [
+        "--primary",
+        "--primary-foreground",
+        "--secondary",
+        "--secondary-foreground",
+        "--success",
+        "--success-surface",
+        "--success-border",
+        "--success-text",
+        "--warning-surface",
+        "--warning-border",
+        "--warning-text",
+        "--destructive",
+        "--destructive-surface",
+        "--destructive-border",
+        "--destructive-text",
+        "--border",
+        "--radius-control",
+        "--badge-padding-block",
+        "--badge-padding-inline",
+        "--badge-font-size"
+      ],
+      "useWhen": [
+        "Short status",
+        "Taxonomy",
+        "Type markers",
+        "Unread counts",
+        "Compact metadata"
+      ],
+      "avoidWhen": [
+        "Full sentences",
+        "Pure decoration",
+        "Primary actions",
+        "Unlocalized status copy"
+      ],
+      "neverInvent": [
+        "Extra badge color families",
+        "Long badge copy",
+        "Left/right-only layout rules",
+        "Utopia brand primitives inside reusable component logic"
+      ],
+      "ai": {
+        "props": {
+          "variant": "Semantic visual role. Use default, secondary, destructive, outline, success, info, or warning.",
+          "size": "Compact sizing role. Use sm, md, or lg; do not use size to fix long copy.",
+          "startContent": "Optional inline-start content such as a non-directional icon.",
+          "endContent": "Optional inline-end content such as a localized count.",
+          "children": "Short visible label from product copy or localization."
+        },
+        "rules": [
+          "Use Badge for short status, taxonomy, and compact metadata only.",
+          "Do not hardcode raw Utopia colors inside Badge usage.",
+          "Use semantic variants instead of one-off classes.",
+          "Keep labels short enough to avoid truncation in dense navigation or tables."
+        ],
+        "arabicFriendly": "Badge must support dir=\"rtl\", logical start/end slots, Arabic numerals for counts, IBM Plex Sans Arabic through theme typography tokens, and localized short labels. Do not invent Arabic production copy."
+      }
+    },
+    {
+      "name": "Breadcrumb",
+      "category": "Navigation",
+      "status": "available",
+      "packageImport": "import { Breadcrumb, BreadcrumbEllipsis, BreadcrumbItem, BreadcrumbLink, BreadcrumbList, BreadcrumbPage, BreadcrumbSeparator } from '@utopia-studio-design/design-system/Navigation';",
+      "sourcePath": "packages/design-system/src/components/Navigation.tsx",
+      "shadcnFoundation": [
+        "breadcrumb",
+        "semantic navigation",
+        "shadcn/ui breadcrumb",
+        "ordered-list composition"
+      ],
+      "fallbackToShadcn": "breadcrumb",
+      "requiredTokens": [
+        "--foreground",
+        "--muted-foreground",
+        "--foreground-subtle",
+        "--surface-hover",
+        "--radius-control",
+        "--space-2",
+        "--control-height-sm",
+        "--duration-fast",
+        "--ease-standard",
+        "--focus-ring-width",
+        "--font-weight-medium"
+      ],
+      "useWhen": [
+        "A deep page needs parent-page context",
+        "Users need to understand where the current resource sits in a hierarchy",
+        "A long path may need collapsed middle items or an overflow menu"
+      ],
+      "avoidWhen": [
+        "Primary navigation is needed; use Top Nav, Side Nav, or Navigation Menu",
+        "A single-level page has no parent context",
+        "The UI is a wizard or progress flow; use steps/progress patterns"
+      ],
+      "neverInvent": [
+        "Directional icon without RTL rule",
+        "Left/right-only layout rules",
+        "Utopia brand primitives inside reusable component logic"
+      ],
+      "ai": {
+        "props": {
+          "aria-label": "Required localized label for the breadcrumb navigation landmark.",
+          "Breadcrumb": "Root nav landmark. Keep aria-label descriptive and localized when needed.",
+          "BreadcrumbList": "Ordered list wrapper for breadcrumb items and separators.",
+          "BreadcrumbItem": "List item wrapper for link, current page, or collapsed menu trigger.",
+          "BreadcrumbLink": "Clickable ancestor link. Use a router link only through composition.",
+          "BreadcrumbPage": "Current page label with aria-current=page.",
+          "BreadcrumbSeparator": "Visual separator. Use non-directional slash by default or mirror directional chevrons in RTL.",
+          "BreadcrumbEllipsis": "Collapsed middle path indicator. Pair with a menu when hidden parents need discovery."
+        },
+        "arabicFriendly": "Breadcrumb order, separator spacing, dropdown alignment, and focus rings must follow dir=\"rtl\" using logical properties. Arabic labels must come from localization."
+      }
+    },
+    {
+      "name": "Breadcrumb Item",
+      "category": "Navigation",
+      "status": "available",
+      "packageImport": "import { BreadcrumbItem, BreadcrumbLink, BreadcrumbPage, BreadcrumbSeparator } from '@utopia-studio-design/design-system/Navigation';",
+      "sourcePath": "packages/design-system/src/components/Navigation.tsx",
+      "shadcnFoundation": [
+        "breadcrumb item",
+        "semantic list item",
+        "shadcn/ui breadcrumb",
+        "ordered-list composition"
+      ],
+      "fallbackToShadcn": "breadcrumb",
+      "requiredTokens": [
+        "--foreground",
+        "--muted-foreground",
+        "--foreground-subtle",
+        "--space-2",
+        "--font-weight-medium"
+      ],
+      "useWhen": [
+        "A breadcrumb path needs one ancestor, separator, current page, or collapsed menu segment",
+        "Each path segment needs semantic list structure for screen readers",
+        "A current page must expose aria-current through BreadcrumbPage"
+      ],
+      "avoidWhen": [
+        "The item is not part of a breadcrumb hierarchy",
+        "Primary navigation rows are needed; use Side Nav Item, Top Nav Item, or Navigation Menu",
+        "The path segment should trigger an action unrelated to navigation"
+      ],
+      "neverInvent": [
+        "Directional icon without RTL rule",
+        "Left/right-only layout rules",
+        "Utopia brand primitives inside reusable component logic"
+      ],
+      "ai": {
+        "props": {
+          "BreadcrumbItem": "List item wrapper for a breadcrumb link, current page, separator, or collapsed menu trigger.",
+          "BreadcrumbLink": "Clickable ancestor path segment. Compose with a router link when needed.",
+          "BreadcrumbPage": "Current page path segment. It owns aria-current=page.",
+          "BreadcrumbSeparator": "Visual hierarchy separator. Keep spacing logical and mirror directional separators in RTL."
+        },
+        "arabicFriendly": "Breadcrumb Item must preserve DOM order, logical spacing, current-page semantics, and mixed-script labels in dir=\"rtl\". Use localized path labels."
+      }
+    },
+    {
+      "name": "Breadcrumbs",
+      "category": "Navigation",
+      "status": "available",
+      "packageImport": "import { Breadcrumb, Breadcrumbs, BreadcrumbItem, BreadcrumbLink, BreadcrumbPage, BreadcrumbSeparator } from '@utopia-studio-design/design-system/Navigation';",
+      "sourcePath": "packages/design-system/src/components/Navigation.tsx",
+      "shadcnFoundation": [
+        "breadcrumb list",
+        "semantic ordered list",
+        "shadcn/ui breadcrumb",
+        "ordered-list composition"
+      ],
+      "fallbackToShadcn": "breadcrumb",
+      "requiredTokens": [
+        "--foreground",
+        "--muted-foreground",
+        "--foreground-subtle",
+        "--space-2",
+        "--font-weight-medium"
+      ],
+      "useWhen": [
+        "A breadcrumb path needs the compact ordered-list alias",
+        "A component page or app surface needs a full path rendered inside a Breadcrumb landmark",
+        "A hierarchy needs multiple Breadcrumb Item children with separators"
+      ],
+      "avoidWhen": [
+        "A single current page label is enough",
+        "The UI needs tabs, side navigation, or top navigation instead of hierarchy context",
+        "A progress or wizard path is being represented"
+      ],
+      "neverInvent": [
+        "Directional icon without RTL rule",
+        "Left/right-only layout rules",
+        "Utopia brand primitives inside reusable component logic"
+      ],
+      "ai": {
+        "props": {
+          "Breadcrumbs": "Compact alias for BreadcrumbList. Use inside Breadcrumb as the ordered list wrapper.",
+          "children": "BreadcrumbItem and BreadcrumbSeparator children in hierarchy order."
+        },
+        "arabicFriendly": "Breadcrumbs must keep equivalent hierarchy discovery in dir=\"rtl\", including logical spacing, separator treatment, dropdown alignment, and localized labels."
+      }
+    },
+    {
+      "name": "Bubble",
+      "category": "Data Display",
+      "status": "available",
+      "packageImport": "import { Bubble } from '@utopia-studio-design/design-system/ShadcnPrimitives';",
+      "sourcePath": "packages/design-system/src/components/ShadcnPrimitives.tsx",
+      "shadcnFoundation": [
+        "bubble",
+        "shadcn/ui registry",
+        "semantic Utopia wrapper"
+      ],
+      "fallbackToShadcn": "bubble",
+      "requiredTokens": [
+        "--background",
+        "--foreground",
+        "--surface",
+        "--surface-strong",
+        "--border",
+        "--radius-surface",
+        "--radius-control",
+        "--muted-foreground",
+        "--focus-ring",
+        "--focus-ring-width",
+        "--focus-ring-offset"
+      ],
+      "useWhen": [
+        "Use when the shadcn/ui bubble pattern is required",
+        "Use as the Utopia semantic-token wrapper before deeper specialization",
+        "Use when AI needs a safe conversion target from shadcn source code"
+      ],
+      "avoidWhen": [
+        "A more specific Utopia primitive already exists",
+        "The behavior requires product-specific copy or data rules"
+      ],
+      "neverInvent": [
+        "Raw shadcn theme colors",
+        "Left/right-only layout rules",
+        "Utopia brand primitives inside reusable component logic"
+      ]
+    },
+    {
+      "name": "Button",
+      "category": "Action",
+      "status": "available",
+      "packageImport": "import { Button } from '@utopia-studio-design/design-system/Button';",
+      "sourcePath": "packages/design-system/src/components/Button.tsx",
+      "shadcnFoundation": [
+        "button",
+        "Slot",
+        "cva"
+      ],
+      "fallbackToShadcn": "button",
+      "requiredTokens": [
+        "--primary",
+        "--primary-hover",
+        "--primary-active",
+        "--primary-foreground",
+        "--secondary",
+        "--secondary-hover",
+        "--secondary-active",
+        "--secondary-foreground",
+        "--destructive",
+        "--destructive-hover",
+        "--destructive-active",
+        "--radius-control",
+        "--button-height",
+        "--button-height-sm",
+        "--button-height-lg",
+        "--focus-ring-width",
+        "--motion-duration-press",
+        "--motion-ease-standard",
+        "--motion-press-scale"
+      ],
+      "useWhen": [
+        "Primary actions",
+        "Form submissions",
+        "Navigation CTAs"
+      ],
+      "avoidWhen": [
+        "Passive metadata",
+        "Decorative labels"
+      ],
+      "neverInvent": [
+        "New button colors",
+        "Gradient states",
+        "Unlabeled icon-only buttons",
+        "Left/right-only layout rules",
+        "Utopia brand primitives inside reusable component logic",
+        "Motion that bypasses MotionProvider or prefers-reduced-motion"
+      ],
+      "ai": {
+        "props": {
+          "motion": "Optional boolean. Defaults to the MotionProvider policy and disables this component pattern when false."
+        }
+      }
+    },
+    {
+      "name": "Button Group",
+      "category": "Action",
+      "status": "available",
+      "packageImport": "import { ButtonGroup, ButtonGroupSeparator, ButtonGroupText } from '@utopia-studio-design/design-system/ButtonGroup';",
+      "sourcePath": "packages/design-system/src/components/ButtonGroup.tsx",
+      "shadcnFoundation": [
+        "button-group",
+        "ButtonGroup",
+        "ButtonGroupSeparator",
+        "ButtonGroupText",
+        "cva",
+        "DropdownMenu composition",
+        "split overflow actions"
+      ],
+      "fallbackToShadcn": "shadcn/ui button-group",
+      "requiredTokens": [
+        "--button-group-gap",
+        "--button-group-gap-compact",
+        "--radius-control",
+        "--button-height",
+        "--focus-ring-width",
+        "--popover-surface",
+        "--border"
+      ],
+      "useWhen": [
+        "Related actions",
+        "Toolbar clusters",
+        "Choice-like action sets",
+        "Split or overflow action groups with Dropdown Menu",
+        "Connected controls that combine buttons, static text, and menu triggers"
+      ],
+      "avoidWhen": [
+        "Unrelated actions",
+        "Primary action stacks",
+        "Navigation lists"
+      ],
+      "neverInvent": [
+        "Button group colors",
+        "Left/right-only spacing",
+        "Serialized React children arrays",
+        "Multiple primary actions without hierarchy",
+        "Utopia brand primitives inside reusable component logic",
+        "Hidden overflow menus for primary actions",
+        "Dropdown triggers without accessible labels"
+      ],
+      "ai": {
+        "props": [
+          "orientation",
+          "density",
+          "asToolbar",
+          "label",
+          "children",
+          "ButtonGroupSeparator.orientation",
+          "ButtonGroupText.asChild"
+        ],
+        "shadcnReferencePatterns": [
+          "button group",
+          "button group with dropdown menu",
+          "split button",
+          "toolbar",
+          "input group composition"
+        ],
+        "arabicFriendly": [
+          "Use logical orientation and preserve action meaning in RTL.",
+          "Dropdown overflow triggers require localized aria-label text.",
+          "Do not reorder destructive or primary actions only to mirror the visual layout."
+        ]
+      }
+    },
+    {
+      "name": "Calendar",
+      "category": "Data Display",
+      "status": "available",
+      "packageImport": "import { Calendar } from '@utopia-studio-design/design-system/DataDisplay';",
+      "sourcePath": "packages/design-system/src/components/DataDisplay.tsx",
+      "shadcnFoundation": [
+        "calendar",
+        "react-day-picker",
+        "semantic date grid",
+        "shadcn/ui calendar",
+        "controlled/uncontrolled state"
+      ],
+      "fallbackToShadcn": "calendar",
+      "requiredTokens": [
+        "--surface",
+        "--background",
+        "--foreground",
+        "--muted-foreground",
+        "--foreground-subtle",
+        "--border",
+        "--input",
+        "--radius-surface",
+        "--radius-control",
+        "--primary",
+        "--primary-foreground",
+        "--surface-hover",
+        "--button-height-sm",
+        "--duration-fast",
+        "--ease-standard",
+        "--focus-ring-width"
+      ],
+      "useWhen": [
+        "Date browsing and date picking with visible month/year navigation",
+        "Product forms need controlled or uncontrolled selected date state",
+        "Month-grid previews need product-owned localization rules and RTL-safe layout"
+      ],
+      "avoidWhen": [
+        "Hijri calendar without localization requirements",
+        "Date math or booking rules that belong in product logic",
+        "Unverified locale-specific calendar behavior"
+      ],
+      "neverInvent": [
+        "Locale-specific calendar behavior",
+        "Left/right-only layout rules",
+        "Utopia brand primitives inside reusable component logic",
+        "Business disabled-date rules inside the design-system package"
+      ],
+      "ai": {
+        "props": {
+          "month": "Controlled visible month. Pair with onMonthChange.",
+          "defaultMonth": "Initial visible month for uncontrolled usage.",
+          "selectedDate": "Controlled selected date. Pair with onSelect.",
+          "defaultSelectedDate": "Initial selected date for uncontrolled usage.",
+          "onSelect": "Called with a Date when an enabled day is selected.",
+          "onMonthChange": "Called when previous/next or month/year controls change the visible month.",
+          "weekStartsOn": "Use product locale requirements. 0 is Sunday, 1 Monday, 6 Saturday.",
+          "disabledDates": "Product-owned predicate for disabled days."
+        },
+        "arabicFriendly": "Calendar supports dir inheritance, localized month/day labels, logical layout, Arabic numerals through Intl, and configurable week start. Hijri support must be explicit product work, not assumed."
+      }
+    },
+    {
+      "name": "Card",
+      "category": "Surface",
+      "status": "available",
+      "packageImport": "import { Card, CardHeader, CardTitle, CardDescription, CardAction, CardStatus, CardContent, CardFooter } from '@utopia-studio-design/design-system/Card';",
+      "sourcePath": "packages/design-system/src/components/Card.tsx",
+      "shadcnFoundation": [
+        "shadcn/ui card",
+        "header/content/footer composition",
+        "semantic surface wrapper"
+      ],
+      "fallbackToShadcn": "card",
+      "requiredTokens": [
+        "--card",
+        "--card-foreground",
+        "--border",
+        "--border-width-strong",
+        "--primary",
+        "--surface",
+        "--surface-hover",
+        "--foreground",
+        "--muted-foreground",
+        "--radius-surface",
+        "--radius-control",
+        "--card-padding",
+        "--card-title-size",
+        "--badge-height",
+        "--badge-padding-block",
+        "--badge-padding-inline",
+        "--focus-ring-width",
+        "--duration-fast",
+        "--duration-medium",
+        "--ease-standard"
+      ],
+      "useWhen": [
+        "A surface needs a clear header, content, and footer contract",
+        "Repeated content such as resource cards, product summaries, or dashboard modules",
+        "Grouped data where status or secondary action belongs in the header inline-end",
+        "Framed tool surfaces that need the Utopia Ceramic hover accent"
+      ],
+      "avoidWhen": [
+        "Full page sections or marketing bands",
+        "Nested cards",
+        "Navigation rows that should use SideNavItem, TopNavItem, Breadcrumbs, or List",
+        "Clickable behavior without using ClickableCard, SelectableCard, or explicit interactive semantics"
+      ],
+      "neverInvent": [
+        "Raw colors",
+        "Raw shadows",
+        "Raw radius values",
+        "Drop shadows",
+        "Rounded marketing panels",
+        "Decorative card grids",
+        "Left/right-only layout rules",
+        "Utopia brand primitives inside reusable component logic"
+      ],
+      "ai": {
+        "props": {
+          "Card.accent": "false | 'hover' | 'always'. Shows the semantic block-start accent line using --primary.",
+          "Card.interactive": "boolean. Adds hover and focus-visible treatment only; use semantic link or button wrappers when the whole card is actionable.",
+          "Card.size": "'default' | 'sm'. Changes density through --card-padding and --card-title-size.",
+          "CardHeader": "Header region. Place CardTitle, CardDescription, and optional CardAction here.",
+          "CardAction": "Header inline-end region for compact actions or CardStatus.",
+          "CardStatus": "Compact status pill that uses badge/control tokens instead of raw colors.",
+          "CardContent": "Main content region.",
+          "CardFooter": "Footer region for actions. Uses logical border-block-start and wraps safely.",
+          "ClickableCard": "Anchor wrapper for full-card links. Defaults to hover accent.",
+          "SelectableCard": "Button wrapper for selectable surfaces. Defaults to hover accent and exposes aria-pressed."
+        },
+        "arabicFriendly": "Card uses logical block/inline layout, puts CardAction at inline-end through CSS grid, supports dir='rtl', tolerates mixed Arabic/English status text, and does not provide production Arabic copy.",
+        "shadcnConversion": "Keep the shadcn/ui Card family shape but consume Utopia semantic CSS tokens and exports only.",
+        "cli": "npm run ds -- component Card --dense"
+      }
+    },
+    {
+      "name": "Carousel",
+      "category": "Data Display",
+      "status": "available",
+      "packageImport": "import { Carousel, CarouselButton, CarouselContent, CarouselControls, CarouselItem } from '@utopia-studio-design/design-system/ShadcnPrimitives';",
+      "sourcePath": "packages/design-system/src/components/ShadcnPrimitives.tsx",
+      "shadcnFoundation": [
+        "carousel",
+        "scroll snap carousel",
+        "shadcn/ui registry"
+      ],
+      "fallbackToShadcn": "carousel",
+      "requiredTokens": [
+        "--surface",
+        "--foreground",
+        "--foreground-muted",
+        "--border",
+        "--radius-surface",
+        "--radius-control",
+        "--secondary",
+        "--secondary-foreground",
+        "--focus-ring-width",
+        "--primary"
+      ],
+      "useWhen": [
+        "Small sets of related items where order matters",
+        "Horizontal browsing that should support wheel, trackpad, touch, and keyboard-friendly focus targets",
+        "DIY item collections where the product team supplies its own media, copy, and item layout",
+        "AI-generated previews that need explicit item labels and replaceable data"
+      ],
+      "avoidWhen": [
+        "Large data sets",
+        "Primary navigation",
+        "Content that must all be visible at once"
+      ],
+      "neverInvent": [
+        "Raw shadcn theme colors",
+        "Left/right-only layout rules",
+        "Utopia brand primitives inside reusable component logic"
+      ],
+      "arabicFriendly": "CarouselContent converts vertical wheel input to inline scrolling, mirrors movement under dir='rtl', hides scrollbars without changing layout width, and requires logical start/end naming for directional controls.",
+      "shadcnConversion": "Keep the shadcn/ui carousel composition shape: Carousel wraps behavior, CarouselContent owns horizontal scroll, CarouselItem owns each replaceable item, and controls remain optional.",
+      "cli": "npm run ds -- component Carousel --dense"
+    },
+    {
+      "name": "Chart",
+      "category": "Data Display",
+      "status": "available",
+      "packageImport": "import { Chart, ChartBars } from '@utopia-studio-design/design-system/ShadcnPrimitives';",
+      "sourcePath": "packages/design-system/src/components/ShadcnPrimitives.tsx",
+      "shadcnFoundation": [
+        "chart",
+        "shadcn/ui chart pattern",
+        "semantic Utopia data display wrapper",
+        "shadcn/ui registry"
+      ],
+      "fallbackToShadcn": "chart",
+      "requiredTokens": [
+        "--surface",
+        "--foreground",
+        "--muted-foreground",
+        "--border",
+        "--radius-surface",
+        "--radius-control",
+        "--primary",
+        "--chart-bar-size",
+        "--chart-block-size",
+        "--chart-grid-color",
+        "--duration-medium",
+        "--ease-standard"
+      ],
+      "useWhen": [
+        "Simple visual summaries with explicit labels and values",
+        "Component docs examples that need a token-safe chart scaffold",
+        "AI-generated dashboards before product-specific chart logic is selected"
+      ],
+      "avoidWhen": [
+        "Financial or analytics charts without domain requirements",
+        "Unlabeled data",
+        "Locale-specific number formatting inside reusable component logic"
+      ],
+      "neverInvent": [
+        "Raw shadcn theme colors",
+        "Left/right-only layout rules",
+        "Utopia brand primitives inside reusable component logic"
+      ]
+    },
+    {
+      "name": "Chat Composer",
+      "category": "Chat",
+      "status": "available",
+      "packageImport": "import { ChatComposer } from '@utopia-studio-design/design-system/Chat';",
+      "sourcePath": "packages/design-system/src/components/Chat.tsx",
+      "shadcnFoundation": [
+        "textarea + button",
+        "shadcn/ui registry pattern",
+        "AI/chat product primitive",
+        "semantic Utopia wrapper"
+      ],
+      "fallbackToShadcn": "textarea + button",
+      "requiredTokens": [
+        "--background",
+        "--surface",
+        "--surface-elevated",
+        "--surface-hover",
+        "--foreground",
+        "--foreground-muted",
+        "--border",
+        "--radius-control",
+        "--radius-surface",
+        "--space-1",
+        "--space-2",
+        "--space-3",
+        "--space-4",
+        "--duration-fast",
+        "--ease-standard",
+        "--focus-ring-width",
+        "--radius-chat-bubble",
+        "--radius-chat-composer",
+        "--radius-chat-token"
+      ],
+      "useWhen": [
+        "Building assistant, support, collaboration, or AI product chat surfaces",
+        "Message, composer, token, metadata, and tool-call regions need consistent reusable parts",
+        "The interface must support mixed-script content and dir=\"rtl\" layout without page-local rewrites"
+      ],
+      "avoidWhen": [
+        "The content is a static marketing testimonial rather than an interactive conversation",
+        "The product needs a bespoke transcript renderer with non-chat semantics",
+        "You only need a single generic card or empty state"
+      ],
+      "neverInvent": [
+        "Left/right-only layout rules",
+        "Raw shadcn theme colors",
+        "Utopia brand primitives inside reusable component logic",
+        "Arabic production copy generated by the component package"
+      ],
+      "ai": {
+        "props": {
+          "dir": "Use inherited dir by default. Set dir=\"rtl\" only for isolated smoke tests.",
+          "role": "Use user, assistant, or system where the component exposes message role.",
+          "metadata": "Pass localized timestamp/read/tool metadata from the app layer.",
+          "children": "Use product-owned copy. The design system supplies layout and tokens only.",
+          "accessibilityText": "Supply every visible label, aria-label, status summary, and action name from product localization. ChatSendButton and ChatDictationButton require label; ChatLayoutScrollButton requires accessibilityLabel; ChatToolCalls requires label."
+        },
+        "arabicFriendly": "Chat components use logical spacing, role-based alignment, mixed-script safe typography, and mirrored message flow in dir=\"rtl\". Do not invent Arabic copy in reusable components."
+      }
+    },
+    {
+      "name": "Chat Composer Drawer",
+      "category": "Chat",
+      "status": "available",
+      "packageImport": "import { ChatComposerDrawer } from '@utopia-studio-design/design-system/Chat';",
+      "sourcePath": "packages/design-system/src/components/Chat.tsx",
+      "shadcnFoundation": [
+        "drawer",
+        "shadcn/ui registry pattern",
+        "AI/chat product primitive",
+        "semantic Utopia wrapper"
+      ],
+      "fallbackToShadcn": "drawer",
+      "requiredTokens": [
+        "--background",
+        "--surface",
+        "--surface-elevated",
+        "--surface-hover",
+        "--foreground",
+        "--foreground-muted",
+        "--border",
+        "--radius-control",
+        "--radius-surface",
+        "--space-1",
+        "--space-2",
+        "--space-3",
+        "--space-4",
+        "--duration-fast",
+        "--ease-standard",
+        "--focus-ring-width",
+        "--radius-chat-bubble",
+        "--radius-chat-composer",
+        "--radius-chat-token"
+      ],
+      "useWhen": [
+        "Building assistant, support, collaboration, or AI product chat surfaces",
+        "Message, composer, token, metadata, and tool-call regions need consistent reusable parts",
+        "The interface must support mixed-script content and dir=\"rtl\" layout without page-local rewrites"
+      ],
+      "avoidWhen": [
+        "The content is a static marketing testimonial rather than an interactive conversation",
+        "The product needs a bespoke transcript renderer with non-chat semantics",
+        "You only need a single generic card or empty state"
+      ],
+      "neverInvent": [
+        "Left/right-only layout rules",
+        "Raw shadcn theme colors",
+        "Utopia brand primitives inside reusable component logic",
+        "Arabic production copy generated by the component package"
+      ],
+      "ai": {
+        "props": {
+          "dir": "Use inherited dir by default. Set dir=\"rtl\" only for isolated smoke tests.",
+          "role": "Use user, assistant, or system where the component exposes message role.",
+          "metadata": "Pass localized timestamp/read/tool metadata from the app layer.",
+          "children": "Use product-owned copy. The design system supplies layout and tokens only."
+        },
+        "arabicFriendly": "Chat components use logical spacing, role-based alignment, mixed-script safe typography, and mirrored message flow in dir=\"rtl\". Do not invent Arabic copy in reusable components."
+      }
+    },
+    {
+      "name": "Chat Composer Input",
+      "category": "Chat",
+      "status": "available",
+      "packageImport": "import { ChatComposerInput } from '@utopia-studio-design/design-system/Chat';",
+      "sourcePath": "packages/design-system/src/components/Chat.tsx",
+      "shadcnFoundation": [
+        "textarea",
+        "shadcn/ui registry pattern",
+        "AI/chat product primitive",
+        "semantic Utopia wrapper"
+      ],
+      "fallbackToShadcn": "textarea",
+      "requiredTokens": [
+        "--background",
+        "--surface",
+        "--surface-elevated",
+        "--surface-hover",
+        "--foreground",
+        "--foreground-muted",
+        "--border",
+        "--radius-control",
+        "--radius-surface",
+        "--space-1",
+        "--space-2",
+        "--space-3",
+        "--space-4",
+        "--duration-fast",
+        "--ease-standard",
+        "--focus-ring-width",
+        "--radius-chat-bubble",
+        "--radius-chat-composer",
+        "--radius-chat-token"
+      ],
+      "useWhen": [
+        "Building assistant, support, collaboration, or AI product chat surfaces",
+        "Message, composer, token, metadata, and tool-call regions need consistent reusable parts",
+        "The interface must support mixed-script content and dir=\"rtl\" layout without page-local rewrites"
+      ],
+      "avoidWhen": [
+        "The content is a static marketing testimonial rather than an interactive conversation",
+        "The product needs a bespoke transcript renderer with non-chat semantics",
+        "You only need a single generic card or empty state"
+      ],
+      "neverInvent": [
+        "Left/right-only layout rules",
+        "Raw shadcn theme colors",
+        "Utopia brand primitives inside reusable component logic",
+        "Arabic production copy generated by the component package"
+      ],
+      "ai": {
+        "props": {
+          "dir": "Use inherited dir by default. Set dir=\"rtl\" only for isolated smoke tests.",
+          "role": "Use user, assistant, or system where the component exposes message role.",
+          "metadata": "Pass localized timestamp/read/tool metadata from the app layer.",
+          "children": "Use product-owned copy. The design system supplies layout and tokens only."
+        },
+        "arabicFriendly": "Chat components use logical spacing, role-based alignment, mixed-script safe typography, and mirrored message flow in dir=\"rtl\". Do not invent Arabic copy in reusable components."
+      }
+    },
+    {
+      "name": "Chat Composer Token Element",
+      "category": "Chat",
+      "status": "available",
+      "packageImport": "import { ChatComposerTokenElement } from '@utopia-studio-design/design-system/Chat';",
+      "sourcePath": "packages/design-system/src/components/Chat.tsx",
+      "shadcnFoundation": [
+        "badge",
+        "shadcn/ui registry pattern",
+        "AI/chat product primitive",
+        "semantic Utopia wrapper"
+      ],
+      "fallbackToShadcn": "badge",
+      "requiredTokens": [
+        "--background",
+        "--surface",
+        "--surface-elevated",
+        "--surface-hover",
+        "--foreground",
+        "--foreground-muted",
+        "--border",
+        "--radius-control",
+        "--radius-surface",
+        "--space-1",
+        "--space-2",
+        "--space-3",
+        "--space-4",
+        "--duration-fast",
+        "--ease-standard",
+        "--focus-ring-width",
+        "--radius-chat-bubble",
+        "--radius-chat-composer",
+        "--radius-chat-token"
+      ],
+      "useWhen": [
+        "Building assistant, support, collaboration, or AI product chat surfaces",
+        "Message, composer, token, metadata, and tool-call regions need consistent reusable parts",
+        "The interface must support mixed-script content and dir=\"rtl\" layout without page-local rewrites"
+      ],
+      "avoidWhen": [
+        "The content is a static marketing testimonial rather than an interactive conversation",
+        "The product needs a bespoke transcript renderer with non-chat semantics",
+        "You only need a single generic card or empty state"
+      ],
+      "neverInvent": [
+        "Left/right-only layout rules",
+        "Raw shadcn theme colors",
+        "Utopia brand primitives inside reusable component logic",
+        "Arabic production copy generated by the component package"
+      ],
+      "ai": {
+        "props": {
+          "dir": "Use inherited dir by default. Set dir=\"rtl\" only for isolated smoke tests.",
+          "role": "Use user, assistant, or system where the component exposes message role.",
+          "metadata": "Pass localized timestamp/read/tool metadata from the app layer.",
+          "children": "Use product-owned copy. The design system supplies layout and tokens only."
+        },
+        "arabicFriendly": "Chat components use logical spacing, role-based alignment, mixed-script safe typography, and mirrored message flow in dir=\"rtl\". Do not invent Arabic copy in reusable components."
+      }
+    },
+    {
+      "name": "Chat Dictation Button",
+      "category": "Chat",
+      "status": "available",
+      "packageImport": "import { ChatDictationButton } from '@utopia-studio-design/design-system/Chat';",
+      "sourcePath": "packages/design-system/src/components/Chat.tsx",
+      "shadcnFoundation": [
+        "button",
+        "shadcn/ui registry pattern",
+        "AI/chat product primitive",
+        "semantic Utopia wrapper"
+      ],
+      "fallbackToShadcn": "button",
+      "requiredTokens": [
+        "--background",
+        "--surface",
+        "--surface-elevated",
+        "--surface-hover",
+        "--foreground",
+        "--foreground-muted",
+        "--border",
+        "--radius-control",
+        "--radius-surface",
+        "--space-1",
+        "--space-2",
+        "--space-3",
+        "--space-4",
+        "--duration-fast",
+        "--ease-standard",
+        "--focus-ring-width",
+        "--radius-chat-bubble",
+        "--radius-chat-composer",
+        "--radius-chat-token"
+      ],
+      "useWhen": [
+        "Building assistant, support, collaboration, or AI product chat surfaces",
+        "Message, composer, token, metadata, and tool-call regions need consistent reusable parts",
+        "The interface must support mixed-script content and dir=\"rtl\" layout without page-local rewrites"
+      ],
+      "avoidWhen": [
+        "The content is a static marketing testimonial rather than an interactive conversation",
+        "The product needs a bespoke transcript renderer with non-chat semantics",
+        "You only need a single generic card or empty state"
+      ],
+      "neverInvent": [
+        "Left/right-only layout rules",
+        "Raw shadcn theme colors",
+        "Utopia brand primitives inside reusable component logic",
+        "Arabic production copy generated by the component package"
+      ],
+      "ai": {
+        "props": {
+          "dir": "Use inherited dir by default. Set dir=\"rtl\" only for isolated smoke tests.",
+          "role": "Use user, assistant, or system where the component exposes message role.",
+          "metadata": "Pass localized timestamp/read/tool metadata from the app layer.",
+          "children": "Use product-owned copy. The design system supplies layout and tokens only.",
+          "accessibilityText": "The required label prop is localized product copy for the dictation action and current state."
+        },
+        "arabicFriendly": "Chat components use logical spacing, role-based alignment, mixed-script safe typography, and mirrored message flow in dir=\"rtl\". Do not invent Arabic copy in reusable components."
+      }
+    },
+    {
+      "name": "Chat Layout",
+      "category": "Chat",
+      "status": "available",
+      "packageImport": "import { ChatLayout } from '@utopia-studio-design/design-system/Chat';",
+      "sourcePath": "packages/design-system/src/components/Chat.tsx",
+      "shadcnFoundation": [
+        "scroll-area",
+        "shadcn/ui registry pattern",
+        "AI/chat product primitive",
+        "semantic Utopia wrapper"
+      ],
+      "fallbackToShadcn": "scroll-area",
+      "requiredTokens": [
+        "--background",
+        "--surface",
+        "--surface-elevated",
+        "--surface-hover",
+        "--foreground",
+        "--foreground-muted",
+        "--border",
+        "--radius-control",
+        "--radius-surface",
+        "--space-1",
+        "--space-2",
+        "--space-3",
+        "--space-4",
+        "--duration-fast",
+        "--ease-standard",
+        "--focus-ring-width",
+        "--radius-chat-bubble",
+        "--radius-chat-composer",
+        "--radius-chat-token"
+      ],
+      "useWhen": [
+        "Building assistant, support, collaboration, or AI product chat surfaces",
+        "Message, composer, token, metadata, and tool-call regions need consistent reusable parts",
+        "The interface must support mixed-script content and dir=\"rtl\" layout without page-local rewrites"
+      ],
+      "avoidWhen": [
+        "The content is a static marketing testimonial rather than an interactive conversation",
+        "The product needs a bespoke transcript renderer with non-chat semantics",
+        "You only need a single generic card or empty state"
+      ],
+      "neverInvent": [
+        "Left/right-only layout rules",
+        "Raw shadcn theme colors",
+        "Utopia brand primitives inside reusable component logic",
+        "Arabic production copy generated by the component package"
+      ],
+      "ai": {
+        "props": {
+          "dir": "Use inherited dir by default. Set dir=\"rtl\" only for isolated smoke tests.",
+          "role": "Use user, assistant, or system where the component exposes message role.",
+          "metadata": "Pass localized timestamp/read/tool metadata from the app layer.",
+          "children": "Use product-owned copy. The design system supplies layout and tokens only."
+        },
+        "arabicFriendly": "Chat components use logical spacing, role-based alignment, mixed-script safe typography, and mirrored message flow in dir=\"rtl\". Do not invent Arabic copy in reusable components."
+      }
+    },
+    {
+      "name": "Chat Layout Scroll Button",
+      "category": "Chat",
+      "status": "available",
+      "packageImport": "import { ChatLayoutScrollButton } from '@utopia-studio-design/design-system/Chat';",
+      "sourcePath": "packages/design-system/src/components/Chat.tsx",
+      "shadcnFoundation": [
+        "button",
+        "shadcn/ui registry pattern",
+        "AI/chat product primitive",
+        "semantic Utopia wrapper"
+      ],
+      "fallbackToShadcn": "button",
+      "requiredTokens": [
+        "--background",
+        "--surface",
+        "--surface-elevated",
+        "--surface-hover",
+        "--foreground",
+        "--foreground-muted",
+        "--border",
+        "--radius-control",
+        "--radius-surface",
+        "--space-1",
+        "--space-2",
+        "--space-3",
+        "--space-4",
+        "--duration-fast",
+        "--ease-standard",
+        "--focus-ring-width",
+        "--radius-chat-bubble",
+        "--radius-chat-composer",
+        "--radius-chat-token"
+      ],
+      "useWhen": [
+        "Building assistant, support, collaboration, or AI product chat surfaces",
+        "Message, composer, token, metadata, and tool-call regions need consistent reusable parts",
+        "The interface must support mixed-script content and dir=\"rtl\" layout without page-local rewrites"
+      ],
+      "avoidWhen": [
+        "The content is a static marketing testimonial rather than an interactive conversation",
+        "The product needs a bespoke transcript renderer with non-chat semantics",
+        "You only need a single generic card or empty state"
+      ],
+      "neverInvent": [
+        "Left/right-only layout rules",
+        "Raw shadcn theme colors",
+        "Utopia brand primitives inside reusable component logic",
+        "Arabic production copy generated by the component package"
+      ],
+      "ai": {
+        "props": {
+          "dir": "Use inherited dir by default. Set dir=\"rtl\" only for isolated smoke tests.",
+          "role": "Use user, assistant, or system where the component exposes message role.",
+          "metadata": "Pass localized timestamp/read/tool metadata from the app layer.",
+          "children": "Use product-owned copy. The design system supplies layout and tokens only.",
+          "accessibilityText": "The required accessibilityLabel prop names the scroll action; the optional label prop is localized visible status copy."
+        },
+        "arabicFriendly": "Chat components use logical spacing, role-based alignment, mixed-script safe typography, and mirrored message flow in dir=\"rtl\". Do not invent Arabic copy in reusable components."
+      }
+    },
+    {
+      "name": "Chat Message",
+      "category": "Chat",
+      "status": "available",
+      "packageImport": "import { ChatMessage } from '@utopia-studio-design/design-system/Chat';",
+      "sourcePath": "packages/design-system/src/components/Chat.tsx",
+      "shadcnFoundation": [
+        "message",
+        "shadcn/ui registry pattern",
+        "AI/chat product primitive",
+        "semantic Utopia wrapper"
+      ],
+      "fallbackToShadcn": "message",
+      "requiredTokens": [
+        "--background",
+        "--surface",
+        "--surface-elevated",
+        "--surface-hover",
+        "--foreground",
+        "--foreground-muted",
+        "--border",
+        "--radius-control",
+        "--radius-surface",
+        "--space-1",
+        "--space-2",
+        "--space-3",
+        "--space-4",
+        "--duration-fast",
+        "--ease-standard",
+        "--focus-ring-width",
+        "--radius-chat-bubble",
+        "--radius-chat-composer",
+        "--radius-chat-token"
+      ],
+      "useWhen": [
+        "Building assistant, support, collaboration, or AI product chat surfaces",
+        "Message, composer, token, metadata, and tool-call regions need consistent reusable parts",
+        "The interface must support mixed-script content and dir=\"rtl\" layout without page-local rewrites"
+      ],
+      "avoidWhen": [
+        "The content is a static marketing testimonial rather than an interactive conversation",
+        "The product needs a bespoke transcript renderer with non-chat semantics",
+        "You only need a single generic card or empty state"
+      ],
+      "neverInvent": [
+        "Left/right-only layout rules",
+        "Raw shadcn theme colors",
+        "Utopia brand primitives inside reusable component logic",
+        "Arabic production copy generated by the component package"
+      ],
+      "ai": {
+        "props": {
+          "dir": "Use inherited dir by default. Set dir=\"rtl\" only for isolated smoke tests.",
+          "role": "Use user, assistant, or system where the component exposes message role.",
+          "metadata": "Pass localized timestamp/read/tool metadata from the app layer.",
+          "children": "Use product-owned copy. The design system supplies layout and tokens only."
+        },
+        "arabicFriendly": "Chat components use logical spacing, role-based alignment, mixed-script safe typography, and mirrored message flow in dir=\"rtl\". Do not invent Arabic copy in reusable components."
+      }
+    },
+    {
+      "name": "Chat Message Bubble",
+      "category": "Chat",
+      "status": "available",
+      "packageImport": "import { ChatMessageBubble } from '@utopia-studio-design/design-system/Chat';",
+      "sourcePath": "packages/design-system/src/components/Chat.tsx",
+      "shadcnFoundation": [
+        "bubble",
+        "shadcn/ui registry pattern",
+        "AI/chat product primitive",
+        "semantic Utopia wrapper"
+      ],
+      "fallbackToShadcn": "bubble",
+      "requiredTokens": [
+        "--background",
+        "--surface",
+        "--surface-elevated",
+        "--surface-hover",
+        "--foreground",
+        "--foreground-muted",
+        "--border",
+        "--radius-control",
+        "--radius-surface",
+        "--space-1",
+        "--space-2",
+        "--space-3",
+        "--space-4",
+        "--duration-fast",
+        "--ease-standard",
+        "--focus-ring-width",
+        "--radius-chat-bubble",
+        "--radius-chat-composer",
+        "--radius-chat-token"
+      ],
+      "useWhen": [
+        "Building assistant, support, collaboration, or AI product chat surfaces",
+        "Message, composer, token, metadata, and tool-call regions need consistent reusable parts",
+        "The interface must support mixed-script content and dir=\"rtl\" layout without page-local rewrites"
+      ],
+      "avoidWhen": [
+        "The content is a static marketing testimonial rather than an interactive conversation",
+        "The product needs a bespoke transcript renderer with non-chat semantics",
+        "You only need a single generic card or empty state"
+      ],
+      "neverInvent": [
+        "Left/right-only layout rules",
+        "Raw shadcn theme colors",
+        "Utopia brand primitives inside reusable component logic",
+        "Arabic production copy generated by the component package"
+      ],
+      "ai": {
+        "props": {
+          "dir": "Use inherited dir by default. Set dir=\"rtl\" only for isolated smoke tests.",
+          "role": "Use user, assistant, or system where the component exposes message role.",
+          "metadata": "Pass localized timestamp/read/tool metadata from the app layer.",
+          "children": "Use product-owned copy. The design system supplies layout and tokens only."
+        },
+        "arabicFriendly": "Chat components use logical spacing, role-based alignment, mixed-script safe typography, and mirrored message flow in dir=\"rtl\". Do not invent Arabic copy in reusable components."
+      }
+    },
+    {
+      "name": "Chat Message List",
+      "category": "Chat",
+      "status": "available",
+      "packageImport": "import { ChatMessageList } from '@utopia-studio-design/design-system/Chat';",
+      "sourcePath": "packages/design-system/src/components/Chat.tsx",
+      "shadcnFoundation": [
+        "message-scroller",
+        "shadcn/ui registry pattern",
+        "AI/chat product primitive",
+        "semantic Utopia wrapper"
+      ],
+      "fallbackToShadcn": "message-scroller",
+      "requiredTokens": [
+        "--background",
+        "--surface",
+        "--surface-elevated",
+        "--surface-hover",
+        "--foreground",
+        "--foreground-muted",
+        "--border",
+        "--radius-control",
+        "--radius-surface",
+        "--space-1",
+        "--space-2",
+        "--space-3",
+        "--space-4",
+        "--duration-fast",
+        "--ease-standard",
+        "--focus-ring-width",
+        "--radius-chat-bubble",
+        "--radius-chat-composer",
+        "--radius-chat-token"
+      ],
+      "useWhen": [
+        "Building assistant, support, collaboration, or AI product chat surfaces",
+        "Message, composer, token, metadata, and tool-call regions need consistent reusable parts",
+        "The interface must support mixed-script content and dir=\"rtl\" layout without page-local rewrites"
+      ],
+      "avoidWhen": [
+        "The content is a static marketing testimonial rather than an interactive conversation",
+        "The product needs a bespoke transcript renderer with non-chat semantics",
+        "You only need a single generic card or empty state"
+      ],
+      "neverInvent": [
+        "Left/right-only layout rules",
+        "Raw shadcn theme colors",
+        "Utopia brand primitives inside reusable component logic",
+        "Arabic production copy generated by the component package"
+      ],
+      "ai": {
+        "props": {
+          "dir": "Use inherited dir by default. Set dir=\"rtl\" only for isolated smoke tests.",
+          "role": "Use user, assistant, or system where the component exposes message role.",
+          "metadata": "Pass localized timestamp/read/tool metadata from the app layer.",
+          "children": "Use product-owned copy. The design system supplies layout and tokens only."
+        },
+        "arabicFriendly": "Chat components use logical spacing, role-based alignment, mixed-script safe typography, and mirrored message flow in dir=\"rtl\". Do not invent Arabic copy in reusable components."
+      }
+    },
+    {
+      "name": "Chat Message Metadata",
+      "category": "Chat",
+      "status": "available",
+      "packageImport": "import { ChatMessageMetadata } from '@utopia-studio-design/design-system/Chat';",
+      "sourcePath": "packages/design-system/src/components/Chat.tsx",
+      "shadcnFoundation": [
+        "text",
+        "shadcn/ui registry pattern",
+        "AI/chat product primitive",
+        "semantic Utopia wrapper"
+      ],
+      "fallbackToShadcn": "text",
+      "requiredTokens": [
+        "--background",
+        "--surface",
+        "--surface-elevated",
+        "--surface-hover",
+        "--foreground",
+        "--foreground-muted",
+        "--border",
+        "--radius-control",
+        "--radius-surface",
+        "--space-1",
+        "--space-2",
+        "--space-3",
+        "--space-4",
+        "--duration-fast",
+        "--ease-standard",
+        "--focus-ring-width",
+        "--radius-chat-bubble",
+        "--radius-chat-composer",
+        "--radius-chat-token"
+      ],
+      "useWhen": [
+        "Building assistant, support, collaboration, or AI product chat surfaces",
+        "Message, composer, token, metadata, and tool-call regions need consistent reusable parts",
+        "The interface must support mixed-script content and dir=\"rtl\" layout without page-local rewrites"
+      ],
+      "avoidWhen": [
+        "The content is a static marketing testimonial rather than an interactive conversation",
+        "The product needs a bespoke transcript renderer with non-chat semantics",
+        "You only need a single generic card or empty state"
+      ],
+      "neverInvent": [
+        "Left/right-only layout rules",
+        "Raw shadcn theme colors",
+        "Utopia brand primitives inside reusable component logic",
+        "Arabic production copy generated by the component package"
+      ],
+      "ai": {
+        "props": {
+          "dir": "Use inherited dir by default. Set dir=\"rtl\" only for isolated smoke tests.",
+          "role": "Use user, assistant, or system where the component exposes message role.",
+          "metadata": "Pass localized timestamp/read/tool metadata from the app layer.",
+          "children": "Use product-owned copy. The design system supplies layout and tokens only."
+        },
+        "arabicFriendly": "Chat components use logical spacing, role-based alignment, mixed-script safe typography, and mirrored message flow in dir=\"rtl\". Do not invent Arabic copy in reusable components."
+      }
+    },
+    {
+      "name": "Chat Send Button",
+      "category": "Chat",
+      "status": "available",
+      "packageImport": "import { ChatSendButton } from '@utopia-studio-design/design-system/Chat';",
+      "sourcePath": "packages/design-system/src/components/Chat.tsx",
+      "shadcnFoundation": [
+        "button",
+        "shadcn/ui registry pattern",
+        "AI/chat product primitive",
+        "semantic Utopia wrapper"
+      ],
+      "fallbackToShadcn": "button",
+      "requiredTokens": [
+        "--background",
+        "--surface",
+        "--surface-elevated",
+        "--surface-hover",
+        "--foreground",
+        "--foreground-muted",
+        "--border",
+        "--radius-control",
+        "--radius-surface",
+        "--space-1",
+        "--space-2",
+        "--space-3",
+        "--space-4",
+        "--duration-fast",
+        "--ease-standard",
+        "--focus-ring-width",
+        "--radius-chat-bubble",
+        "--radius-chat-composer",
+        "--radius-chat-token"
+      ],
+      "useWhen": [
+        "Building assistant, support, collaboration, or AI product chat surfaces",
+        "Message, composer, token, metadata, and tool-call regions need consistent reusable parts",
+        "The interface must support mixed-script content and dir=\"rtl\" layout without page-local rewrites"
+      ],
+      "avoidWhen": [
+        "The content is a static marketing testimonial rather than an interactive conversation",
+        "The product needs a bespoke transcript renderer with non-chat semantics",
+        "You only need a single generic card or empty state"
+      ],
+      "neverInvent": [
+        "Left/right-only layout rules",
+        "Raw shadcn theme colors",
+        "Utopia brand primitives inside reusable component logic",
+        "Arabic production copy generated by the component package"
+      ],
+      "ai": {
+        "props": {
+          "dir": "Use inherited dir by default. Set dir=\"rtl\" only for isolated smoke tests.",
+          "role": "Use user, assistant, or system where the component exposes message role.",
+          "metadata": "Pass localized timestamp/read/tool metadata from the app layer.",
+          "children": "Use product-owned copy. The design system supplies layout and tokens only.",
+          "accessibilityText": "The required label prop is localized product copy for the send action and current state."
+        },
+        "arabicFriendly": "Chat components use logical spacing, role-based alignment, mixed-script safe typography, and mirrored message flow in dir=\"rtl\". Do not invent Arabic copy in reusable components."
+      }
+    },
+    {
+      "name": "Chat System Message",
+      "category": "Chat",
+      "status": "available",
+      "packageImport": "import { ChatSystemMessage } from '@utopia-studio-design/design-system/Chat';",
+      "sourcePath": "packages/design-system/src/components/Chat.tsx",
+      "shadcnFoundation": [
+        "separator",
+        "shadcn/ui registry pattern",
+        "AI/chat product primitive",
+        "semantic Utopia wrapper"
+      ],
+      "fallbackToShadcn": "separator",
+      "requiredTokens": [
+        "--background",
+        "--surface",
+        "--surface-elevated",
+        "--surface-hover",
+        "--foreground",
+        "--foreground-muted",
+        "--border",
+        "--radius-control",
+        "--radius-surface",
+        "--space-1",
+        "--space-2",
+        "--space-3",
+        "--space-4",
+        "--duration-fast",
+        "--ease-standard",
+        "--focus-ring-width",
+        "--radius-chat-bubble",
+        "--radius-chat-composer",
+        "--radius-chat-token"
+      ],
+      "useWhen": [
+        "Building assistant, support, collaboration, or AI product chat surfaces",
+        "Message, composer, token, metadata, and tool-call regions need consistent reusable parts",
+        "The interface must support mixed-script content and dir=\"rtl\" layout without page-local rewrites"
+      ],
+      "avoidWhen": [
+        "The content is a static marketing testimonial rather than an interactive conversation",
+        "The product needs a bespoke transcript renderer with non-chat semantics",
+        "You only need a single generic card or empty state"
+      ],
+      "neverInvent": [
+        "Left/right-only layout rules",
+        "Raw shadcn theme colors",
+        "Utopia brand primitives inside reusable component logic",
+        "Arabic production copy generated by the component package"
+      ],
+      "ai": {
+        "props": {
+          "dir": "Use inherited dir by default. Set dir=\"rtl\" only for isolated smoke tests.",
+          "role": "Use user, assistant, or system where the component exposes message role.",
+          "metadata": "Pass localized timestamp/read/tool metadata from the app layer.",
+          "children": "Use product-owned copy. The design system supplies layout and tokens only."
+        },
+        "arabicFriendly": "Chat components use logical spacing, role-based alignment, mixed-script safe typography, and mirrored message flow in dir=\"rtl\". Do not invent Arabic copy in reusable components."
+      }
+    },
+    {
+      "name": "Chat Tokenized Text",
+      "category": "Chat",
+      "status": "available",
+      "packageImport": "import { ChatTokenizedText } from '@utopia-studio-design/design-system/Chat';",
+      "sourcePath": "packages/design-system/src/components/Chat.tsx",
+      "shadcnFoundation": [
+        "badge",
+        "shadcn/ui registry pattern",
+        "AI/chat product primitive",
+        "semantic Utopia wrapper"
+      ],
+      "fallbackToShadcn": "badge",
+      "requiredTokens": [
+        "--background",
+        "--surface",
+        "--surface-elevated",
+        "--surface-hover",
+        "--foreground",
+        "--foreground-muted",
+        "--border",
+        "--radius-control",
+        "--radius-surface",
+        "--space-1",
+        "--space-2",
+        "--space-3",
+        "--space-4",
+        "--duration-fast",
+        "--ease-standard",
+        "--focus-ring-width",
+        "--radius-chat-bubble",
+        "--radius-chat-composer",
+        "--radius-chat-token"
+      ],
+      "useWhen": [
+        "Building assistant, support, collaboration, or AI product chat surfaces",
+        "Message, composer, token, metadata, and tool-call regions need consistent reusable parts",
+        "The interface must support mixed-script content and dir=\"rtl\" layout without page-local rewrites"
+      ],
+      "avoidWhen": [
+        "The content is a static marketing testimonial rather than an interactive conversation",
+        "The product needs a bespoke transcript renderer with non-chat semantics",
+        "You only need a single generic card or empty state"
+      ],
+      "neverInvent": [
+        "Left/right-only layout rules",
+        "Raw shadcn theme colors",
+        "Utopia brand primitives inside reusable component logic",
+        "Arabic production copy generated by the component package"
+      ],
+      "ai": {
+        "props": {
+          "dir": "Use inherited dir by default. Set dir=\"rtl\" only for isolated smoke tests.",
+          "role": "Use user, assistant, or system where the component exposes message role.",
+          "metadata": "Pass localized timestamp/read/tool metadata from the app layer.",
+          "children": "Use product-owned copy. The design system supplies layout and tokens only."
+        },
+        "arabicFriendly": "Chat components use logical spacing, role-based alignment, mixed-script safe typography, and mirrored message flow in dir=\"rtl\". Do not invent Arabic copy in reusable components."
+      }
+    },
+    {
+      "name": "Chat Tool Calls",
+      "category": "Chat",
+      "status": "available",
+      "packageImport": "import { ChatToolCalls } from '@utopia-studio-design/design-system/Chat';",
+      "sourcePath": "packages/design-system/src/components/Chat.tsx",
+      "shadcnFoundation": [
+        "collapsible",
+        "shadcn/ui registry pattern",
+        "AI/chat product primitive",
+        "semantic Utopia wrapper"
+      ],
+      "fallbackToShadcn": "collapsible",
+      "requiredTokens": [
+        "--background",
+        "--surface",
+        "--surface-elevated",
+        "--surface-hover",
+        "--foreground",
+        "--foreground-muted",
+        "--border",
+        "--radius-control",
+        "--radius-surface",
+        "--space-1",
+        "--space-2",
+        "--space-3",
+        "--space-4",
+        "--duration-fast",
+        "--ease-standard",
+        "--focus-ring-width",
+        "--radius-chat-bubble",
+        "--radius-chat-composer",
+        "--radius-chat-token"
+      ],
+      "useWhen": [
+        "Building assistant, support, collaboration, or AI product chat surfaces",
+        "Message, composer, token, metadata, and tool-call regions need consistent reusable parts",
+        "The interface must support mixed-script content and dir=\"rtl\" layout without page-local rewrites"
+      ],
+      "avoidWhen": [
+        "The content is a static marketing testimonial rather than an interactive conversation",
+        "The product needs a bespoke transcript renderer with non-chat semantics",
+        "You only need a single generic card or empty state"
+      ],
+      "neverInvent": [
+        "Left/right-only layout rules",
+        "Raw shadcn theme colors",
+        "Utopia brand primitives inside reusable component logic",
+        "Arabic production copy generated by the component package"
+      ],
+      "ai": {
+        "props": {
+          "dir": "Use inherited dir by default. Set dir=\"rtl\" only for isolated smoke tests.",
+          "role": "Use user, assistant, or system where the component exposes message role.",
+          "metadata": "Pass localized timestamp/read/tool metadata from the app layer.",
+          "children": "Use product-owned copy. The design system supplies layout and tokens only.",
+          "accessibilityText": "The required label prop is a localized summary of the tool-call group; call labels, descriptions, durations, and states come from product data."
+        },
+        "arabicFriendly": "Chat components use logical spacing, role-based alignment, mixed-script safe typography, and mirrored message flow in dir=\"rtl\". Do not invent Arabic copy in reusable components."
+      }
+    },
+    {
+      "name": "Checkbox",
+      "category": "Forms",
+      "status": "available",
+      "packageImport": "import { Checkbox } from '@utopia-studio-design/design-system/Forms';",
+      "sourcePath": "packages/design-system/src/components/Forms.tsx",
+      "shadcnFoundation": [
+        "checkbox",
+        "Radix Checkbox",
+        "semantic Utopia wrapper"
+      ],
+      "fallbackToShadcn": "checkbox",
+      "requiredTokens": [
+        "--background",
+        "--foreground",
+        "--input",
+        "--primary",
+        "--primary-foreground",
+        "--radius-control",
+        "--focus-ring-width",
+        "--motion-duration-press",
+        "--motion-ease-standard"
+      ],
+      "useWhen": [
+        "Multi-select boolean choices",
+        "Terms acknowledgement",
+        "Independent option toggles in forms"
+      ],
+      "avoidWhen": [
+        "Single persistent settings",
+        "Exclusive choices",
+        "Actions that should be buttons"
+      ],
+      "neverInvent": [
+        "Left/right label placement",
+        "Left/right-only layout rules",
+        "Utopia brand primitives inside reusable component logic",
+        "Motion that bypasses MotionProvider or prefers-reduced-motion"
+      ],
+      "ai": {
+        "props": {
+          "motion": "Optional boolean. Defaults to the MotionProvider policy and disables this component pattern when false."
+        }
+      }
+    },
+    {
+      "name": "Collapsible",
+      "category": "Disclosure",
+      "status": "available",
+      "packageImport": "import { Collapsible, CollapsibleContent, CollapsibleTrigger } from '@utopia-studio-design/design-system/ShadcnPrimitives';",
+      "sourcePath": "packages/design-system/src/components/ShadcnPrimitives.tsx",
+      "shadcnFoundation": [
+        "collapsible",
+        "Radix Collapsible",
+        "shadcn/ui registry"
+      ],
+      "fallbackToShadcn": "collapsible",
+      "requiredTokens": [
+        "--surface",
+        "--foreground",
+        "--muted-foreground",
+        "--border",
+        "--radius-surface",
+        "--radius-control",
+        "--focus-ring-width",
+        "--motion-duration-expand",
+        "--motion-ease-standard"
+      ],
+      "useWhen": [
+        "Optional details",
+        "Progressive disclosure inside a page",
+        "Content that can be hidden without changing route"
+      ],
+      "avoidWhen": [
+        "Primary page navigation",
+        "Required instructions",
+        "Complex multi-section disclosure that should be Accordion"
+      ],
+      "neverInvent": [
+        "Raw shadcn theme colors",
+        "Left/right-only layout rules",
+        "Utopia brand primitives inside reusable component logic",
+        "Motion that bypasses MotionProvider or prefers-reduced-motion"
+      ],
+      "ai": {
+        "props": {
+          "motion": "Optional boolean. Defaults to the MotionProvider policy and disables this component pattern when false."
+        }
+      }
+    },
+    {
+      "name": "Combobox",
+      "category": "Forms",
+      "status": "available",
+      "packageImport": "import { Combobox, ComboboxContent, ComboboxInput, ComboboxOption, ComboboxTrigger } from '@utopia-studio-design/design-system/ShadcnPrimitives';",
+      "sourcePath": "packages/design-system/src/components/ShadcnPrimitives.tsx",
+      "shadcnFoundation": [
+        "combobox",
+        "shadcn/ui registry",
+        "semantic Utopia wrapper"
+      ],
+      "fallbackToShadcn": "combobox",
+      "requiredTokens": [
+        "--background",
+        "--foreground",
+        "--surface",
+        "--border",
+        "--radius-surface",
+        "--radius-control",
+        "--input",
+        "--surface-hover",
+        "--focus-ring-width"
+      ],
+      "useWhen": [
+        "Searchable selection from a known option set",
+        "AI-generated forms that need an explicit trigger, input, content, and option contract",
+        "Arabic-friendly product UI where option labels may be mixed-script or RTL"
+      ],
+      "avoidWhen": [
+        "A native select is sufficient",
+        "Free text input with no option selection",
+        "Product-specific filtering or async loading belongs in app logic"
+      ],
+      "neverInvent": [
+        "Raw shadcn theme colors",
+        "Left/right-only layout rules",
+        "Utopia brand primitives inside reusable component logic"
+      ]
+    },
+    {
+      "name": "Command",
+      "category": "Navigation",
+      "status": "available",
+      "packageImport": "import { Command, CommandPaletteEmpty, CommandPaletteGroup, CommandPaletteInput, CommandPaletteItem, CommandPaletteList } from '@utopia-studio-design/design-system/Navigation';",
+      "sourcePath": "packages/design-system/src/components/Navigation.tsx",
+      "shadcnFoundation": [
+        "command",
+        "cmdk",
+        "shadcn/ui command",
+        "semantic Utopia navigation wrapper"
+      ],
+      "fallbackToShadcn": "command",
+      "requiredTokens": [
+        "--surface",
+        "--border",
+        "--radius-surface",
+        "--input",
+        "--focus-ring-width",
+        "--foreground",
+        "--muted-foreground",
+        "--popover-surface",
+        "--surface-hover",
+        "--button-height"
+      ],
+      "useWhen": [
+        "Keyboard-first navigation and app command palettes",
+        "Global search with grouped suggestions and shortcuts",
+        "AI-generated admin surfaces where commands need explicit values and labels"
+      ],
+      "avoidWhen": [
+        "Small static menus that should use Dropdown Menu or Context Menu",
+        "Unstructured free-text search without command actions",
+        "Hidden shortcuts with no visible label or accessible value"
+      ],
+      "neverInvent": [
+        "Hidden commands without labels",
+        "Left/right-only layout rules",
+        "Utopia brand primitives inside reusable component logic"
+      ]
+    },
+    {
+      "name": "Context Menu",
+      "category": "Navigation",
+      "status": "available",
+      "packageImport": "import { ContextMenu, ContextMenuCheckboxItem, ContextMenuContent, ContextMenuItem, ContextMenuLabel, ContextMenuSeparator, ContextMenuShortcut, ContextMenuSub, ContextMenuSubContent, ContextMenuSubTrigger, ContextMenuTrigger } from '@utopia-studio-design/design-system/Navigation';",
+      "sourcePath": "packages/design-system/src/components/Navigation.tsx",
+      "shadcnFoundation": [
+        "context-menu",
+        "Radix Context Menu",
+        "shadcn/ui context-menu",
+        "semantic Utopia menu wrapper"
+      ],
+      "fallbackToShadcn": "context-menu",
+      "requiredTokens": [
+        "--surface",
+        "--border",
+        "--radius-surface",
+        "--focus-ring-width",
+        "--foreground",
+        "--muted-foreground",
+        "--popover-surface",
+        "--surface-hover",
+        "--button-height"
+      ],
+      "useWhen": [
+        "Secondary contextual actions triggered from right-click or long-press surfaces",
+        "Dense command sets that need labels, shortcuts, separators, checked state, or submenus",
+        "AI-generated product tools where contextual actions should stay separate from primary navigation"
+      ],
+      "avoidWhen": [
+        "Primary workflows that must be visible without right click",
+        "Mobile-only critical actions unless an equivalent visible trigger exists",
+        "Navigation menus that should be discoverable as Top Nav, Side Nav, or Dropdown Menu"
+      ],
+      "neverInvent": [
+        "Unavailable actions with no disabled state",
+        "Left/right-only layout rules",
+        "Utopia brand primitives inside reusable component logic"
+      ]
+    },
+    {
+      "name": "Data Table",
+      "category": "Data Display",
+      "status": "available",
+      "packageImport": "import { DataTable, DataTableBody, DataTableCell, DataTableFooter, DataTableHead, DataTableHeader, DataTableRow, DataTableShell, DataTableToolbar } from '@utopia-studio-design/design-system/ShadcnPrimitives';",
+      "sourcePath": "packages/design-system/src/components/ShadcnPrimitives.tsx",
+      "shadcnFoundation": [
+        "data-table",
+        "TanStack Table-compatible composition pattern",
+        "shadcn/ui registry",
+        "semantic Utopia wrapper"
+      ],
+      "fallbackToShadcn": "table",
+      "requiredTokens": [
+        "--background",
+        "--foreground",
+        "--surface",
+        "--border",
+        "--radius-surface",
+        "--radius-control",
+        "--muted-foreground",
+        "--surface-hover",
+        "--surface-strong",
+        "--input",
+        "--focus-ring-width"
+      ],
+      "useWhen": [
+        "Structured tabular data with headers and comparable rows",
+        "AI-generated admin/product views that need accessible table semantics",
+        "Arabic-friendly data displays that must preserve table meaning in dir='rtl'"
+      ],
+      "avoidWhen": [
+        "Card lists are easier to scan",
+        "Large virtualized data sets without product table requirements",
+        "Locale-specific sorting, formatting, or filtering inside the reusable primitive"
+      ],
+      "neverInvent": [
+        "Raw shadcn theme colors",
+        "Left/right-only layout rules",
+        "Utopia brand primitives inside reusable component logic"
+      ]
+    },
+    {
+      "name": "Date Picker",
+      "category": "Forms",
+      "status": "available",
+      "packageImport": "import { DatePicker } from '@utopia-studio-design/design-system/DataDisplay';",
+      "sourcePath": "packages/design-system/src/components/DataDisplay.tsx",
+      "shadcnFoundation": [
+        "date-picker",
+        "react-day-picker",
+        "Radix Popover",
+        "shadcn/ui date picker",
+        "semantic Utopia wrapper",
+        "controlled/uncontrolled state"
+      ],
+      "fallbackToShadcn": "calendar plus popover",
+      "requiredTokens": [
+        "--background",
+        "--foreground",
+        "--surface",
+        "--border",
+        "--radius-surface",
+        "--radius-control",
+        "--input",
+        "--primary",
+        "--primary-foreground",
+        "--surface-hover",
+        "--button-height-sm",
+        "--button-height-lg",
+        "--z-popover",
+        "--shadow-popover",
+        "--duration-fast",
+        "--ease-standard",
+        "--focus-ring-width"
+      ],
+      "useWhen": [
+        "Calendar-backed date selection",
+        "AI-generated forms that need a visible trigger and calendar grid contract",
+        "Arabic-friendly date UI where locale formatting belongs in product or theme configuration"
+      ],
+      "avoidWhen": [
+        "Plain date text is enough",
+        "Hijri or country-specific calendars before product requirements are defined",
+        "Business date validation inside the reusable primitive"
+      ],
+      "neverInvent": [
+        "Raw shadcn theme colors",
+        "Left/right-only layout rules",
+        "Utopia brand primitives inside reusable component logic",
+        "Product-specific date validation inside the reusable primitive"
+      ],
+      "ai": {
+        "props": {
+          "defaultSelectedDate": "Initial selected date for uncontrolled usage.",
+          "selectedDate": "Controlled selected date. Pair with onSelect.",
+          "onSelect": "Called with a Date and closes the popover by default.",
+          "locale": "Use a BCP 47 locale. Arabic locales switch the trigger, popover, and calendar to RTL.",
+          "weekStartsOn": "Use product locale requirements. 0 is Sunday, 1 Monday, 6 Saturday.",
+          "label": "Visible trigger label. Localize this in product copy.",
+          "placeholder": "Visible trigger placeholder. Localize this in product copy."
+        },
+        "arabicFriendly": "Date Picker mirrors the popover alignment and trigger direction for Arabic, delegates calendar labels to react-day-picker locale data, and keeps Hijri/calendar-system support explicit."
+      }
+    },
+    {
+      "name": "Dialog",
+      "category": "Feedback",
+      "status": "available",
+      "packageImport": "import { Dialog, DialogClose, DialogContent, DialogDescription, DialogFooter, DialogHeader, DialogTitle, DialogTrigger } from '@utopia-studio-design/design-system/ShadcnPrimitives';",
+      "sourcePath": "packages/design-system/src/components/ShadcnPrimitives.tsx",
+      "shadcnFoundation": [
+        "dialog",
+        "shadcn/ui registry",
+        "semantic Utopia wrapper"
+      ],
+      "fallbackToShadcn": "dialog",
+      "requiredTokens": [
+        "--background",
+        "--foreground",
+        "--surface",
+        "--border",
+        "--radius-surface",
+        "--radius-control",
+        "--z-overlay",
+        "--z-modal",
+        "--focus-ring-width",
+        "--overlay",
+        "--modal-surface",
+        "--motion-duration-reveal",
+        "--motion-ease-emphasized"
+      ],
+      "useWhen": [
+        "Focused interruptive content",
+        "Forms or details that need an overlay surface",
+        "AI-generated modals that need explicit trigger, content, title, description, and close parts"
+      ],
+      "avoidWhen": [
+        "Inline disclosure is enough",
+        "Irreversible confirmation that should use Alert Dialog",
+        "Product-specific flows hidden in reusable component logic"
+      ],
+      "neverInvent": [
+        "Raw shadcn theme colors",
+        "Left/right-only layout rules",
+        "Utopia brand primitives inside reusable component logic",
+        "Motion that bypasses MotionProvider or prefers-reduced-motion"
+      ],
+      "ai": {
+        "props": {
+          "motion": "Optional boolean. Defaults to the MotionProvider policy and disables this component pattern when false."
+        }
+      }
+    },
+    {
+      "name": "Direction",
+      "category": "Utilities",
+      "status": "available",
+      "packageImport": "import { Direction } from '@utopia-studio-design/design-system/ShadcnPrimitives';",
+      "sourcePath": "packages/design-system/src/components/ShadcnPrimitives.tsx",
+      "shadcnFoundation": [
+        "direction",
+        "shadcn/ui registry",
+        "semantic Utopia wrapper"
+      ],
+      "fallbackToShadcn": "direction",
+      "requiredTokens": [
+        "--background",
+        "--foreground",
+        "--surface",
+        "--border",
+        "--radius-surface",
+        "--font-arabic",
+        "--focus-ring-width"
+      ],
+      "useWhen": [
+        "Scoped RTL smoke checks",
+        "Mixed-script examples",
+        "AI-generated demos that need to prove start/end layout instead of left/right layout"
+      ],
+      "avoidWhen": [
+        "App-level direction can be set on the document",
+        "Arabic copy has not been localized or verified",
+        "A component needs behavioral RTL handling instead of just a direction scope"
+      ],
+      "neverInvent": [
+        "Raw shadcn theme colors",
+        "Left/right-only layout rules",
+        "Utopia brand primitives inside reusable component logic"
+      ]
+    },
+    {
+      "name": "Drawer",
+      "category": "Feedback",
+      "status": "available",
+      "packageImport": "import { Drawer, DrawerClose, DrawerContent, DrawerDescription, DrawerFooter, DrawerHeader, DrawerTitle, DrawerTrigger } from '@utopia-studio-design/design-system/ShadcnPrimitives';",
+      "sourcePath": "packages/design-system/src/components/ShadcnPrimitives.tsx",
+      "shadcnFoundation": [
+        "drawer",
+        "shadcn/ui registry",
+        "semantic Utopia wrapper"
+      ],
+      "fallbackToShadcn": "drawer",
+      "requiredTokens": [
+        "--background",
+        "--foreground",
+        "--surface",
+        "--border",
+        "--radius-surface",
+        "--radius-control",
+        "--z-overlay",
+        "--z-modal",
+        "--focus-ring-width",
+        "--overlay",
+        "--modal-surface",
+        "--motion-duration-reveal",
+        "--motion-ease-emphasized"
+      ],
+      "useWhen": [
+        "Supplemental panels that slide from logical start, end, or bottom",
+        "Mobile-friendly task surfaces",
+        "AI-generated layouts that need explicit side semantics for RTL"
+      ],
+      "avoidWhen": [
+        "A Dialog communicates the task better",
+        "Primary navigation that should use Side Nav or Sheet",
+        "Left/right side naming in reusable APIs"
+      ],
+      "neverInvent": [
+        "Raw shadcn theme colors",
+        "Left/right-only layout rules",
+        "Utopia brand primitives inside reusable component logic",
+        "Motion that bypasses MotionProvider or prefers-reduced-motion"
+      ],
+      "ai": {
+        "props": {
+          "motion": "Optional boolean. Defaults to the MotionProvider policy and disables this component pattern when false."
+        }
+      }
+    },
+    {
+      "name": "Dropdown Menu",
+      "category": "Navigation",
+      "status": "available",
+      "packageImport": "import { DropdownMenu, DropdownMenuCheckboxItem, DropdownMenuContent, DropdownMenuGroup, DropdownMenuItem, DropdownMenuLabel, DropdownMenuRadioGroup, DropdownMenuRadioItem, DropdownMenuSeparator, DropdownMenuShortcut, DropdownMenuSub, DropdownMenuSubContent, DropdownMenuSubTrigger, DropdownMenuTrigger } from '@utopia-studio-design/design-system/Navigation';",
+      "sourcePath": "packages/design-system/src/components/Navigation.tsx",
+      "shadcnFoundation": [
+        "dropdown-menu",
+        "Radix Dropdown Menu",
+        "DropdownMenuLabel",
+        "DropdownMenuSeparator",
+        "DropdownMenuSub",
+        "DropdownMenuGroup",
+        "DropdownMenuCheckboxItem",
+        "DropdownMenuRadioGroup",
+        "DropdownMenuRadioItem",
+        "DropdownMenuShortcut"
+      ],
+      "fallbackToShadcn": "dropdown-menu",
+      "requiredTokens": [
+        "--surface",
+        "--border",
+        "--radius-surface",
+        "--popover-surface",
+        "--destructive",
+        "--muted-foreground",
+        "--button-height",
+        "--focus-ring-width"
+      ],
+      "useWhen": [
+        "Compact action lists",
+        "Overflow actions",
+        "Grouped overflow actions with separators and submenus",
+        "Button Group overflow triggers",
+        "Checkbox and radio menu state",
+        "Keyboard shortcut hints",
+        "Submenu actions with RTL-aware indicators"
+      ],
+      "avoidWhen": [
+        "Primary page nav"
+      ],
+      "neverInvent": [
+        "Menu items without labels",
+        "Left/right-only layout rules",
+        "Utopia brand primitives inside reusable component logic",
+        "Destructive actions without semantic destructive state",
+        "Submenus without visible trigger text",
+        "Checkbox or radio menu items without checked state ownership",
+        "Shortcut text used as the only accessible label"
+      ],
+      "ai": {
+        "parts": [
+          "DropdownMenu",
+          "DropdownMenuTrigger",
+          "DropdownMenuContent",
+          "DropdownMenuGroup",
+          "DropdownMenuItem",
+          "DropdownMenuLabel",
+          "DropdownMenuSeparator",
+          "DropdownMenuCheckboxItem",
+          "DropdownMenuRadioGroup",
+          "DropdownMenuRadioItem",
+          "DropdownMenuShortcut",
+          "DropdownMenuSub",
+          "DropdownMenuSubTrigger",
+          "DropdownMenuSubContent"
+        ],
+        "arabicFriendly": [
+          "Use align=start/end instead of physical left/right positioning.",
+          "Submenu indicators mirror in dir=rtl.",
+          "Icon slots are optional; labels remain required.",
+          "Shortcut hints stay inline-end using logical spacing."
+        ],
+        "shadcnReferencePatterns": [
+          "basic menu",
+          "menu with icons",
+          "menu with shortcuts",
+          "checkbox items",
+          "radio group",
+          "submenu",
+          "destructive action"
+        ]
+      }
+    },
+    {
+      "name": "Empty",
+      "category": "Data Display",
+      "status": "available",
+      "packageImport": "import { Empty } from '@utopia-studio-design/design-system/DataDisplay';",
+      "sourcePath": "packages/design-system/src/components/DataDisplay.tsx",
+      "shadcnFoundation": [
+        "empty",
+        "semantic empty state"
+      ],
+      "fallbackToShadcn": "empty",
+      "requiredTokens": [
+        "--surface",
+        "--border",
+        "--radius-surface"
+      ],
+      "useWhen": [
+        "No data states",
+        "First-run guidance"
+      ],
+      "avoidWhen": [
+        "Error states"
+      ],
+      "neverInvent": [
+        "Marketing filler copy",
+        "Left/right-only layout rules",
+        "Utopia brand primitives inside reusable component logic"
+      ]
+    },
+    {
+      "name": "Field",
+      "category": "Forms",
+      "status": "available",
+      "packageImport": "import { Field, FieldContent, FieldDescription, FieldError, FieldGroup, FieldLabel, FieldLegend, FieldSeparator, FieldSet, FieldTitle } from '@utopia-studio-design/design-system/Forms';",
+      "sourcePath": "packages/design-system/src/components/Forms.tsx",
+      "shadcnFoundation": [
+        "field",
+        "label",
+        "input"
+      ],
+      "fallbackToShadcn": "field",
+      "requiredTokens": [
+        "--space-1",
+        "--space-2",
+        "--space-4",
+        "--foreground",
+        "--muted-foreground",
+        "--destructive",
+        "--border"
+      ],
+      "useWhen": [
+        "Form field composition",
+        "Related controls need a semantic fieldset",
+        "Labels, descriptions, and errors need a shared layout contract"
+      ],
+      "avoidWhen": [
+        "Inline metadata",
+        "Standalone text without a form control"
+      ],
+      "neverInvent": [
+        "Placeholder-only labels",
+        "Unconnected validation messages",
+        "Left/right orientation names",
+        "Left/right-only layout rules",
+        "Utopia brand primitives inside reusable component logic"
+      ]
+    },
+    {
+      "name": "Hover Card",
+      "category": "Surface",
+      "status": "available",
+      "packageImport": "import { HoverCard, HoverCardContent, HoverCardTrigger } from '@utopia-studio-design/design-system/Surface';",
+      "sourcePath": "packages/design-system/src/components/Surface.tsx",
+      "shadcnFoundation": [
+        "hover-card",
+        "Radix Hover Card"
+      ],
+      "fallbackToShadcn": "hover-card",
+      "requiredTokens": [
+        "--surface",
+        "--border",
+        "--shadow-popover",
+        "--radius-surface",
+        "--popover-surface",
+        "--floating-content-width",
+        "--motion-duration-reveal",
+        "--motion-ease-emphasized"
+      ],
+      "useWhen": [
+        "Supplemental previews",
+        "Nonessential hover detail",
+        "A link or compact trigger benefits from a sighted preview"
+      ],
+      "avoidWhen": [
+        "Critical instructions",
+        "Touch-only flows",
+        "Content must be keyboard or screen-reader discoverable without the trigger context"
+      ],
+      "neverInvent": [
+        "Required content hidden on hover",
+        "Unbounded popover widths",
+        "Physical left/right names for logical alignment",
+        "Hover-only product actions",
+        "Left/right-only layout rules",
+        "Utopia brand primitives inside reusable component logic",
+        "Motion that bypasses MotionProvider or prefers-reduced-motion"
+      ],
+      "ai": {
+        "props": {
+          "motion": "Optional boolean. Defaults to the MotionProvider policy and disables this component pattern when false."
+        }
+      }
+    },
+    {
+      "name": "Icon Button",
+      "category": "Action",
+      "status": "available",
+      "packageImport": "import { IconButton } from '@utopia-studio-design/design-system/IconButton';",
+      "sourcePath": "packages/design-system/src/components/IconButton.tsx",
+      "shadcnFoundation": [
+        "button",
+        "Slot",
+        "cva"
+      ],
+      "fallbackToShadcn": "shadcn/ui button with icon-only composition",
+      "requiredTokens": [
+        "--primary",
+        "--primary-hover",
+        "--primary-active",
+        "--secondary",
+        "--secondary-hover",
+        "--secondary-active",
+        "--ghost-hover",
+        "--ghost-active",
+        "--destructive",
+        "--destructive-hover",
+        "--destructive-active",
+        "--radius-control",
+        "--button-height",
+        "--button-height-sm",
+        "--button-height-lg",
+        "--focus-ring-width"
+      ],
+      "useWhen": [
+        "Compact repeated actions",
+        "Toolbar actions with recognizable icons",
+        "Side navigation collapse or utility controls"
+      ],
+      "avoidWhen": [
+        "Primary actions that need visible labels",
+        "Ambiguous actions without a tooltip or nearby context",
+        "Navigation labels that should remain readable"
+      ],
+      "neverInvent": [
+        "Unlabeled icon-only buttons",
+        "Theme-specific icon policy inside reusable component logic",
+        "Removing icon-only support because a theme discourages icons",
+        "Left/right-only icon direction rules",
+        "Utopia brand primitives inside reusable component logic"
+      ],
+      "ai": {
+        "props": [
+          "label",
+          "children",
+          "variant",
+          "size",
+          "disabled",
+          "loading",
+          "loadingText",
+          "asChild"
+        ],
+        "rules": [
+          "IconButton is the explicit reusable primitive for icon-only actions.",
+          "A theme may constrain which icons are appropriate, but must not remove the primitive or its accessibility contract.",
+          "Always provide label; visual children are not the accessible name."
+        ],
+        "arabicFriendly": [
+          "Mirror only directional icons in RTL; non-directional icons such as settings, add, download, and home should not be mirrored by default.",
+          "Use localized aria-label text supplied by the product; do not invent Arabic copy."
+        ]
+      }
+    },
+    {
+      "name": "Input",
+      "category": "Forms",
+      "status": "available",
+      "packageImport": "import { Input } from '@utopia-studio-design/design-system/Forms';",
+      "sourcePath": "packages/design-system/src/components/Forms.tsx",
+      "shadcnFoundation": [
+        "input",
+        "semantic form control"
+      ],
+      "fallbackToShadcn": "input",
+      "requiredTokens": [
+        "--input",
+        "--radius-control",
+        "--focus-ring-width"
+      ],
+      "useWhen": [
+        "Single-line text entry"
+      ],
+      "avoidWhen": [
+        "Long-form writing"
+      ],
+      "neverInvent": [
+        "Placeholder-only labels",
+        "Left/right-only layout rules",
+        "Utopia brand primitives inside reusable component logic"
+      ]
+    },
+    {
+      "name": "Input Group",
+      "category": "Forms",
+      "status": "available",
+      "packageImport": "import { InputGroup, InputGroupInput, InputGroupText } from '@utopia-studio-design/design-system/ShadcnPrimitives';",
+      "sourcePath": "packages/design-system/src/components/ShadcnPrimitives.tsx",
+      "shadcnFoundation": [
+        "input-group",
+        "shadcn/ui registry",
+        "semantic Utopia wrapper"
+      ],
+      "fallbackToShadcn": "input-group",
+      "requiredTokens": [
+        "--background",
+        "--foreground",
+        "--surface",
+        "--border",
+        "--radius-control",
+        "--input",
+        "--muted-foreground",
+        "--focus-ring-width"
+      ],
+      "useWhen": [
+        "Text input needs a prefix, suffix, unit, or scope label",
+        "AI-generated forms need explicit addon and input parts",
+        "Arabic-friendly forms need logical start/end addon placement"
+      ],
+      "avoidWhen": [
+        "A plain Input is sufficient",
+        "The addon is decorative only",
+        "Product validation or formatting belongs inside reusable component logic"
+      ],
+      "neverInvent": [
+        "Raw shadcn theme colors",
+        "Left/right-only layout rules",
+        "Utopia brand primitives inside reusable component logic"
+      ]
+    },
+    {
+      "name": "Input OTP",
+      "category": "Forms",
+      "status": "available",
+      "packageImport": "import { InputOTP } from '@utopia-studio-design/design-system/ShadcnPrimitives';",
+      "sourcePath": "packages/design-system/src/components/ShadcnPrimitives.tsx",
+      "shadcnFoundation": [
+        "input-otp",
+        "shadcn/ui registry",
+        "semantic Utopia wrapper"
+      ],
+      "fallbackToShadcn": "input-otp",
+      "requiredTokens": [
+        "--background",
+        "--foreground",
+        "--input",
+        "--radius-control",
+        "--focus-ring-width"
+      ],
+      "useWhen": [
+        "One-time passcodes",
+        "Short verification codes",
+        "AI-generated authentication examples that need accessible grouped digit slots"
+      ],
+      "avoidWhen": [
+        "Long secrets or passwords",
+        "Arbitrary numeric input",
+        "Verification transport or security logic inside the reusable primitive"
+      ],
+      "neverInvent": [
+        "Raw shadcn theme colors",
+        "Left/right-only layout rules",
+        "Utopia brand primitives inside reusable component logic"
+      ],
+      "ai": {
+        "props": {
+          "aria-label": "Required localized label for the complete one-time-code group.",
+          "getSlotLabel": "Required localization formatter that names each visual slot for assistive technology."
+        },
+        "arabicFriendly": "Supply Arabic slot labels and localized numerals from the product layer. Slot order follows inherited direction without hardcoded left/right spacing."
+      }
+    },
+    {
+      "name": "Item",
+      "category": "Data Display",
+      "status": "available",
+      "packageImport": "import { Item, ItemActions, ItemContent, ItemDescription, ItemTitle } from '@utopia-studio-design/design-system/ShadcnPrimitives';",
+      "sourcePath": "packages/design-system/src/components/ShadcnPrimitives.tsx",
+      "shadcnFoundation": [
+        "item",
+        "shadcn/ui registry",
+        "semantic Utopia wrapper"
+      ],
+      "fallbackToShadcn": "item",
+      "requiredTokens": [
+        "--background",
+        "--foreground",
+        "--surface",
+        "--border",
+        "--radius-surface",
+        "--muted-foreground",
+        "--focus-ring-width"
+      ],
+      "useWhen": [
+        "Repeated rows with title and description",
+        "Settings or resource lists with optional actions",
+        "AI-generated list rows that need stable title, description, and action slots"
+      ],
+      "avoidWhen": [
+        "Tabular comparison data",
+        "Complex cards with media or large content blocks",
+        "Navigation-only rows that should be links or menu items"
+      ],
+      "neverInvent": [
+        "Raw shadcn theme colors",
+        "Left/right-only layout rules",
+        "Utopia brand primitives inside reusable component logic"
+      ]
+    },
+    {
+      "name": "Kbd",
+      "category": "Data Display",
+      "status": "available",
+      "packageImport": "import { Kbd } from '@utopia-studio-design/design-system/ShadcnPrimitives';",
+      "sourcePath": "packages/design-system/src/components/ShadcnPrimitives.tsx",
+      "shadcnFoundation": [
+        "kbd",
+        "shadcn/ui registry",
+        "semantic Utopia wrapper"
+      ],
+      "fallbackToShadcn": "kbd",
+      "requiredTokens": [
+        "--foreground",
+        "--surface",
+        "--border",
+        "--radius-control",
+        "--focus-ring-width"
+      ],
+      "useWhen": [
+        "Keyboard shortcuts",
+        "Command hints",
+        "AI-readable docs that need compact key labels"
+      ],
+      "avoidWhen": [
+        "Clickable commands",
+        "Long instructions",
+        "Decorative keycap styling without an actual shortcut"
+      ],
+      "neverInvent": [
+        "Raw shadcn theme colors",
+        "Left/right-only layout rules",
+        "Utopia brand primitives inside reusable component logic"
+      ]
+    },
+    {
+      "name": "Label",
+      "category": "Forms",
+      "status": "available",
+      "packageImport": "import { Label } from '@utopia-studio-design/design-system/ShadcnPrimitives';",
+      "sourcePath": "packages/design-system/src/components/ShadcnPrimitives.tsx",
+      "shadcnFoundation": [
+        "label",
+        "shadcn/ui registry",
+        "semantic Utopia wrapper"
+      ],
+      "fallbackToShadcn": "label",
+      "requiredTokens": [
+        "--foreground",
+        "--muted-foreground",
+        "--destructive",
+        "--space-2"
+      ],
+      "useWhen": [
+        "Visible labels for checkboxes, switches, inputs, and other controls",
+        "Accessible control association through matching htmlFor and id values",
+        "AI-generated forms where placeholder-only labels are forbidden"
+      ],
+      "avoidWhen": [
+        "Decorative text",
+        "Complex fields that need descriptions, validation, or grouped layout; use Field instead",
+        "Field status or help text"
+      ],
+      "neverInvent": [
+        "A label whose htmlFor does not match the associated control id",
+        "Placeholder-only labeling",
+        "Production Arabic copy that was not supplied by localization",
+        "Left/right-only layout rules",
+        "Utopia brand primitives inside reusable component logic"
+      ]
+    },
+    {
+      "name": "Menubar",
+      "category": "Navigation",
+      "status": "available",
+      "packageImport": "import { Menubar, MenubarCheckboxItem, MenubarContent, MenubarGroup, MenubarItem, MenubarLabel, MenubarMenu, MenubarRadioGroup, MenubarRadioItem, MenubarSeparator, MenubarShortcut, MenubarSub, MenubarSubContent, MenubarSubTrigger, MenubarTrigger } from '@utopia-studio-design/design-system/ShadcnPrimitives';",
+      "sourcePath": "packages/design-system/src/components/ShadcnPrimitives.tsx",
+      "shadcnFoundation": [
+        "menubar",
+        "shadcn/ui registry",
+        "semantic Utopia wrapper"
+      ],
+      "fallbackToShadcn": "menubar",
+      "requiredTokens": [
+        "--foreground",
+        "--surface",
+        "--surface-hover",
+        "--muted-foreground",
+        "--border",
+        "--radius-surface",
+        "--radius-control",
+        "--secondary",
+        "--secondary-foreground",
+        "--z-popover",
+        "--focus-ring-width",
+        "--popover-surface"
+      ],
+      "useWhen": [
+        "Application-level command menus",
+        "Desktop-style grouped navigation actions",
+        "Persistent File, Edit, View, or Profiles command families",
+        "AI-generated command surfaces that need groups, checkbox items, radio items, shortcuts, or submenus"
+      ],
+      "avoidWhen": [
+        "Simple page navigation where Top Nav or Navigation Menu is clearer",
+        "Mobile-first primary navigation",
+        "A single contextual action menu where Dropdown Menu is clearer"
+      ],
+      "neverInvent": [
+        "Keyboard shortcuts that the application has not registered",
+        "Checkbox or radio state without application-owned state",
+        "Production Arabic command labels not supplied by localization",
+        "Left/right-only layout rules",
+        "Utopia brand primitives inside reusable component logic"
+      ]
+    },
+    {
+      "category": "Navigation",
+      "status": "available",
+      "sourcePath": "packages/design-system/src/components/Navigation.tsx",
+      "neverInvent": [
+        "Raw shadcn theme colors",
+        "Left/right-only layout rules",
+        "Utopia brand primitives inside reusable component logic",
+        "Invented Arabic production copy"
+      ],
+      "name": "Mobile Nav",
+      "packageImport": "import { MobileNav, MobileNavContent, MobileNavToggle, MobileNavTrigger } from '@utopia-studio-design/design-system/Navigation';",
+      "shadcnFoundation": [
+        "dialog",
+        "sheet",
+        "Radix Dialog",
+        "shadcn/ui sheet composition"
+      ],
+      "fallbackToShadcn": "sheet",
+      "requiredTokens": [
+        "--foreground",
+        "--muted-foreground",
+        "--secondary",
+        "--secondary-foreground",
+        "--border",
+        "--radius-control",
+        "--radius-surface",
+        "--popover-surface",
+        "--focus-ring-width",
+        "--modal-surface",
+        "--overlay",
+        "--z-modal"
+      ],
+      "useWhen": [
+        "Small viewport navigation needs an off-canvas panel",
+        "Desktop Top Nav or Side Nav needs a mobile counterpart",
+        "A mobile IA surface needs Dialog accessibility and escape/outside-click behavior"
+      ],
+      "avoidWhen": [
+        "Always-visible desktop navigation",
+        "Non-navigation drawers that should use Drawer or Sheet"
+      ],
+      "ai": {
+        "props": {
+          "defaultOpen": "Initial uncontrolled open state.",
+          "open": "Controlled open state.",
+          "onOpenChange": "Radix Dialog state callback.",
+          "children": "MobileNavTrigger and MobileNavContent."
+        },
+        "arabicFriendly": "Panel opens from inline start, which becomes the right side in RTL. Use logical spacing and localized labels."
+      }
+    },
+    {
+      "category": "Navigation",
+      "status": "available",
+      "sourcePath": "packages/design-system/src/components/Navigation.tsx",
+      "neverInvent": [
+        "Raw shadcn theme colors",
+        "Left/right-only layout rules",
+        "Utopia brand primitives inside reusable component logic",
+        "Invented Arabic production copy"
+      ],
+      "name": "Mobile Nav Toggle",
+      "packageImport": "import { MobileNavToggle } from '@utopia-studio-design/design-system/Navigation';",
+      "shadcnFoundation": [
+        "button",
+        "icon-only button",
+        "Dialog trigger composition"
+      ],
+      "fallbackToShadcn": "button",
+      "requiredTokens": [
+        "--foreground",
+        "--muted-foreground",
+        "--secondary",
+        "--secondary-foreground",
+        "--border",
+        "--radius-control",
+        "--radius-surface",
+        "--popover-surface",
+        "--focus-ring-width"
+      ],
+      "useWhen": [
+        "An icon-only control opens or closes Mobile Nav",
+        "The trigger needs Button semantics with accessible label"
+      ],
+      "avoidWhen": [
+        "Visible text buttons",
+        "Desktop side nav collapse; use SideNavCollapseButton"
+      ],
+      "ai": {
+        "props": {
+          "aria-label": "Required accessible label.",
+          "open": "Optional visual open state.",
+          "children": "Icon-only visual content."
+        },
+        "arabicFriendly": "Use direction-neutral menu icons unless product supplies mirrored directional icons."
+      }
+    },
+    {
+      "name": "Native Select",
+      "category": "Forms",
+      "status": "available",
+      "packageImport": "import { NativeSelect, NativeSelectOptGroup, NativeSelectOption } from '@utopia-studio-design/design-system/ShadcnPrimitives';",
+      "sourcePath": "packages/design-system/src/components/ShadcnPrimitives.tsx",
+      "shadcnFoundation": [
+        "native-select",
+        "shadcn/ui registry",
+        "semantic Utopia wrapper"
+      ],
+      "fallbackToShadcn": "native-select",
+      "requiredTokens": [
+        "--background",
+        "--foreground",
+        "--muted-foreground",
+        "--surface-hover",
+        "--destructive",
+        "--input",
+        "--radius-control",
+        "--focus-ring-width",
+        "--popover-surface"
+      ],
+      "useWhen": [
+        "Simple or grouped option selection using native browser behavior",
+        "Performance-sensitive forms and mobile-optimized platform pickers",
+        "Disabled or invalid form states that must retain native semantics",
+        "Arabic-friendly forms that need platform behavior before custom Select is necessary"
+      ],
+      "avoidWhen": [
+        "Searchable or async option sets",
+        "Complex custom option rendering",
+        "Product localization rules inside reusable component logic"
+      ],
+      "neverInvent": [
+        "Product-owned option values or selection rules",
+        "Production Arabic option labels not supplied by localization",
+        "Left/right-only layout rules",
+        "Utopia brand primitives inside reusable component logic"
+      ]
+    },
+    {
+      "category": "Navigation",
+      "status": "available",
+      "sourcePath": "packages/design-system/src/components/Navigation.tsx",
+      "neverInvent": [
+        "Raw shadcn theme colors",
+        "Left/right-only layout rules",
+        "Utopia brand primitives inside reusable component logic",
+        "Invented Arabic production copy"
+      ],
+      "name": "Nav Heading Menu",
+      "packageImport": "import { NavHeadingMenu, NavHeadingMenuContent, NavHeadingMenuTrigger } from '@utopia-studio-design/design-system/Navigation';",
+      "shadcnFoundation": [
+        "dropdown-menu",
+        "Radix DropdownMenu",
+        "heading selector menu"
+      ],
+      "fallbackToShadcn": "dropdown-menu",
+      "requiredTokens": [
+        "--foreground",
+        "--muted-foreground",
+        "--secondary",
+        "--secondary-foreground",
+        "--border",
+        "--radius-control",
+        "--radius-surface",
+        "--popover-surface",
+        "--focus-ring-width"
+      ],
+      "useWhen": [
+        "A nav heading needs a workspace/version/project selector",
+        "SideNavHeading or mobile nav heading needs an end-slot menu"
+      ],
+      "avoidWhen": [
+        "Primary navigation link lists",
+        "Arbitrary action menus outside navigation headings"
+      ],
+      "ai": {
+        "props": {
+          "children": "NavHeadingMenuTrigger and NavHeadingMenuContent."
+        },
+        "arabicFriendly": "Align content using logical start/end; labels come from localization."
+      }
+    },
+    {
+      "category": "Navigation",
+      "status": "available",
+      "sourcePath": "packages/design-system/src/components/Navigation.tsx",
+      "neverInvent": [
+        "Raw shadcn theme colors",
+        "Left/right-only layout rules",
+        "Utopia brand primitives inside reusable component logic",
+        "Invented Arabic production copy"
+      ],
+      "name": "Nav Icon",
+      "packageImport": "import { NavIcon } from '@utopia-studio-design/design-system/Navigation';",
+      "shadcnFoundation": [
+        "button",
+        "icon-only button",
+        "navigation utility action"
+      ],
+      "fallbackToShadcn": "button",
+      "requiredTokens": [
+        "--foreground",
+        "--muted-foreground",
+        "--secondary",
+        "--secondary-foreground",
+        "--border",
+        "--radius-control",
+        "--radius-surface",
+        "--popover-surface",
+        "--focus-ring-width"
+      ],
+      "useWhen": [
+        "Top Nav, Mobile Nav, or nav heading needs icon-only utility actions like search, notifications, account, or workspace menus",
+        "A navigation icon needs Button accessibility and tokenized hover/focus states"
+      ],
+      "avoidWhen": [
+        "Content icons inside body copy",
+        "Navigation links with visible text; use TopNavItem or SideNavItem"
+      ],
+      "ai": {
+        "props": {
+          "aria-label": "Required accessible label.",
+          "active": "Selected visual state.",
+          "children": "Icon-only visual content."
+        },
+        "arabicFriendly": "Directional icons must mirror or be replaced in RTL; direction-neutral icons need no mirroring."
+      }
+    },
+    {
+      "name": "Navigation Menu",
+      "category": "Navigation",
+      "status": "available",
+      "packageImport": "import { NavigationMenu, NavigationMenuContent, NavigationMenuIndicator, NavigationMenuItem, NavigationMenuLink, NavigationMenuList, NavigationMenuTrigger, NavigationMenuViewport } from '@utopia-studio-design/design-system/ShadcnPrimitives';",
+      "sourcePath": "packages/design-system/src/components/ShadcnPrimitives.tsx",
+      "shadcnFoundation": [
+        "navigation-menu",
+        "shadcn/ui registry",
+        "semantic Utopia wrapper"
+      ],
+      "fallbackToShadcn": "navigation-menu",
+      "requiredTokens": [
+        "--background",
+        "--foreground",
+        "--surface",
+        "--border",
+        "--radius-surface",
+        "--radius-control",
+        "--secondary",
+        "--secondary-foreground",
+        "--surface-hover",
+        "--muted-foreground",
+        "--z-popover",
+        "--focus-ring-width",
+        "--duration-fast",
+        "--duration-medium",
+        "--ease-standard"
+      ],
+      "useWhen": [
+        "Top-level navigation with nested content",
+        "Documentation or product navigation where a menu trigger reveals related links",
+        "AI-generated navigation that needs explicit root, list, item, trigger, content, link, and viewport parts"
+      ],
+      "avoidWhen": [
+        "Simple inline links are enough",
+        "Mobile primary navigation that should use Mobile Nav or Sheet",
+        "Action commands that should use Menubar or Command",
+        "Navigation labels without product-owned copy"
+      ],
+      "neverInvent": [
+        "Raw shadcn theme colors",
+        "Left/right-only layout rules; use logical start/end and dir instead",
+        "Product routes or Arabic production copy that were not supplied",
+        "Utopia brand primitives inside reusable component logic"
+      ]
+    },
+    {
+      "name": "Pagination",
+      "category": "Navigation",
+      "status": "available",
+      "packageImport": "import { Pagination, PaginationContent, PaginationEllipsis, PaginationItem, PaginationLink, PaginationNext, PaginationPrevious } from '@utopia-studio-design/design-system/ShadcnPrimitives';",
+      "sourcePath": "packages/design-system/src/components/ShadcnPrimitives.tsx",
+      "shadcnFoundation": [
+        "pagination",
+        "shadcn/ui registry",
+        "semantic Utopia wrapper"
+      ],
+      "fallbackToShadcn": "pagination",
+      "requiredTokens": [
+        "--foreground",
+        "--surface",
+        "--border",
+        "--radius-control",
+        "--secondary",
+        "--secondary-foreground",
+        "--muted-foreground",
+        "--focus-ring-width",
+        "--focus-ring-offset"
+      ],
+      "useWhen": [
+        "Paged result sets",
+        "Tables or lists with known page navigation",
+        "AI-generated data views that need previous, next, and current page semantics"
+      ],
+      "avoidWhen": [
+        "Infinite scrolling is the product pattern",
+        "Small result sets",
+        "Unknown or continuously loaded result sets where pagination would misrepresent progress",
+        "Action controls that only resemble page navigation"
+      ],
+      "neverInvent": [
+        "Raw shadcn theme colors",
+        "Left/right-only layout rules or unmirrored directional icons",
+        "Page totals, localized numerals, or Arabic labels not supplied by product data",
+        "Utopia brand primitives inside reusable component logic"
+      ],
+      "ai": {
+        "props": {
+          "aria-label": "Required localized label for the pagination navigation landmark.",
+          "PaginationPrevious.text": "Required localized visible previous-page label.",
+          "PaginationNext.text": "Required localized visible next-page label.",
+          "PaginationEllipsis.label": "Required localized screen-reader label for omitted pages."
+        },
+        "arabicFriendly": "Pass localized labels and numerals from product code. Previous and next icons mirror through dir=\"rtl\" while the component uses logical spacing."
+      }
+    },
+    {
+      "name": "Popover",
+      "category": "Surface",
+      "status": "available",
+      "packageImport": "import { Popover, PopoverAnchor, PopoverClose, PopoverContent, PopoverDescription, PopoverHeader, PopoverTitle, PopoverTrigger } from '@utopia-studio-design/design-system/Surface';",
+      "sourcePath": "packages/design-system/src/components/Surface.tsx",
+      "shadcnFoundation": [
+        "popover",
+        "Radix Popover"
+      ],
+      "fallbackToShadcn": "popover",
+      "requiredTokens": [
+        "--surface",
+        "--border",
+        "--shadow-popover",
+        "--radius-surface",
+        "--z-popover",
+        "--focus-ring-width",
+        "--focus-ring-offset",
+        "--surface-hover",
+        "--muted-foreground",
+        "--popover-surface",
+        "--motion-duration-reveal",
+        "--motion-ease-emphasized"
+      ],
+      "useWhen": [
+        "Small contextual panels",
+        "Inline configuration",
+        "Non-modal supplemental controls that can be dismissed"
+      ],
+      "avoidWhen": [
+        "Long forms",
+        "Full workflows",
+        "Critical confirmations"
+      ],
+      "neverInvent": [
+        "Modal behavior",
+        "Left/right-only alignment rules instead of logical start/end alignment",
+        "Product form values, Arabic production copy, or persistence behavior",
+        "Utopia brand primitives inside reusable component logic",
+        "Motion that bypasses MotionProvider or prefers-reduced-motion"
+      ],
+      "ai": {
+        "props": {
+          "motion": "Optional boolean. Defaults to the MotionProvider policy and disables this component pattern when false."
+        }
+      }
+    },
+    {
+      "name": "Progress",
+      "category": "Data Display",
+      "status": "available",
+      "packageImport": "import { Progress, ProgressIndicator, ProgressLabel, ProgressTrack, ProgressValue } from '@utopia-studio-design/design-system/DataDisplay';",
+      "sourcePath": "packages/design-system/src/components/DataDisplay.tsx",
+      "shadcnFoundation": [
+        "progress",
+        "semantic progress indicator"
+      ],
+      "fallbackToShadcn": "progress",
+      "requiredTokens": [
+        "--primary",
+        "--secondary",
+        "--success",
+        "--warning",
+        "--destructive",
+        "--muted-foreground",
+        "--radius-control",
+        "--duration-medium",
+        "--duration-slow",
+        "--ease-standard"
+      ],
+      "useWhen": [
+        "Known progress values",
+        "Uploads, setup steps, or task completion where aria-valuenow is meaningful"
+      ],
+      "avoidWhen": [
+        "Unknown loading states unless indeterminate is explicitly selected",
+        "Decorative completion bars"
+      ],
+      "neverInvent": [
+        "Missing aria-valuenow for determinate progress",
+        "Invented percentages or completion states not supplied by product data",
+        "Left/right-only layout rules",
+        "Utopia brand primitives inside reusable component logic"
+      ],
+      "ai": {
+        "props": {
+          "value": "Known numeric completion supplied by product state.",
+          "indeterminate": "Use only when completion cannot be quantified.",
+          "valueText": "Localized visible value such as Arabic numerals; keep numeric aria-valuenow on the track.",
+          "status": "Semantic task status, never a raw color choice."
+        },
+        "arabicFriendly": "Progress grows from inline-start, indeterminate motion follows logical direction, and localized valueText is separate from numeric aria-valuenow."
+      }
+    },
+    {
+      "name": "Radio Group",
+      "category": "Forms",
+      "status": "available",
+      "packageImport": "import { RadioGroup, RadioGroupItem, RadioGroupOption } from '@utopia-studio-design/design-system/Forms';",
+      "sourcePath": "packages/design-system/src/components/Forms.tsx",
+      "shadcnFoundation": [
+        "radio-group",
+        "semantic form choice"
+      ],
+      "fallbackToShadcn": "radio-group",
+      "requiredTokens": [
+        "--primary",
+        "--primary-foreground",
+        "--input",
+        "--background",
+        "--surface",
+        "--surface-hover",
+        "--border",
+        "--muted-foreground",
+        "--destructive",
+        "--radius-surface",
+        "--focus-ring",
+        "--focus-ring-width",
+        "--focus-ring-offset"
+      ],
+      "useWhen": [
+        "Single choice from visible options",
+        "Settings where all options should be visible",
+        "Arabic-friendly forms that need label and control order to mirror with dir='rtl'"
+      ],
+      "avoidWhen": [
+        "Independent booleans",
+        "Large option sets",
+        "Compact selects are clearer"
+      ],
+      "neverInvent": [
+        "Checkbox behavior",
+        "A card option without the same keyboard and selection contract as a standard option",
+        "Product labels, descriptions, or selected values not supplied by the consumer",
+        "Left/right-only layout rules",
+        "Utopia brand primitives inside reusable component logic"
+      ],
+      "ai": {
+        "props": {
+          "value": "Controlled selected value for a mutually exclusive option set.",
+          "defaultValue": "Initial value for an uncontrolled option set.",
+          "onValueChange": "Receives the selected option value.",
+          "orientation": "Keyboard navigation orientation: vertical or horizontal.",
+          "variant": "RadioGroupOption presentation: default for dense forms or card for descriptive choices.",
+          "label": "Visible option label supplied by product or localization.",
+          "description": "Optional supporting text; do not repeat the label."
+        },
+        "arabicFriendly": "The control and copy follow logical inline order under dir='rtl'; labels align to inline-start, and card selection does not depend on a left/right position."
+      }
+    },
+    {
+      "name": "Resizable",
+      "category": "Layout",
+      "status": "available",
+      "packageImport": "import { Resizable, ResizableHandle, ResizablePanel } from '@utopia-studio-design/design-system/ShadcnPrimitives';",
+      "sourcePath": "packages/design-system/src/components/ShadcnPrimitives.tsx",
+      "shadcnFoundation": [
+        "resizable",
+        "shadcn/ui registry",
+        "semantic Utopia wrapper"
+      ],
+      "fallbackToShadcn": "resizable",
+      "requiredTokens": [
+        "--background",
+        "--foreground",
+        "--surface",
+        "--border",
+        "--radius-surface",
+        "--focus-ring-width"
+      ],
+      "useWhen": [
+        "Split-pane layouts",
+        "Inspector/editor surfaces where panel sizes are user-adjustable",
+        "AI-generated app shells that need explicit panel and handle parts"
+      ],
+      "avoidWhen": [
+        "Static content layout",
+        "Mobile layouts without a resize affordance",
+        "Persistence or storage logic inside reusable component code"
+      ],
+      "neverInvent": [
+        "Raw shadcn theme colors",
+        "A decorative divider that cannot be focused or resized with the keyboard",
+        "A visible grip without the ResizableHandle separator behavior",
+        "Left/right-only layout rules",
+        "Utopia brand primitives inside reusable component logic"
+      ],
+      "ai": {
+        "props": {
+          "orientation": "Use horizontal for inline panels and vertical for stacked panels.",
+          "defaultSize": "Initial panel percentage or size supplied by the product layout.",
+          "withHandle": "Adds a visible grip without changing separator behavior.",
+          "onLayoutChange": "Optional consumer-owned persistence hook; storage stays outside the component."
+        },
+        "arabicFriendly": "Horizontal panels follow DOM and logical inline order under dir='rtl'; do not encode left/right ownership in component props. Vertical resizing is direction-neutral."
+      }
+    },
+    {
+      "name": "Scroll Area",
+      "category": "Layout",
+      "status": "available",
+      "packageImport": "import { ScrollArea, ScrollAreaCorner, ScrollAreaViewport, ScrollBar } from '@utopia-studio-design/design-system/ShadcnPrimitives';",
+      "sourcePath": "packages/design-system/src/components/ShadcnPrimitives.tsx",
+      "shadcnFoundation": [
+        "scroll-area",
+        "shadcn/ui registry",
+        "semantic Utopia wrapper"
+      ],
+      "fallbackToShadcn": "scroll-area",
+      "requiredTokens": [
+        "--background",
+        "--foreground",
+        "--surface",
+        "--surface-strong",
+        "--border",
+        "--muted-foreground",
+        "--radius-surface",
+        "--radius-control",
+        "--duration-fast",
+        "--ease-standard",
+        "--focus-ring-width"
+      ],
+      "useWhen": [
+        "Constrained panels with overflow content",
+        "Scrollable side navigation regions, menus, and inspector regions",
+        "AI-generated layouts that need an explicit viewport and scrollbar contract"
+      ],
+      "avoidWhen": [
+        "Page-level document scrolling is enough",
+        "Virtualized large lists",
+        "Hiding essential content behind an unlabelled scroll region"
+      ],
+      "neverInvent": [
+        "Raw shadcn theme colors",
+        "A fixed component width or height instead of a consumer-owned layout constraint",
+        "Always-visible scrollbars when hover or auto behavior is sufficient",
+        "Horizontal content that assumes the physical left edge is the start",
+        "Left/right-only layout rules",
+        "Utopia brand primitives inside reusable component logic"
+      ],
+      "ai": {
+        "props": {
+          "type": "Scrollbar visibility behavior; hover is the default, with auto, scroll, and always available when explicitly required.",
+          "orientation": "Set each ScrollBar to vertical or horizontal; render both plus ScrollAreaCorner for two-axis content.",
+          "dir": "Inherit or set ltr/rtl so horizontal scrolling follows the locale direction."
+        },
+        "arabicFriendly": "Horizontal galleries begin at logical inline-start under dir='rtl'; content alignment uses start/end and scrollbar behavior must not assume a physical left origin."
+      }
+    },
+    {
+      "name": "Select",
+      "category": "Forms",
+      "status": "available",
+      "packageImport": "import { Select, SelectContent, SelectGroup, SelectItem, SelectLabel, SelectScrollDownButton, SelectScrollUpButton, SelectSeparator, SelectTrigger, SelectValue } from '@utopia-studio-design/design-system/Forms';",
+      "sourcePath": "packages/design-system/src/components/Forms.tsx",
+      "shadcnFoundation": [
+        "select",
+        "semantic selection control",
+        "Radix Select",
+        "SelectGroup",
+        "SelectLabel",
+        "SelectSeparator",
+        "SelectScrollUpButton",
+        "SelectScrollDownButton"
+      ],
+      "fallbackToShadcn": "select",
+      "requiredTokens": [
+        "--input",
+        "--surface",
+        "--radius-control",
+        "--radius-surface",
+        "--z-popover",
+        "--focus-ring-width",
+        "--popover-surface",
+        "--background",
+        "--foreground",
+        "--muted-foreground",
+        "--button-height-sm"
+      ],
+      "useWhen": [
+        "Compact option selection",
+        "Longer option sets than Radio Group",
+        "AI-generated forms that need explicit trigger, value, content, and item parts",
+        "Grouped option lists with labels",
+        "Long option sets that need scroll buttons",
+        "Disabled options with visible state"
+      ],
+      "avoidWhen": [
+        "Few visible choices where radio is clearer",
+        "Searchable or async options that need Combobox",
+        "Native platform select is enough"
+      ],
+      "neverInvent": [
+        "Menu without keyboard labels",
+        "Left/right-only layout rules",
+        "Utopia brand primitives inside reusable component logic",
+        "Searchable async options; use Combobox",
+        "Unlabeled SelectTrigger controls",
+        "Physical left/right placement APIs"
+      ],
+      "ai": {
+        "parts": [
+          "Select",
+          "SelectTrigger",
+          "SelectValue",
+          "SelectContent",
+          "SelectGroup",
+          "SelectLabel",
+          "SelectItem",
+          "SelectSeparator",
+          "SelectScrollUpButton",
+          "SelectScrollDownButton"
+        ],
+        "shadcnReferencePatterns": [
+          "basic select",
+          "select with groups",
+          "disabled option",
+          "scrollable select",
+          "RTL select"
+        ],
+        "arabicFriendly": [
+          "Use aria-label or an external FieldLabel for the trigger.",
+          "Use align=start/end for content placement and let dir=rtl handle inline flow.",
+          "Keep selected indicators and labels visible for mixed-script text.",
+          "Do not use native select when a tokenized shadcn/Utopia surface is required."
+        ]
+      }
+    },
+    {
+      "name": "Separator",
+      "category": "Layout",
+      "status": "available",
+      "packageImport": "import { Separator } from '@utopia-studio-design/design-system/ShadcnPrimitives';",
+      "sourcePath": "packages/design-system/src/components/ShadcnPrimitives.tsx",
+      "shadcnFoundation": [
+        "separator",
+        "shadcn/ui registry",
+        "semantic Utopia wrapper"
+      ],
+      "fallbackToShadcn": "separator",
+      "requiredTokens": [
+        "--border"
+      ],
+      "useWhen": [
+        "Separating related sections",
+        "Visual grouping inside dense surfaces",
+        "AI-generated layouts that need semantic dividers without decorative lines"
+      ],
+      "avoidWhen": [
+        "Spacing alone communicates the grouping",
+        "A heading or landmark is required",
+        "Decorative rules that do not communicate structure"
+      ],
+      "neverInvent": [
+        "Raw shadcn theme colors",
+        "Left/right-only layout rules",
+        "Utopia brand primitives inside reusable component logic"
+      ]
+    },
+    {
+      "name": "Sheet",
+      "category": "Feedback",
+      "status": "available",
+      "packageImport": "import { Sheet, SheetClose, SheetContent, SheetDescription, SheetFooter, SheetHeader, SheetTitle, SheetTrigger } from '@utopia-studio-design/design-system/ShadcnPrimitives';",
+      "sourcePath": "packages/design-system/src/components/ShadcnPrimitives.tsx",
+      "shadcnFoundation": [
+        "sheet",
+        "shadcn/ui registry",
+        "semantic Utopia wrapper"
+      ],
+      "fallbackToShadcn": "sheet",
+      "requiredTokens": [
+        "--background",
+        "--foreground",
+        "--surface",
+        "--border",
+        "--radius-surface",
+        "--radius-control",
+        "--z-overlay",
+        "--z-modal",
+        "--focus-ring-width",
+        "--overlay",
+        "--modal-surface",
+        "--motion-duration-reveal",
+        "--motion-ease-emphasized"
+      ],
+      "useWhen": [
+        "Supplemental panels attached to a logical side",
+        "Configuration or navigation surfaces that should not become full Dialogs",
+        "AI-generated panels that need explicit trigger, content, header, footer, title, description, and close parts"
+      ],
+      "avoidWhen": [
+        "A centered Dialog is clearer",
+        "Primary page layout that should use Side Nav",
+        "Left/right side names instead of start/end or logical side handling"
+      ],
+      "neverInvent": [
+        "Raw shadcn theme colors",
+        "Left/right-only layout rules",
+        "Utopia brand primitives inside reusable component logic",
+        "Motion that bypasses MotionProvider or prefers-reduced-motion"
+      ],
+      "ai": {
+        "props": {
+          "motion": "Optional boolean. Defaults to the MotionProvider policy and disables this component pattern when false."
+        }
+      }
+    },
+    {
+      "name": "Side Nav",
+      "category": "Navigation",
+      "status": "available",
+      "packageImport": "import { PanelIcon, SideNav, SideNavCollapseButton, SideNavContent, SideNavHeading, SideNavItem, SideNavNestedGroup, SideNavNestedItems, SideNavSearch, SideNavSection } from '@utopia-studio-design/design-system/Navigation';",
+      "sourcePath": "packages/design-system/src/components/Navigation.tsx",
+      "shadcnFoundation": [
+        "sidebar",
+        "navigation",
+        "shadcn/ui composition",
+        "semantic Utopia wrapper"
+      ],
+      "fallbackToShadcn": "sidebar",
+      "requiredTokens": [
+        "--background",
+        "--foreground",
+        "--border",
+        "--radius-control",
+        "--secondary",
+        "--secondary-foreground",
+        "--muted-foreground",
+        "--foreground-subtle",
+        "--button-height-sm",
+        "--focus-ring-width"
+      ],
+      "useWhen": [
+        "Persistent docs or app navigation",
+        "Grouped navigation links with current page state",
+        "A navigation surface needs package-owned content, search, section, nested group, item, heading, account, and collapse composition parts",
+        "A navigation surface should receive heading and search as SideNav props instead of hardcoding local wrappers",
+        "AI-generated app shells that need explicit section, heading, item, nested item, search, and collapse button parts"
+      ],
+      "avoidWhen": [
+        "Temporary panels that should use Sheet",
+        "Top-level horizontal navigation that should use Top Nav",
+        "Navigation without accessible labels or current state"
+      ],
+      "neverInvent": [
+        "Raw shadcn theme colors",
+        "Left/right-only layout rules",
+        "Utopia brand primitives inside reusable component logic",
+        "Local CSS-only search, nested group, or content wrappers when SideNavSearch, SideNavNestedGroup, SideNavNestedItems, or SideNavContent are available"
+      ],
+      "ai": {
+        "props": {
+          "collapsed": "Sets the collapsed side navigation state and hides labels, badges, and account copy while preserving icon-only affordances.",
+          "density": "Use default for app navigation; use compact for docs/library sidebars with dense catalog lists.",
+          "heading": "Optional SideNavHeading node rendered before search and navigation content.",
+          "search": "Optional SideNavSearch node rendered after heading and before navigation content.",
+          "SideNavContent": "Scrollable or flexible body region for repeated SideNavSection groups.",
+          "SideNavSearch": "Package-owned search field for filtering navigation lists without local input styling.",
+          "SideNavNestedGroup": "Groups a parent SideNavItem and its nested child collection.",
+          "SideNavNestedItems": "Indented child item collection using logical inline-start spacing and border.",
+          "PanelIcon": "Direction-neutral icon exported for SideNavCollapseButton examples. Prefer it over directional arrows unless the directional icon has an RTL mirror rule."
+        },
+        "arabicFriendly": "Use logical start/end spacing in nested items and let document direction control order. Closed disclosure indicators rotate toward the inline start in LTR and RTL. Preserve scroll position when the side nav collapses and expands, and do not use left/right naming in generated side navigation layouts."
+      }
+    },
+    {
+      "name": "Side Nav Collapse Button",
+      "category": "Navigation",
+      "status": "available",
+      "packageImport": "import { PanelIcon, SideNavCollapseButton } from '@utopia-studio-design/design-system/Navigation';",
+      "sourcePath": "packages/design-system/src/components/Navigation.tsx",
+      "shadcnFoundation": [
+        "button",
+        "Button variant=ghost",
+        "icon-only control",
+        "sidebar collapse control",
+        "semantic Utopia wrapper"
+      ],
+      "fallbackToShadcn": "button",
+      "requiredTokens": [
+        "--foreground",
+        "--muted-foreground",
+        "--radius-control",
+        "--focus-ring-width",
+        "--ghost-hover",
+        "--ghost-active"
+      ],
+      "useWhen": [
+        "A persistent side navigation can collapse or expand",
+        "The control is composed as SideNavHeading endContent",
+        "The button uses the design-system Button primitive with variant=ghost and isIconOnly",
+        "The button is icon-only with hover/focus background and an accessible label; add Tooltip when visual context is not enough",
+        "The button has aria-expanded and an accessible label",
+        "AI-generated app shells expose side nav state without inventing local controls"
+      ],
+      "avoidWhen": [
+        "The side navigation has no collapsed state",
+        "A text button is required",
+        "A temporary panel close action that should use SheetClose",
+        "Icon-only controls without accessible labels; add visible or tooltip help when context is ambiguous"
+      ],
+      "neverInvent": [
+        "Visible Collapse text inside the control",
+        "Custom button styling instead of Button variant=ghost isIconOnly",
+        "Hardcoded app icons",
+        "Raw shadcn theme colors",
+        "Left/right-only layout rules",
+        "Utopia brand primitives inside reusable component logic"
+      ],
+      "ai": {
+        "props": {
+          "aria-label": "Required accessible label, such as Close sidebar or Open sidebar.",
+          "aria-expanded": "Reflects the controlled side navigation state.",
+          "children": "Icon-only visual content. SideNavCollapseButton wraps Button with variant=ghost and isIconOnly; compose inside SideNavHeading endContent. Add Tooltip when the surrounding UI does not already make the action clear."
+        },
+        "usage": "Place SideNavCollapseButton in SideNavHeading endContent. Always provide aria-label and aria-expanded. When a tooltip is needed, wrap with Tooltip/TooltipTrigger asChild and keep visible helper text in TooltipContent rather than inside the button.",
+        "arabicFriendly": "PanelIcon is direction-neutral. If a product supplies a directional collapse icon, it must mirror in dir=\"rtl\" or be replaced with a neutral panel icon. Prefer direction-neutral tooltip placement, or use logical placement/RTL branching where the host app supports it."
+      }
+    },
+    {
+      "name": "Side Nav Heading",
+      "category": "Navigation",
+      "status": "available",
+      "packageImport": "import { SideNavHeading } from '@utopia-studio-design/design-system/Navigation';",
+      "sourcePath": "packages/design-system/src/components/Navigation.tsx",
+      "shadcnFoundation": [
+        "sidebar group label",
+        "semantic heading",
+        "semantic Utopia wrapper"
+      ],
+      "fallbackToShadcn": "sidebar",
+      "requiredTokens": [
+        "--foreground",
+        "--muted-foreground",
+        "--radius-control",
+        "--radius-surface",
+        "--space-1",
+        "--space-3",
+        "--font-size-supporting",
+        "--line-height-supporting"
+      ],
+      "useWhen": [
+        "Grouping related side navigation items with variant=section",
+        "A side navigation surface needs a brand, workspace, product, or documentation heading with variant=brand",
+        "A heading needs optional icon, meta, subtitle/version, or endContent slots without hardcoding icon assets",
+        "AI-generated navigation needs stable section labels from manifest data"
+      ],
+      "avoidWhen": [
+        "A clickable navigation item is required",
+        "A dropdown menu body is required; compose SideNavHeading with a menu primitive instead",
+        "Decorative labels with no section relationship"
+      ],
+      "neverInvent": [
+        "Raw brand colors inside the component",
+        "Hardcoded app icons",
+        "Left/right-only layout rules",
+        "Arabic copy invented by the component",
+        "Utopia brand primitives inside reusable component logic"
+      ],
+      "ai": {
+        "props": {
+          "variant": "section keeps compact group-label styling; brand renders a larger app/workspace header.",
+          "icon": "Optional leading visual slot. Omit for text-only headings; artwork is app or theme owned. Large logos and wordmarks are constrained by the component.",
+          "mediaSize": "Use mark for compact square icons, wordmark for wide logos, or auto when the consumer controls sizing.",
+          "meta": "Optional line above the label, such as organization or workspace.",
+          "subtitle": "Optional line below the label.",
+          "version": "Alias for subtitle for versioned docs/product surfaces.",
+          "endContent": "Optional trailing slot for chevrons, status, or menu affordance."
+        },
+        "arabicFriendly": "Use logical layout and start/end slots. Do not bake English-only ordering into icon, label, meta, or endContent."
+      }
+    },
+    {
+      "name": "Side Nav Item",
+      "category": "Navigation",
+      "status": "available",
+      "packageImport": "import { SideNavItem } from '@utopia-studio-design/design-system/Navigation';",
+      "sourcePath": "packages/design-system/src/components/Navigation.tsx",
+      "shadcnFoundation": [
+        "sidebar menu item",
+        "link",
+        "semantic Utopia wrapper"
+      ],
+      "fallbackToShadcn": "sidebar",
+      "requiredTokens": [
+        "--secondary",
+        "--secondary-foreground",
+        "--muted-foreground",
+        "--foreground-subtle",
+        "--radius-control",
+        "--focus-ring-width",
+        "--space-2",
+        "--space-3",
+        "--space-4",
+        "--space-6",
+        "--space-8"
+      ],
+      "useWhen": [
+        "A side navigation row links to a route or section",
+        "The current page can be marked with isCurrent or aria-current",
+        "The row needs optional icon/startContent, badge, or endContent slots while keeping spacing owned by the component.",
+        "The row is nested inside a side nav hierarchy and needs depth-based indentation",
+        "A navigation option needs disabled status without becoming a button"
+      ],
+      "avoidWhen": [
+        "Submitting actions that should use Button",
+        "Nested disclosure controls that should use a future collapsible nav primitive",
+        "Hardcoded icons or counts inside local navigation markup"
+      ],
+      "neverInvent": [
+        "Raw shadcn theme colors",
+        "Left/right-only layout rules",
+        "Utopia brand primitives inside reusable component logic",
+        "Local CSS-only side nav item layouts when SideNavItem slots are available"
+      ],
+      "ai": {
+        "props": {
+          "icon": "Optional leading visual slot. Omit for text-only rows; do not add placeholder marks.",
+          "depth": "Use 0 for root rows, 1 for items inside a top-level section, 2 for nested section children, and 3 only for rare deep navigation.",
+          "badge": "Optional trailing count or status pill aligned to the inline end.",
+          "endContent": "Optional trailing action/content slot after the badge."
+        },
+        "arabicFriendly": "Use icon/startContent for inline-start content and badge/endContent for inline-end content. In dir=\"rtl\", spacing and indentation must follow inline start/end, mixed Arabic/English labels must truncate without overlapping badges, and disabled/current states must remain keyboard and screen-reader equivalent."
+      }
+    },
+    {
+      "name": "Side Nav Section",
+      "category": "Navigation",
+      "status": "available",
+      "packageImport": "import { SideNavSection } from '@utopia-studio-design/design-system/Navigation';",
+      "sourcePath": "packages/design-system/src/components/Navigation.tsx",
+      "shadcnFoundation": [
+        "sidebar group",
+        "semantic section wrapper",
+        "semantic Utopia wrapper"
+      ],
+      "fallbackToShadcn": "sidebar",
+      "requiredTokens": [
+        "--space-1",
+        "--space-3",
+        "--space-4",
+        "--border",
+        "--muted-foreground",
+        "--duration-fast",
+        "--duration-medium",
+        "--ease-standard"
+      ],
+      "useWhen": [
+        "Grouping a section label and related Side Nav Item rows",
+        "A side nav needs repeated IA groups from a manifest",
+        "A long side nav section should optionally collapse without inventing local disclosure controls",
+        "Nested component families that need a parent row with collapsible children should use variant=nested",
+        "AI-generated shells should map Docs, Account, Project, or Settings groups into sections"
+      ],
+      "avoidWhen": [
+        "A single clickable navigation row is required; use SideNavItem",
+        "A brand/workspace header is required; use SideNavHeading variant=brand",
+        "Content regions that should use Layout or Section"
+      ],
+      "neverInvent": [
+        "Raw shadcn theme colors",
+        "Left/right-only layout rules",
+        "Utopia brand primitives inside reusable component logic"
+      ],
+      "ai": {
+        "props": {
+          "label": "Optional section label rendered before children with SideNavHeading variant=section or a row-style nested trigger when variant=nested.",
+          "children": "SideNavItem rows or related navigation content owned by this section.",
+          "collapsible": "When true, the full section heading or nested trigger toggles the section; the chevron is a visual end indicator, not the only hit target.",
+          "variant": "Use section for top-level IA groups. Use nested for a row-style parent with indented collapsible children, such as component families.",
+          "defaultExpanded": "Initial uncontrolled expanded state for collapsible sections.",
+          "expanded": "Controlled expanded state for collapsible sections.",
+          "onExpandedChange": "Called when a collapsible section toggles."
+        },
+        "arabicFriendly": "Group order follows document direction. Use logical spacing and avoid left/right labels in generated section layouts."
+      }
+    },
+    {
+      "name": "Skeleton",
+      "category": "Data Display",
+      "status": "available",
+      "packageImport": "import { Skeleton } from '@utopia-studio-design/design-system/DataDisplay';",
+      "sourcePath": "packages/design-system/src/components/DataDisplay.tsx",
+      "shadcnFoundation": [
+        "skeleton"
+      ],
+      "fallbackToShadcn": "skeleton",
+      "requiredTokens": [
+        "--muted",
+        "--radius-surface",
+        "--duration-fast"
+      ],
+      "useWhen": [
+        "Loading placeholders",
+        "Layout-preserving content previews",
+        "Avoiding layout shift while data loads"
+      ],
+      "avoidWhen": [
+        "Finished empty states",
+        "Unknown long-running progress where Spinner or Progress is clearer"
+      ],
+      "neverInvent": [
+        "Spinner-only page skeletons",
+        "Left/right-only layout rules",
+        "Utopia brand primitives inside reusable component logic"
+      ]
+    },
+    {
+      "name": "Sidebar",
+      "category": "Navigation",
+      "status": "available",
+      "packageImport": "import { Sidebar, SidebarContent, SidebarFooter, SidebarGroup, SidebarGroupAction, SidebarGroupLabel, SidebarHeader, SidebarInset, SidebarMenu, SidebarMenuAction, SidebarMenuBadge, SidebarMenuButton, SidebarMenuItem, SidebarMenuSub, SidebarMenuSubButton, SidebarMenuSubItem, SidebarOverlay, SidebarProvider, SidebarRail, SidebarTrigger, useSidebar } from '@utopia-studio-design/design-system/Sidebar';",
+      "sourcePath": "packages/design-system/src/components/Sidebar.tsx",
+      "shadcnFoundation": [
+        "sidebar",
+        "composable app shell",
+        "semantic Utopia wrapper"
+      ],
+      "fallbackToShadcn": "sidebar",
+      "requiredTokens": [
+        "--background",
+        "--foreground",
+        "--border",
+        "--surface-hover",
+        "--popover-surface",
+        "--radius-control",
+        "--radius-surface",
+        "--sidebar-width",
+        "--sidebar-width-collapsed",
+        "--sidebar-min-block-size",
+        "--sidebar-rail-size",
+        "--duration-medium",
+        "--ease-standard"
+      ],
+      "useWhen": [
+        "Building a controlled or uncontrolled application shell with collapsible navigation",
+        "Composing header, content, footer, groups, menu items, actions, badges, submenus, rail, and inset content",
+        "A responsive off-canvas or icon-collapse application sidebar is required independently from documentation Side Nav"
+      ],
+      "avoidWhen": [
+        "Rendering the design-system documentation tree; use Side Nav",
+        "A temporary overlay should use Sheet",
+        "Hardcoding product destinations inside the reusable primitive"
+      ],
+      "neverInvent": [
+        "Left/right-only collapse rules",
+        "Product-specific menu data",
+        "Utopia brand primitives inside reusable component logic"
+      ],
+      "ai": {
+        "parts": [
+          "SidebarProvider",
+          "Sidebar",
+          "SidebarHeader",
+          "SidebarContent",
+          "SidebarFooter",
+          "SidebarGroup",
+          "SidebarGroupAction",
+          "SidebarGroupLabel",
+          "SidebarInset",
+          "SidebarMenu",
+          "SidebarMenuItem",
+          "SidebarMenuButton",
+          "SidebarMenuAction",
+          "SidebarMenuBadge",
+          "SidebarMenuSub",
+          "SidebarMenuSubItem",
+          "SidebarMenuSubButton",
+          "SidebarOverlay",
+          "SidebarRail",
+          "SidebarTrigger",
+          "useSidebar"
+        ],
+        "arabicFriendly": "Use dir=rtl at the shell boundary and provide localized collapseLabel, expandLabel, overlay labels, rail labels, and tooltip strings. Logical borders, alignment, off-canvas motion, submenus, and badges mirror without changing the component API."
+      }
+    },
+    {
+      "name": "Slider",
+      "category": "Forms",
+      "status": "available",
+      "packageImport": "import { Slider } from '@utopia-studio-design/design-system/Forms';",
+      "sourcePath": "packages/design-system/src/components/Forms.tsx",
+      "shadcnFoundation": [
+        "slider",
+        "Radix Slider"
+      ],
+      "fallbackToShadcn": "slider",
+      "requiredTokens": [
+        "--primary",
+        "--secondary",
+        "--background",
+        "--shadow-control",
+        "--focus-ring-width"
+      ],
+      "useWhen": [
+        "Continuous numeric adjustment",
+        "Approximate values where dragging is useful",
+        "Arabic-friendly numeric controls that must mirror direction with RTL"
+      ],
+      "avoidWhen": [
+        "Exact numeric entry only",
+        "Unlabeled ranges",
+        "Business validation inside reusable component logic"
+      ],
+      "neverInvent": [
+        "Unlabeled ranges",
+        "Left/right-only layout rules",
+        "Utopia brand primitives inside reusable component logic"
+      ]
+    },
+    {
+      "name": "Sonner",
+      "category": "Feedback",
+      "status": "available",
+      "packageImport": "import { Toaster, toast } from '@utopia-studio-design/design-system/ShadcnPrimitives';",
+      "sourcePath": "packages/design-system/src/components/ShadcnPrimitives.tsx",
+      "shadcnFoundation": [
+        "sonner",
+        "shadcn/ui registry",
+        "semantic Utopia wrapper"
+      ],
+      "fallbackToShadcn": "toast",
+      "requiredTokens": [
+        "--background",
+        "--foreground",
+        "--surface",
+        "--border",
+        "--radius-surface",
+        "--shadow-popover",
+        "--muted-foreground",
+        "--focus-ring-width"
+      ],
+      "useWhen": [
+        "Nonblocking toast feedback",
+        "Status messages that should be announced politely",
+        "AI-generated examples that need success, error, promise, description, and position behavior"
+      ],
+      "avoidWhen": [
+        "Blocking errors",
+        "Long-form content",
+        "Product notification scheduling inside reusable component logic"
+      ],
+      "neverInvent": [
+        "Raw shadcn theme colors",
+        "Left/right-only layout rules",
+        "Utopia brand primitives inside reusable component logic"
+      ]
+    },
+    {
+      "name": "Spinner",
+      "category": "Data Display",
+      "status": "available",
+      "packageImport": "import { Spinner } from '@utopia-studio-design/design-system/DataDisplay';",
+      "sourcePath": "packages/design-system/src/components/DataDisplay.tsx",
+      "shadcnFoundation": [
+        "spinner"
+      ],
+      "fallbackToShadcn": "spinner",
+      "requiredTokens": [
+        "--foreground",
+        "--duration-fast"
+      ],
+      "useWhen": [
+        "Short inline loading",
+        "Small pending states next to text or controls"
+      ],
+      "avoidWhen": [
+        "Large page loading",
+        "Known progress values where Progress is clearer"
+      ],
+      "neverInvent": [
+        "Unannounced loading state",
+        "Left/right-only layout rules",
+        "Utopia brand primitives inside reusable component logic"
+      ],
+      "ai": {
+        "props": {
+          "label": "Localized loading text. Supplying it exposes role=status and a live region.",
+          "aria-label": "Localized accessible name when no visible label is rendered. Without either label, Spinner is decorative and aria-hidden."
+        },
+        "arabicFriendly": "Loading labels come from product localization. The spinner is direction-neutral and must not be mirrored."
+      }
+    },
+    {
+      "name": "Switch",
+      "category": "Forms",
+      "status": "available",
+      "packageImport": "import { Switch } from '@utopia-studio-design/design-system/Forms';",
+      "sourcePath": "packages/design-system/src/components/Forms.tsx",
+      "shadcnFoundation": [
+        "switch",
+        "Radix Switch"
+      ],
+      "fallbackToShadcn": "switch",
+      "requiredTokens": [
+        "--primary",
+        "--secondary",
+        "--background",
+        "--border",
+        "--shadow-control",
+        "--focus-ring-width"
+      ],
+      "useWhen": [
+        "Persistent binary settings",
+        "Preferences that save immediately",
+        "Arabic-friendly forms where switch thumb movement must mirror in RTL"
+      ],
+      "avoidWhen": [
+        "Submit actions",
+        "Temporary pressed states that should be Toggle",
+        "Mutually exclusive options that should be Radio Group"
+      ],
+      "neverInvent": [
+        "Toggle button behavior",
+        "Left/right-only layout rules",
+        "Utopia brand primitives inside reusable component logic"
+      ]
+    },
+    {
+      "name": "Table",
+      "category": "Data Display",
+      "status": "available",
+      "packageImport": "import { Table, TableBody, TableCaption, TableCell, TableContainer, TableFooter, TableHead, TableHeader, TableRow } from '@utopia-studio-design/design-system/DataDisplay';",
+      "sourcePath": "packages/design-system/src/components/DataDisplay.tsx",
+      "shadcnFoundation": [
+        "table"
+      ],
+      "fallbackToShadcn": "table",
+      "requiredTokens": [
+        "--border",
+        "--space-2",
+        "--space-3",
+        "--muted-foreground"
+      ],
+      "useWhen": [
+        "Structured rows and columns",
+        "Small semantic tables that do not need sorting/filtering",
+        "AI-generated static table examples with explicit header, body, row, head, and cell parts"
+      ],
+      "avoidWhen": [
+        "Simple metadata",
+        "Interactive data grids that should use Data Table",
+        "Div-based tables"
+      ],
+      "neverInvent": [
+        "Div-based tables",
+        "Left/right-only layout rules",
+        "Utopia brand primitives inside reusable component logic"
+      ]
+    },
+    {
+      "name": "Tabs",
+      "category": "Navigation",
+      "status": "available",
+      "packageImport": "import { Tabs, TabList, Tab, TabPanel } from '@utopia-studio-design/design-system/Navigation';",
+      "sourcePath": "packages/design-system/src/components/Navigation.tsx",
+      "shadcnFoundation": [
+        "tabs",
+        "Radix Tabs"
+      ],
+      "fallbackToShadcn": "tabs",
+      "requiredTokens": [
+        "--border",
+        "--secondary",
+        "--radius-control",
+        "--focus-ring-width",
+        "--motion-duration-page",
+        "--motion-ease-standard"
+      ],
+      "useWhen": [
+        "Peer views",
+        "Same-context panels",
+        "Keyboard-switchable content sections"
+      ],
+      "avoidWhen": [
+        "Page navigation",
+        "Unrelated destinations"
+      ],
+      "neverInvent": [
+        "Tabs as unrelated links",
+        "Left/right-only layout rules",
+        "Utopia brand primitives inside reusable component logic",
+        "Motion that bypasses MotionProvider or prefers-reduced-motion"
+      ],
+      "ai": {
+        "props": {
+          "motion": "Optional boolean. Defaults to the MotionProvider policy and disables this component pattern when false."
+        }
+      }
+    },
+    {
+      "name": "Textarea",
+      "category": "Forms",
+      "status": "available",
+      "packageImport": "import { Textarea } from '@utopia-studio-design/design-system/Forms';",
+      "sourcePath": "packages/design-system/src/components/Forms.tsx",
+      "shadcnFoundation": [
+        "textarea",
+        "semantic multiline input"
+      ],
+      "fallbackToShadcn": "textarea",
+      "requiredTokens": [
+        "--input",
+        "--radius-control",
+        "--focus-ring-width"
+      ],
+      "useWhen": [
+        "Multi-line text entry",
+        "Notes, comments, and longer form content"
+      ],
+      "avoidWhen": [
+        "Single-line labels",
+        "Rich text editing"
+      ],
+      "neverInvent": [
+        "Fixed tiny text areas",
+        "Left/right-only layout rules",
+        "Utopia brand primitives inside reusable component logic"
+      ]
+    },
+    {
+      "name": "Toast",
+      "category": "Data Display",
+      "status": "legacy",
+      "packageImport": "import { Toast, ToastDescription, ToastTitle } from '@utopia-studio-design/design-system/DataDisplay';",
+      "sourcePath": "packages/design-system/src/components/DataDisplay.tsx",
+      "shadcnFoundation": [
+        "sonner",
+        "toast"
+      ],
+      "fallbackToShadcn": "sonner",
+      "requiredTokens": [
+        "--surface",
+        "--border",
+        "--radius-surface",
+        "--muted-foreground"
+      ],
+      "useWhen": [
+        "Short nonblocking feedback",
+        "Small status messages rendered inline or by a toast system",
+        "AI-generated examples that need title and description structure"
+      ],
+      "avoidWhen": [
+        "Critical blocking errors",
+        "Long messages or workflows",
+        "Any new implementation; import Toaster and toast from the Sonner contract instead"
+      ],
+      "replacement": "Sonner",
+      "neverInvent": [
+        "Toast-only error handling",
+        "Left/right-only layout rules",
+        "Utopia brand primitives inside reusable component logic"
+      ]
+    },
+    {
+      "name": "Toggle Button",
+      "category": "Action",
+      "status": "available",
+      "packageImport": "import { ToggleButton } from '@utopia-studio-design/design-system/ToggleButton';",
+      "sourcePath": "packages/design-system/src/components/ToggleButton.tsx",
+      "shadcnFoundation": [
+        "toggle",
+        "Radix Toggle",
+        "cva"
+      ],
+      "fallbackToShadcn": "shadcn/ui toggle",
+      "requiredTokens": [
+        "--secondary",
+        "--secondary-hover",
+        "--secondary-active",
+        "--ghost-hover",
+        "--ghost-active",
+        "--radius-control",
+        "--button-height",
+        "--focus-ring-width"
+      ],
+      "useWhen": [
+        "Persistent selected/unselected states",
+        "Formatting controls",
+        "Favorite or mute actions"
+      ],
+      "avoidWhen": [
+        "Form submission",
+        "Navigation",
+        "Mutually exclusive sets"
+      ],
+      "neverInvent": [
+        "New pressed colors",
+        "Checkbox behavior",
+        "Left/right-only state names",
+        "Utopia brand primitives inside reusable component logic"
+      ],
+      "ai": {
+        "props": [
+          "label",
+          "isPressed",
+          "defaultPressed",
+          "onPressedChange",
+          "icon",
+          "pressedIcon",
+          "isIconOnly",
+          "isDisabled",
+          "isLoading",
+          "variant",
+          "size"
+        ],
+        "arabicFriendly": [
+          "Use logical start/end language for labels and adjacent content.",
+          "In RTL, keep persistent pressed state behavior identical; only directional layout and directional icons may mirror.",
+          "Do not invent Arabic copy; use provided localized strings or neutral test copy."
+        ]
+      }
+    },
+    {
+      "name": "Toggle Button Group",
+      "category": "Action",
+      "status": "available",
+      "packageImport": "import { ToggleButtonGroup, ToggleButtonGroupItem } from '@utopia-studio-design/design-system/ToggleButtonGroup';",
+      "sourcePath": "packages/design-system/src/components/ToggleButtonGroup.tsx",
+      "shadcnFoundation": [
+        "toggle-group",
+        "Radix Toggle Group",
+        "cva"
+      ],
+      "fallbackToShadcn": "shadcn/ui toggle-group",
+      "requiredTokens": [
+        "--button-group-gap",
+        "--button-group-gap-compact",
+        "--secondary",
+        "--secondary-hover",
+        "--secondary-active",
+        "--radius-control",
+        "--button-height",
+        "--focus-ring-width"
+      ],
+      "useWhen": [
+        "Mutually exclusive toggle sets",
+        "Multi-select formatting controls",
+        "Segmented tool options"
+      ],
+      "avoidWhen": [
+        "Unrelated actions",
+        "Navigation tabs",
+        "One-off binary choices"
+      ],
+      "neverInvent": [
+        "Serialized React children arrays",
+        "Button group colors",
+        "Left/right-only orientation logic",
+        "Utopia brand primitives inside reusable component logic"
+      ],
+      "ai": {
+        "props": [
+          "label",
+          "type",
+          "value",
+          "defaultValue",
+          "onValueChange",
+          "onChange",
+          "orientation",
+          "isDisabled",
+          "density",
+          "ToggleButtonGroupItem.label",
+          "ToggleButtonGroupItem.value",
+          "ToggleButtonGroupItem.icon",
+          "ToggleButtonGroupItem.pressedIcon",
+          "ToggleButtonGroupItem.isIconOnly"
+        ],
+        "arabicFriendly": [
+          "Use start/end labels instead of left/right labels for alignment controls.",
+          "Preserve item order according to product meaning; rely on dir='rtl' and logical CSS for inline flow.",
+          "Icon-only items require aria-label in the localized language."
+        ]
+      }
+    },
+    {
+      "name": "Tooltip",
+      "category": "Surface",
+      "status": "available",
+      "packageImport": "import { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger } from '@utopia-studio-design/design-system/Surface';",
+      "sourcePath": "packages/design-system/src/components/Surface.tsx",
+      "shadcnFoundation": [
+        "tooltip",
+        "Radix Tooltip"
+      ],
+      "fallbackToShadcn": "tooltip",
+      "requiredTokens": [
+        "--surface",
+        "--border",
+        "--radius-surface",
+        "--popover-surface",
+        "--motion-duration-reveal",
+        "--motion-ease-emphasized"
+      ],
+      "useWhen": [
+        "Short helper text",
+        "Icon-only action explanation"
+      ],
+      "avoidWhen": [
+        "Required information",
+        "Long content"
+      ],
+      "neverInvent": [
+        "Interactive tooltip content",
+        "Untranslated production Arabic copy",
+        "Left/right-only layout rules",
+        "Utopia brand primitives inside reusable component logic",
+        "Motion that bypasses MotionProvider or prefers-reduced-motion"
+      ],
+      "ai": {
+        "props": {
+          "motion": "Optional boolean. Defaults to the MotionProvider policy and disables this component pattern when false."
+        }
+      }
+    },
+    {
+      "category": "Navigation",
+      "status": "available",
+      "sourcePath": "packages/design-system/src/components/Navigation.tsx",
+      "neverInvent": [
+        "Raw shadcn theme colors",
+        "Left/right-only layout rules",
+        "Utopia brand primitives inside reusable component logic",
+        "Invented Arabic production copy"
+      ],
+      "name": "Top Nav",
+      "packageImport": "import { TopNav, TopNavHeading, TopNavItem, TopNavMenu, TopNavMegaMenu, NavIcon } from '@utopia-studio-design/design-system/Navigation';",
+      "shadcnFoundation": [
+        "navigation-menu",
+        "Radix NavigationMenu",
+        "shadcn/ui navigation-menu composition",
+        "semantic Utopia wrapper"
+      ],
+      "fallbackToShadcn": "navigation-menu",
+      "requiredTokens": [
+        "--foreground",
+        "--muted-foreground",
+        "--secondary",
+        "--secondary-foreground",
+        "--border",
+        "--radius-control",
+        "--radius-surface",
+        "--popover-surface",
+        "--focus-ring-width"
+      ],
+      "useWhen": [
+        "Desktop horizontal app or docs navigation",
+        "Navigation needs brand heading, current item state, menu triggers, mega menu content, and end icon actions",
+        "AI-generated app shells need explicit top navigation parts instead of ad hoc flex rows"
+      ],
+      "avoidWhen": [
+        "Mobile-only navigation; use Mobile Nav",
+        "Persistent vertical navigation; use Side Nav",
+        "Submitting actions that should use Button"
+      ],
+      "ai": {
+        "props": {
+          "children": "Use TopNavItem, TopNavMenu, or TopNavMegaMenu children. Pair with TopNavHeading and NavIcon outside or near the root as needed."
+        },
+        "arabicFriendly": "Use document direction for order. Keep item labels as localized product content and use logical alignment for menu content."
+      }
+    },
+    {
+      "category": "Navigation",
+      "status": "available",
+      "sourcePath": "packages/design-system/src/components/Navigation.tsx",
+      "neverInvent": [
+        "Raw shadcn theme colors",
+        "Left/right-only layout rules",
+        "Utopia brand primitives inside reusable component logic",
+        "Invented Arabic production copy"
+      ],
+      "name": "Top Nav Heading",
+      "packageImport": "import { TopNavHeading } from '@utopia-studio-design/design-system/Navigation';",
+      "shadcnFoundation": [
+        "navigation brand slot",
+        "semantic Utopia wrapper"
+      ],
+      "fallbackToShadcn": "navigation-menu composition",
+      "requiredTokens": [
+        "--foreground",
+        "--muted-foreground",
+        "--secondary",
+        "--secondary-foreground",
+        "--border",
+        "--radius-control",
+        "--radius-surface",
+        "--popover-surface",
+        "--focus-ring-width"
+      ],
+      "useWhen": [
+        "Top navigation needs product, workspace, or app identity",
+        "A brand mark and label should stay aligned in a horizontal navigation bar"
+      ],
+      "avoidWhen": [
+        "Side navigation headers; use SideNavHeading",
+        "Decorative logos without accessible text"
+      ],
+      "ai": {
+        "props": {
+          "label": "Primary app/product name.",
+          "icon": "Optional leading mark slot owned by app/theme.",
+          "meta": "Optional line above label.",
+          "subtitle": "Optional line below label."
+        },
+        "arabicFriendly": "Do not assume English label order. Slot order follows inline start/end."
+      }
+    },
+    {
+      "category": "Navigation",
+      "status": "available",
+      "sourcePath": "packages/design-system/src/components/Navigation.tsx",
+      "neverInvent": [
+        "Raw shadcn theme colors",
+        "Left/right-only layout rules",
+        "Utopia brand primitives inside reusable component logic",
+        "Invented Arabic production copy"
+      ],
+      "name": "Top Nav Item",
+      "packageImport": "import { TopNavItem } from '@utopia-studio-design/design-system/Navigation';",
+      "shadcnFoundation": [
+        "navigation-menu link",
+        "Radix NavigationMenu.Link"
+      ],
+      "fallbackToShadcn": "navigation-menu link",
+      "requiredTokens": [
+        "--foreground",
+        "--muted-foreground",
+        "--secondary",
+        "--secondary-foreground",
+        "--border",
+        "--radius-control",
+        "--radius-surface",
+        "--popover-surface",
+        "--focus-ring-width"
+      ],
+      "useWhen": [
+        "A top navigation row links to a route or section",
+        "The current route needs isCurrent or aria-current"
+      ],
+      "avoidWhen": [
+        "Opening nested content; use TopNavMenu or TopNavMegaMenu",
+        "Actions that should use Button"
+      ],
+      "ai": {
+        "props": {
+          "href": "Navigation target.",
+          "isCurrent": "Sets aria-current page and selected visual state.",
+          "children": "Visible label."
+        },
+        "arabicFriendly": "Mixed Arabic/English labels must not affect hit target or alignment."
+      }
+    },
+    {
+      "category": "Navigation",
+      "status": "available",
+      "sourcePath": "packages/design-system/src/components/Navigation.tsx",
+      "neverInvent": [
+        "Raw shadcn theme colors",
+        "Left/right-only layout rules",
+        "Utopia brand primitives inside reusable component logic",
+        "Invented Arabic production copy"
+      ],
+      "name": "Top Nav Mega Menu",
+      "packageImport": "import { TopNavMegaMenu, TopNavMegaMenuFeaturedCard, TopNavMegaMenuItem } from '@utopia-studio-design/design-system/Navigation';",
+      "shadcnFoundation": [
+        "navigation-menu mega menu pattern",
+        "Radix NavigationMenu.Content"
+      ],
+      "fallbackToShadcn": "navigation-menu",
+      "requiredTokens": [
+        "--foreground",
+        "--muted-foreground",
+        "--secondary",
+        "--secondary-foreground",
+        "--border",
+        "--radius-control",
+        "--radius-surface",
+        "--popover-surface",
+        "--focus-ring-width",
+        "--surface-hover"
+      ],
+      "useWhen": [
+        "A top navigation trigger opens grouped destinations, a featured card, or multi-column navigation content",
+        "Desktop IA needs richer scanable navigation without leaving the page"
+      ],
+      "avoidWhen": [
+        "Small lists that should use TopNavMenu",
+        "Mobile panels that should use Mobile Nav"
+      ],
+      "ai": {
+        "props": {
+          "label": "Visible trigger label.",
+          "align": "Logical start/end alignment for the menu surface.",
+          "children": "Featured card and item children."
+        },
+        "arabicFriendly": "Use logical alignment and mirror only directional icons supplied by product code."
+      }
+    },
+    {
+      "category": "Navigation",
+      "status": "available",
+      "sourcePath": "packages/design-system/src/components/Navigation.tsx",
+      "neverInvent": [
+        "Raw shadcn theme colors",
+        "Left/right-only layout rules",
+        "Utopia brand primitives inside reusable component logic",
+        "Invented Arabic production copy"
+      ],
+      "name": "Top Nav Mega Menu Featured Card",
+      "packageImport": "import { TopNavMegaMenuFeaturedCard } from '@utopia-studio-design/design-system/Navigation';",
+      "shadcnFoundation": [
+        "navigation-menu link",
+        "featured destination card"
+      ],
+      "fallbackToShadcn": "navigation-menu link",
+      "requiredTokens": [
+        "--foreground",
+        "--muted-foreground",
+        "--secondary",
+        "--secondary-foreground",
+        "--border",
+        "--radius-control",
+        "--radius-surface",
+        "--popover-surface",
+        "--focus-ring-width"
+      ],
+      "useWhen": [
+        "Mega menu needs one prominent destination or product area"
+      ],
+      "avoidWhen": [
+        "Repeated simple rows; use TopNavMegaMenuItem"
+      ],
+      "ai": {
+        "props": {
+          "href": "Navigation target.",
+          "title": "Primary destination title.",
+          "description": "Supporting destination copy.",
+          "icon": "Optional start icon slot."
+        },
+        "arabicFriendly": "Keep title/description localized; do not invent Arabic copy."
+      }
+    },
+    {
+      "category": "Navigation",
+      "status": "available",
+      "sourcePath": "packages/design-system/src/components/Navigation.tsx",
+      "neverInvent": [
+        "Raw shadcn theme colors",
+        "Left/right-only layout rules",
+        "Utopia brand primitives inside reusable component logic",
+        "Invented Arabic production copy"
+      ],
+      "name": "Top Nav Mega Menu Item",
+      "packageImport": "import { TopNavMegaMenuItem } from '@utopia-studio-design/design-system/Navigation';",
+      "shadcnFoundation": [
+        "navigation-menu link",
+        "mega menu list item"
+      ],
+      "fallbackToShadcn": "navigation-menu link",
+      "requiredTokens": [
+        "--foreground",
+        "--muted-foreground",
+        "--secondary",
+        "--secondary-foreground",
+        "--border",
+        "--radius-control",
+        "--radius-surface",
+        "--popover-surface",
+        "--focus-ring-width"
+      ],
+      "useWhen": [
+        "Mega menu needs repeated destination rows with title and description"
+      ],
+      "avoidWhen": [
+        "The destination should be visually featured; use TopNavMegaMenuFeaturedCard"
+      ],
+      "ai": {
+        "props": {
+          "href": "Navigation target.",
+          "title": "Primary destination title.",
+          "description": "Supporting destination copy.",
+          "icon": "Optional start icon slot."
+        },
+        "arabicFriendly": "Logical grid columns must keep icon/title/description readable in RTL."
+      }
+    },
+    {
+      "category": "Navigation",
+      "status": "available",
+      "sourcePath": "packages/design-system/src/components/Navigation.tsx",
+      "neverInvent": [
+        "Raw shadcn theme colors",
+        "Left/right-only layout rules",
+        "Utopia brand primitives inside reusable component logic",
+        "Invented Arabic production copy"
+      ],
+      "name": "Top Nav Menu",
+      "packageImport": "import { TopNavMenu, TopNavMenuItem } from '@utopia-studio-design/design-system/Navigation';",
+      "shadcnFoundation": [
+        "navigation-menu trigger/content",
+        "Radix NavigationMenu.Item",
+        "Radix NavigationMenu.Content"
+      ],
+      "fallbackToShadcn": "navigation-menu",
+      "requiredTokens": [
+        "--foreground",
+        "--muted-foreground",
+        "--secondary",
+        "--secondary-foreground",
+        "--border",
+        "--radius-control",
+        "--radius-surface",
+        "--popover-surface",
+        "--focus-ring-width"
+      ],
+      "useWhen": [
+        "A top navigation trigger opens a compact list of links",
+        "Navigation content is too small for a mega menu"
+      ],
+      "avoidWhen": [
+        "Large grouped destination panels; use TopNavMegaMenu"
+      ],
+      "ai": {
+        "props": {
+          "label": "Visible trigger label.",
+          "children": "TopNavMenuItem children."
+        },
+        "arabicFriendly": "Trigger and content align with logical inline start/end."
+      }
+    },
+    {
+      "name": "Typography",
+      "category": "Data Display",
+      "status": "available",
+      "packageImport": "import { ArabicText, Heading, Prose, Text, Typography } from '@utopia-studio-design/design-system/Typography';",
+      "sourcePath": "packages/design-system/src/components/Typography.tsx",
+      "shadcnFoundation": [
+        "typography",
+        "semantic text primitives",
+        "Arabic-friendly type contract"
+      ],
+      "fallbackToShadcn": "typography",
+      "requiredTokens": [
+        "--font-sans",
+        "--font-arabic",
+        "--foreground",
+        "--foreground-muted",
+        "--foreground-subtle",
+        "--line-height-body",
+        "--line-height-arabic",
+        "--tracking-heading"
+      ],
+      "useWhen": [
+        "Headings and body copy need semantic hierarchy",
+        "Mixed English and Arabic text must render cleanly",
+        "AI needs copy-safe text primitives instead of ad hoc CSS"
+      ],
+      "avoidWhen": [
+        "The text is only a status marker; use Badge instead",
+        "A layout primitive should own spacing instead"
+      ],
+      "neverInvent": [
+        "Viewport-scaled body text",
+        "Negative letter spacing",
+        "Arabic copy not supplied by the product team",
+        "Left/right-only layout rules",
+        "Utopia brand primitives inside reusable component logic"
+      ]
+    }
+  ]
+}