@utopia-studio-design/design-system-cli 0.6.1 → 0.7.0

package/data/manifests/components.json

@@ -5,7 +5,7 @@
       "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",
+      "sourcePath": "packages/design-system/src/components/Primitives.tsx",
       "shadcnFoundation": [
         "accordion",
         "Radix Accordion",
@@ -45,6 +45,7 @@
       ],
       "ai": {
         "props": {
+          "SidebarProvider.placement": "Sets the navigation's logical side to start or end. Defaults to start and remains semantic across LTR and RTL.",
           "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.",
@@ -111,7 +112,7 @@
       "category": "Feedback",
       "status": "available",
       "packageImport": "import { Alert, AlertDescription, AlertTitle } from '@utopia-studio-design/design-system/Alert';",
-      "sourcePath": "packages/design-system/src/components/ShadcnPrimitives.tsx",
+      "sourcePath": "packages/design-system/src/components/Primitives.tsx",
       "shadcnFoundation": [
         "alert",
         "shadcn/ui registry",
@@ -178,7 +179,7 @@
       "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",
+      "sourcePath": "packages/design-system/src/components/Primitives.tsx",
       "shadcnFoundation": [
         "alert-dialog",
         "Radix AlertDialog",
@@ -281,7 +282,7 @@
       "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",
+      "sourcePath": "packages/design-system/src/components/Primitives.tsx",
       "shadcnFoundation": [
         "attachment",
         "shadcn/ui registry",
@@ -333,7 +334,7 @@
           "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."
+          "AttachmentTrigger": "Dashed add/upload trigger; product owns file input behavior. Inside ChatComposer toolbarStart it resolves to the compact semantic chat action size and retains a visible focus ring."
         },
         "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."
       }
@@ -627,8 +628,8 @@
       "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",
+      "packageImport": "import { Bubble } from '@utopia-studio-design/design-system/Primitives';",
+      "sourcePath": "packages/design-system/src/components/Primitives.tsx",
       "shadcnFoundation": [
         "bubble",
         "shadcn/ui registry",
@@ -939,8 +940,8 @@
       "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",
+      "packageImport": "import { Carousel, CarouselButton, CarouselContent, CarouselControls, CarouselItem } from '@utopia-studio-design/design-system/Primitives';",
+      "sourcePath": "packages/design-system/src/components/Primitives.tsx",
       "shadcnFoundation": [
         "carousel",
         "scroll snap carousel",
@@ -983,8 +984,8 @@
       "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",
+      "packageImport": "import { Chart, ChartBars } from '@utopia-studio-design/design-system/Primitives';",
+      "sourcePath": "packages/design-system/src/components/Primitives.tsx",
       "shadcnFoundation": [
         "chart",
         "shadcn/ui chart pattern",
@@ -1048,7 +1049,7 @@
         "--interaction-selection-border"
       ],
       "useWhen": [
-        "Application analytics need Line, Bar, Area, Stacked, Scatter, or Donut families",
+        "Application analytics need Cartesian, radial, matrix, hierarchy, financial, flow, range, or compact KPI chart families",
         "Charts need controlled series visibility and keyboard point exploration",
         "Loading, empty, error, partial, and ready data states must remain explicit",
         "A semantic data table is required as the exact-value alternative"
@@ -1068,7 +1069,8 @@
       ],
       "ai": {
         "props": {
-          "type": "'line' | 'bar' | 'area' | 'stacked' | 'scatter' | 'donut'",
+          "appearance": "'default' | 'mono-rounded'. The mono-rounded preset adapts Amicro Monocharts' monochrome palette and rounded geometry without changing the semantic chart contract.",
+          "type": "Supports 26 families: line, bar, area, stacked, scatter, donut, composed, step, candlestick, kpi, pyramid, radial, gauge, bullet, sankey, radar, funnel, heatmap, sparkline, bubble, treemap, stream, meter, waterfall, polar, and range.",
           "state": "'loading' | 'empty' | 'error' | 'partial' | 'ready'",
           "renderer": "Optional tree-shakeable adapter implementing ChartRendererProps.",
           "direction": "'ltr' | 'rtl'. Changes chronological rendering and logical Arrow key exploration.",
@@ -1190,7 +1192,16 @@
         "--focus-ring-width",
         "--radius-chat-bubble",
         "--radius-chat-composer",
-        "--radius-chat-token"
+        "--radius-chat-token",
+        "--font-size-workspace-body",
+        "--font-size-workspace-label",
+        "--line-height-workspace-body",
+        "--workspace-panel-padding",
+        "--workspace-content-max-inline-size",
+        "--workspace-composer-min-block-size",
+        "--chat-composer-action-size",
+        "--chat-composer-action-icon-size",
+        "--chat-scroller-end-reserve"
       ],
       "useWhen": [
         "Building assistant, support, collaboration, or AI product chat surfaces",
@@ -1211,6 +1222,10 @@
       "ai": {
         "props": {
           "dir": "Use inherited dir by default. Set dir=\"rtl\" only for isolated smoke tests.",
+          "density": "Use compact for persistent product workspaces such as agent consoles and editors; keep default for standalone conversational surfaces.",
+          "drawer": "Render selected attachment or context previews above the input. Do not place the upload trigger or send action here.",
+          "toolbarStart": "Render compact source, attachment, or add controls at the logical start of the bottom toolbar. Icon-only controls inherit the chat action-size contract; do not restore the theme's default button size in page CSS.",
+          "actions": "Render send, stop, dictation, or model actions at the logical end of the same bottom toolbar. Chat action size and icon scale stay proportional to workspace typography through semantic tokens.",
           "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.",
@@ -1593,9 +1608,12 @@
       "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."
+          "scrollMode": "Use managed for viewport-height agent, assistant, or support workspaces; keep static when the document intentionally owns a short transcript.",
+          "messagesLabel": "Required localized region name when scrollMode is managed.",
+          "jumpToLatestLabel": "Required localized live-edge action name when scrollMode is managed.",
+          "composerSubmission": "In managed mode, submitting from the Chat Composer returns the conversation to the live edge after the new message commits. Offscreen assistant updates still preserve the reader's position until they submit or choose the jump action.",
+          "isStreaming": "Reflect the truthful current response state; it never starts or simulates generation.",
+          "children": "Use product-owned copy. The design system supplies layout, scrolling behavior, 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."
       }
@@ -1632,7 +1650,10 @@
         "--focus-ring-width",
         "--radius-chat-bubble",
         "--radius-chat-composer",
-        "--radius-chat-token"
+        "--radius-chat-token",
+        "--chat-composer-action-size",
+        "--chat-composer-action-icon-size",
+        "--chat-scroller-end-reserve"
       ],
       "useWhen": [
         "Building assistant, support, collaboration, or AI product chat surfaces",
@@ -1656,11 +1677,64 @@
           "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."
+          "accessibilityText": "The required accessibilityLabel prop names the scroll action; the optional label prop is localized visible status copy.",
+          "placement": "Managed message scrollers reserve a dedicated end rail for this action. Do not position it over tool, input, or message content."
         },
         "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 Scroller",
+      "category": "Chat",
+      "status": "available",
+      "packageImport": "import { ChatMessageScroller } from '@utopia-studio-design/design-system/Chat';",
+      "sourcePath": "packages/design-system/src/components/Chat.tsx",
+      "shadcnFoundation": [
+        "message-scroller behavior",
+        "scroll-area",
+        "AI/chat product primitive",
+        "semantic Utopia wrapper"
+      ],
+      "fallbackToShadcn": "message-scroller",
+      "requiredTokens": [
+        "--surface-elevated",
+        "--foreground",
+        "--ring",
+        "--focus-ring-width",
+        "--workspace-panel-padding",
+        "--workspace-content-max-inline-size",
+        "--motion-duration-reveal",
+        "--motion-ease-standard"
+      ],
+      "useWhen": [
+        "A conversation owns internal scrolling inside an agent, assistant, or support workspace",
+        "Streaming should follow only while the user remains at the live edge",
+        "History prepend, reload, and offscreen updates must preserve reading position"
+      ],
+      "avoidWhen": [
+        "The transcript is short static content and the document intentionally owns scrolling",
+        "The surface is a marketing testimonial rather than an interactive conversation"
+      ],
+      "neverInvent": [
+        "Always-on bottom locking that interrupts reading",
+        "Unlocalized region and jump-action labels",
+        "Visible scrollbar chrome on Ceramic product surfaces",
+        "Page-local scroll ownership for a managed conversation",
+        "Left/right-only layout rules",
+        "Utopia brand primitives inside reusable component logic"
+      ],
+      "ai": {
+        "props": {
+          "accessibilityLabel": "Required localized name for the scrollable message region.",
+          "jumpToLatestLabel": "Required localized action name for the live-edge control.",
+          "isStreaming": "Reflect the truthful current response state so the log exposes aria-busy and follows only at the live edge.",
+          "scrollToEnd": "Use the imperative handle only for explicit live-edge intent such as composer submission or the localized jump action; never use it to interrupt a reader for passive offscreen updates.",
+          "defaultPosition": "Use end for existing conversations and start only for intentionally top-origin transcripts.",
+          "preserveScrollOnPrepend": "Keep enabled when loading older history above the current viewport."
+        },
+        "arabicFriendly": "Uses logical placement for the live-edge action and inherits dir for mixed-script messages without changing chronological DOM order."
+      }
+    },
     {
       "name": "Chat Message",
       "category": "Chat",
@@ -1933,7 +2007,9 @@
         "--focus-ring-width",
         "--radius-chat-bubble",
         "--radius-chat-composer",
-        "--radius-chat-token"
+        "--radius-chat-token",
+        "--chat-composer-action-size",
+        "--chat-composer-action-icon-size"
       ],
       "useWhen": [
         "Building assistant, support, collaboration, or AI product chat surfaces",
@@ -1957,7 +2033,8 @@
           "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."
+          "accessibilityText": "The required label prop is localized product copy for the send action and current state.",
+          "size": "Uses the compact semantic chat action size and icon scale rather than the active theme's generic button height."
         },
         "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."
       }
@@ -2082,6 +2159,61 @@
         "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 Panel",
+      "category": "Chat",
+      "status": "available",
+      "packageImport": "import { ChatToolPanel } from '@utopia-studio-design/design-system/Chat';",
+      "sourcePath": "packages/design-system/src/components/Chat.tsx",
+      "shadcnFoundation": [
+        "collapsible",
+        "item",
+        "AI/chat tool primitive",
+        "semantic Utopia wrapper"
+      ],
+      "fallbackToShadcn": "collapsible + item",
+      "requiredTokens": [
+        "--surface",
+        "--surface-hover",
+        "--surface-strong",
+        "--foreground",
+        "--foreground-subtle",
+        "--border",
+        "--radius-surface",
+        "--workspace-row-min-block-size",
+        "--workspace-panel-padding",
+        "--chat-tool-panel-max-block-size",
+        "--motion-duration-expand",
+        "--motion-ease-standard"
+      ],
+      "useWhen": [
+        "Search, configuration, connection, or approval controls must stay inside the conversation",
+        "A tool needs a compact summary when idle and a bounded work area when active",
+        "Selected context should remain reviewable without displacing the composer"
+      ],
+      "avoidWhen": [
+        "The content is a generated preview or durable artifact; place that in the output rail",
+        "The control is a single short action that fits directly in a message"
+      ],
+      "neverInvent": [
+        "Unbounded document-like sections inside the transcript",
+        "Generated output inside the tool input panel",
+        "Raw product status or counts that are not backed by data",
+        "Page-local colors, radii, typography, or disclosure motion",
+        "Left/right-only layout rules",
+        "Utopia brand primitives inside reusable component logic"
+      ],
+      "ai": {
+        "props": {
+          "title": "Required localized factual tool name.",
+          "description": "Optional concise localized purpose; keep details inside expanded content.",
+          "count": "Optional truthful count or compact status summary.",
+          "expanded": "Use for controlled disclosure when product state must persist.",
+          "onExpandedChange": "Persist disclosure only when it materially helps task recovery."
+        },
+        "arabicFriendly": "Uses logical grid placement and inherited direction; disclosure rotation is direction-neutral and chronological message order remains unchanged."
+      }
+    },
     {
       "name": "Chat Tool Calls",
       "category": "Chat",
@@ -2114,7 +2246,12 @@
         "--focus-ring-width",
         "--radius-chat-bubble",
         "--radius-chat-composer",
-        "--radius-chat-token"
+        "--radius-chat-token",
+        "--font-size-body",
+        "--font-size-small",
+        "--line-height-body",
+        "--font-size-workspace-label",
+        "--line-height-workspace-body"
       ],
       "useWhen": [
         "Building assistant, support, collaboration, or AI product chat surfaces",
@@ -2138,6 +2275,7 @@
           "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.",
+          "status": "Use pending only for active work. It renders a complete circular track with a rotating indeterminate arc; reduced-motion keeps the ring visible and stops rotation.",
           "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."
@@ -2192,8 +2330,8 @@
       "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",
+      "packageImport": "import { Collapsible, CollapsibleContent, CollapsibleTrigger } from '@utopia-studio-design/design-system/Primitives';",
+      "sourcePath": "packages/design-system/src/components/Primitives.tsx",
       "shadcnFoundation": [
         "collapsible",
         "Radix Collapsible",
@@ -2237,8 +2375,8 @@
       "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",
+      "packageImport": "import { Combobox, ComboboxContent, ComboboxInput, ComboboxOption, ComboboxTrigger } from '@utopia-studio-design/design-system/Primitives';",
+      "sourcePath": "packages/design-system/src/components/Primitives.tsx",
       "shadcnFoundation": [
         "combobox",
         "shadcn/ui registry",
@@ -2478,8 +2616,8 @@
       "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",
+      "packageImport": "import { DataTable, DataTableBody, DataTableCell, DataTableFooter, DataTableHead, DataTableHeader, DataTableRow, DataTableShell, DataTableToolbar } from '@utopia-studio-design/design-system/Primitives';",
+      "sourcePath": "packages/design-system/src/components/Primitives.tsx",
       "shadcnFoundation": [
         "data-table",
         "TanStack Table-compatible composition pattern",
@@ -2591,8 +2729,8 @@
       "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",
+      "packageImport": "import { Dialog, DialogClose, DialogContent, DialogDescription, DialogFooter, DialogHeader, DialogTitle, DialogTrigger } from '@utopia-studio-design/design-system/Primitives';",
+      "sourcePath": "packages/design-system/src/components/Primitives.tsx",
       "shadcnFoundation": [
         "dialog",
         "shadcn/ui registry",
@@ -2640,8 +2778,8 @@
       "name": "Direction",
       "category": "Utilities",
       "status": "available",
-      "packageImport": "import { Direction } from '@utopia-studio-design/design-system/ShadcnPrimitives';",
-      "sourcePath": "packages/design-system/src/components/ShadcnPrimitives.tsx",
+      "packageImport": "import { Direction } from '@utopia-studio-design/design-system/Primitives';",
+      "sourcePath": "packages/design-system/src/components/Primitives.tsx",
       "shadcnFoundation": [
         "direction",
         "shadcn/ui registry",
@@ -2677,8 +2815,8 @@
       "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",
+      "packageImport": "import { Drawer, DrawerClose, DrawerContent, DrawerDescription, DrawerFooter, DrawerHeader, DrawerTitle, DrawerTrigger } from '@utopia-studio-design/design-system/Primitives';",
+      "sourcePath": "packages/design-system/src/components/Primitives.tsx",
       "shadcnFoundation": [
         "drawer",
         "shadcn/ui registry",
@@ -3079,8 +3217,8 @@
       "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",
+      "packageImport": "import { InputGroup, InputGroupInput, InputGroupText } from '@utopia-studio-design/design-system/Primitives';",
+      "sourcePath": "packages/design-system/src/components/Primitives.tsx",
       "shadcnFoundation": [
         "input-group",
         "shadcn/ui registry",
@@ -3117,8 +3255,8 @@
       "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",
+      "packageImport": "import { InputOTP } from '@utopia-studio-design/design-system/Primitives';",
+      "sourcePath": "packages/design-system/src/components/Primitives.tsx",
       "shadcnFoundation": [
         "input-otp",
         "shadcn/ui registry",
@@ -3159,8 +3297,8 @@
       "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",
+      "packageImport": "import { Item, ItemActions, ItemContent, ItemDescription, ItemTitle } from '@utopia-studio-design/design-system/Primitives';",
+      "sourcePath": "packages/design-system/src/components/Primitives.tsx",
       "shadcnFoundation": [
         "item",
         "shadcn/ui registry",
@@ -3196,8 +3334,8 @@
       "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",
+      "packageImport": "import { Kbd } from '@utopia-studio-design/design-system/Primitives';",
+      "sourcePath": "packages/design-system/src/components/Primitives.tsx",
       "shadcnFoundation": [
         "kbd",
         "shadcn/ui registry",
@@ -3231,8 +3369,8 @@
       "name": "Label",
       "category": "Forms",
       "status": "available",
-      "packageImport": "import { Label } from '@utopia-studio-design/design-system/ShadcnPrimitives';",
-      "sourcePath": "packages/design-system/src/components/ShadcnPrimitives.tsx",
+      "packageImport": "import { Label } from '@utopia-studio-design/design-system/Primitives';",
+      "sourcePath": "packages/design-system/src/components/Primitives.tsx",
       "shadcnFoundation": [
         "label",
         "shadcn/ui registry",
@@ -3267,8 +3405,8 @@
       "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",
+      "packageImport": "import { Menubar, MenubarCheckboxItem, MenubarContent, MenubarGroup, MenubarItem, MenubarLabel, MenubarMenu, MenubarRadioGroup, MenubarRadioItem, MenubarSeparator, MenubarShortcut, MenubarSub, MenubarSubContent, MenubarSubTrigger, MenubarTrigger } from '@utopia-studio-design/design-system/Primitives';",
+      "sourcePath": "packages/design-system/src/components/Primitives.tsx",
       "shadcnFoundation": [
         "menubar",
         "shadcn/ui registry",
@@ -3543,8 +3681,8 @@
       "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",
+      "packageImport": "import { NavigationMenu, NavigationMenuContent, NavigationMenuIndicator, NavigationMenuItem, NavigationMenuLink, NavigationMenuList, NavigationMenuTrigger, NavigationMenuViewport } from '@utopia-studio-design/design-system/Primitives';",
+      "sourcePath": "packages/design-system/src/components/Primitives.tsx",
       "shadcnFoundation": [
         "navigation-menu",
         "shadcn/ui registry",
@@ -3590,8 +3728,8 @@
       "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",
+      "packageImport": "import { Pagination, PaginationContent, PaginationEllipsis, PaginationItem, PaginationLink, PaginationNext, PaginationPrevious } from '@utopia-studio-design/design-system/Primitives';",
+      "sourcePath": "packages/design-system/src/components/Primitives.tsx",
       "shadcnFoundation": [
         "pagination",
         "shadcn/ui registry",
@@ -3791,8 +3929,8 @@
       "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",
+      "packageImport": "import { Resizable, ResizableHandle, ResizablePanel } from '@utopia-studio-design/design-system/Primitives';",
+      "sourcePath": "packages/design-system/src/components/Primitives.tsx",
       "shadcnFoundation": [
         "resizable",
         "shadcn/ui registry",
@@ -3838,8 +3976,8 @@
       "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",
+      "packageImport": "import { ScrollArea, ScrollAreaCorner, ScrollAreaViewport, ScrollBar } from '@utopia-studio-design/design-system/Primitives';",
+      "sourcePath": "packages/design-system/src/components/Primitives.tsx",
       "shadcnFoundation": [
         "scroll-area",
         "shadcn/ui registry",
@@ -3971,8 +4109,8 @@
       "name": "Separator",
       "category": "Layout",
       "status": "available",
-      "packageImport": "import { Separator } from '@utopia-studio-design/design-system/ShadcnPrimitives';",
-      "sourcePath": "packages/design-system/src/components/ShadcnPrimitives.tsx",
+      "packageImport": "import { Separator } from '@utopia-studio-design/design-system/Primitives';",
+      "sourcePath": "packages/design-system/src/components/Primitives.tsx",
       "shadcnFoundation": [
         "separator",
         "shadcn/ui registry",
@@ -4002,8 +4140,8 @@
       "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",
+      "packageImport": "import { Sheet, SheetClose, SheetContent, SheetDescription, SheetFooter, SheetHeader, SheetTitle, SheetTrigger } from '@utopia-studio-design/design-system/Primitives';",
+      "sourcePath": "packages/design-system/src/components/Primitives.tsx",
       "shadcnFoundation": [
         "sheet",
         "shadcn/ui registry",
@@ -4432,7 +4570,8 @@
           "SidebarMenuButton.isActive": "Marks the item active and supplies aria-current=page unless the consumer provides another aria-current value.",
           "SidebarMenuButton.tooltip": "Provides collapsed hover/focus help and an accessible name when aria-label is omitted."
         },
-        "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."
+        "usage": "Wrap the complete shell in SidebarProvider and pass placement=start|end. Keep Sidebar and SidebarInset as siblings so the provider can place navigation on the requested logical side. Persist the semantic value, never a physical left/right value.",
+        "arabicFriendly": "Use dir=rtl at the shell boundary and provide localized collapseLabel, expandLabel, overlay labels, rail labels, and tooltip strings. placement=start resolves to the physical right in RTL, while placement=end resolves to the physical left. Borders, active indicators, rails, tooltips, off-canvas motion, submenus, and badges mirror automatically."
       }
     },
     {
@@ -4506,6 +4645,7 @@
           "NavigationIcon"
         ],
         "props": {
+          "SidebarProvider.placement": "Sets the block on the logical start or end side. Defaults to start.",
           "SidebarBlockType1.brand": "Required app-owned brand node shown only in the expanded sidebar.",
           "SidebarBlockType1.collapsedIcon": "Optional app-owned compact mark shown in the collapsed desktop trigger; hover reveals the panel icon.",
           "SidebarBlockType1.children": "Grouped Sidebar navigation primitives. Product routing remains consumer-owned.",
@@ -4514,8 +4654,8 @@
           "SidebarBlockType1Workspace.label": "Required factual workspace label. Keep detailed metadata in the consumer-owned dialog.",
           "SidebarBlockType1Workspace.description": "Optional short metadata only; omit when it would truncate into low-value ellipsis."
         },
-        "usage": "Wrap the application shell in SidebarProvider. Render SidebarBlockType1 with localized labels and app-owned brand/navigation/footer slots. Use SidebarBlockType1Trigger in the mobile topbar so the menu remains visible when the off-canvas sidebar is closed.",
-        "arabicFriendly": "All alignment and off-canvas positioning use logical properties. Provide localized trigger, overlay, group, item, and workspace labels. The hamburger and panel icons are direction-neutral."
+        "usage": "Wrap the application shell in SidebarProvider and pass the persisted semantic placement. Render SidebarBlockType1 with localized labels and app-owned brand/navigation/footer slots. Use SidebarBlockType1Trigger in the mobile topbar so the menu remains visible when the off-canvas sidebar is closed.",
+        "arabicFriendly": "All alignment and off-canvas positioning use logical properties. placement=start is physically right in RTL and placement=end is physically left. Provide localized trigger, overlay, group, item, and workspace labels. The hamburger remains direction-neutral; the panel control reflects the physical panel side."
       }
     },
     {
@@ -4556,8 +4696,8 @@
       "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",
+      "packageImport": "import { Toaster, toast } from '@utopia-studio-design/design-system/Primitives';",
+      "sourcePath": "packages/design-system/src/components/Primitives.tsx",
       "shadcnFoundation": [
         "sonner",
         "shadcn/ui registry",
@@ -4637,9 +4777,9 @@
       ],
       "fallbackToShadcn": "spinner",
       "requiredTokens": [
-        "--brand-loader-background",
-        "--brand-loader-accent",
-        "--brand-loader-foreground",
+        "--loading-background",
+        "--loading-accent",
+        "--loading-foreground",
         "--brand-loader-size",
         "--brand-loader-duration-enter",
         "--brand-loader-duration-cycle",
@@ -4927,6 +5067,8 @@
         "--secondary",
         "--secondary-hover",
         "--secondary-active",
+        "--interaction-selection-surface",
+        "--interaction-selection-border",
         "--radius-control",
         "--button-height",
         "--focus-ring-width"
@@ -5327,6 +5469,115 @@
         "arabicFriendly": "Trigger and content align with logical inline start/end."
       }
     },
+    {
+      "name": "Code Block",
+      "category": "Data Display",
+      "status": "available",
+      "packageImport": "import { CodeBlock } from '@utopia-studio-design/design-system/CodeBlock';",
+      "sourcePath": "packages/design-system/src/components/CodeBlock.tsx",
+      "shadcnFoundation": ["code block", "button", "semantic Utopia wrapper"],
+      "fallbackToShadcn": "code-block",
+      "requiredTokens": [
+        "--surface", "--surface-hover", "--foreground", "--muted-foreground", "--border",
+        "--success-text", "--radius-surface", "--font-mono", "--font-size-small",
+        "--font-size-supporting", "--button-height-lg", "--icon-size-md", "--space-4",
+        "--focus-ring", "--focus-ring-width"
+      ],
+      "useWhen": [
+        "Documentation exposes code, commands, configuration, or agent instructions",
+        "Users need to copy an exact reusable snippet",
+        "A language label helps identify the snippet format"
+      ],
+      "avoidWhen": [
+        "A short inline identifier belongs inside prose",
+        "The content is editable; use a text input or code editor",
+        "Copying the content would be unsafe or misleading"
+      ],
+      "neverInvent": [
+        "Utopia brand primitives or raw brand colors",
+        "Unlocalized copy feedback",
+        "A second interactive copy control outside the code block",
+        "Left/right-only positioning"
+      ],
+      "ai": {
+        "props": {
+          "code": "Exact plain-text content rendered and copied by the component.",
+          "language": "Short visible format label such as tsx, bash, json, or text.",
+          "copyLabel": "Localized accessible name for the idle copy action.",
+          "copiedLabel": "Localized accessible name and live feedback after a successful copy.",
+          "onCopyError": "Optional callback for consumer-owned clipboard error handling.",
+          "className": "Optional consumer class applied to the semantic root."
+        },
+        "rules": [
+          "Use one CodeBlock for each independently reusable snippet.",
+          "Keep copied text byte-for-byte aligned with the visible code.",
+          "Supply localized copyLabel and copiedLabel in localized products.",
+          "Do not place a second copy button beside CodeBlock."
+        ],
+        "arabicFriendly": "The header follows logical inline direction while code content remains LTR for stable commands and source. Localize copyLabel and copiedLabel; never invent Arabic production code or copy."
+      }
+    },
+    {
+      "name": "Workspace Journey",
+      "category": "Navigation",
+      "status": "available",
+      "packageImport": "import { WorkspaceJourney } from '@utopia-studio-design/design-system/Navigation';",
+      "sourcePath": "packages/design-system/src/components/Navigation.tsx",
+      "shadcnFoundation": [
+        "semantic navigation",
+        "button",
+        "responsive dense surface",
+        "Ceramic workspace wrapper"
+      ],
+      "fallbackToShadcn": "navigation-menu",
+      "requiredTokens": [
+        "--surface-hover",
+        "--foreground-subtle",
+        "--border",
+        "--interaction-selection-surface",
+        "--success-text",
+        "--primary",
+        "--workspace-row-min-block-size",
+        "--workspace-panel-padding",
+        "--font-size-workspace-body",
+        "--font-size-workspace-label",
+        "--focus-ring-width",
+        "--focus-ring-offset",
+        "--ring"
+      ],
+      "useWhen": [
+        "A persistent workspace exposes ordered stages with complete, current, and locked states",
+        "Users need to revisit completed stages without rolling back workflow progress",
+        "The same stage navigation must reflow between a vertical rail, a compact horizontal strip, and a two-column mobile summary"
+      ],
+      "avoidWhen": [
+        "The sequence submits one linear form; use a form progress pattern",
+        "Every destination is independently available; use Tabs or Side Nav",
+        "The stages are only decorative status and cannot change the visible workspace"
+      ],
+      "neverInvent": [
+        "Page-owned stage truncation or overflow rules",
+        "Raw colors, radii, spacing, or left/right positioning",
+        "Left/right-only layout rules instead of logical properties",
+        "Utopia brand primitives inside reusable component logic",
+        "A horizontal strip or carousel that clips unreachable stages",
+        "Color-only current, complete, or locked state"
+      ],
+      "ai": {
+        "props": {
+          "aria-label": "Localized name for the stage navigation region.",
+          "items": "Ordered stable ids, labels, localized state labels, and complete/current/locked states.",
+          "selectedId": "The stage whose content is currently visible; it receives aria-current=step.",
+          "onSelect": "Changes only the visible stage. Locked stages remain disabled."
+        },
+        "rules": [
+          "Labels stay on one line and ellipsize visually while aria-label and title preserve the complete label.",
+          "At compact widths all stages share the available row; at mobile widths the component reflows to two columns without adding horizontal scrolling.",
+          "Do not use the component to imply progress that the application has not persisted."
+        ],
+        "arabicFriendly": "Logical inline borders mirror in RTL. Localized labels keep their full accessible name even when visually truncated."
+      }
+    },
     {
       "name": "Typography",
       "category": "Data Display",