@utopia-studio-design/design-system-cli 0.3.3 → 0.4.0

package/README.md

@@ -4,7 +4,7 @@ The same structured API powers terminal output, JSON automation, generated agent
 
 ```sh
 npm install -D @utopia-studio-design/design-system-cli
-npx utopia-ds init
+npx utopia-ds init . --theme utopia-default --yes
 npx utopia-ds search "Arabic data table" --json
 npx utopia-ds component DataTable --json
 npx utopia-ds template template-saas-solution-homepage --copy ./saas-website

package/bin/utopia-ds.mjs

@@ -11,10 +11,24 @@ import { createTemplateSubmissionUrl, validateTemplateSubmission } from '../lib/
 const args = process.argv.slice(2)
 const command = args.find((arg) => !arg.startsWith('--')) ?? 'help'
 const commandIndex = args.indexOf(command)
-const values = commandIndex >= 0 ? args.slice(commandIndex + 1).filter((arg) => !arg.startsWith('--')) : []
+const optionsWithValues = new Set(['--copy', '--theme'])
+const values = commandIndex >= 0 ? positionalValues(args.slice(commandIndex + 1)) : []
 const json = args.includes('--json')
 const dense = args.includes('--dense')
 
+function positionalValues(input) {
+  const positionals = []
+  for (let index = 0; index < input.length; index += 1) {
+    const argument = input[index]
+    if (optionsWithValues.has(argument)) {
+      index += 1
+      continue
+    }
+    if (!argument.startsWith('--')) positionals.push(argument)
+  }
+  return positionals
+}
+
 function output(type, data, format = null) {
   if (json) return console.log(JSON.stringify(envelope(type, data), null, 2))
   if (format) return console.log(format(data, dense))
@@ -29,7 +43,13 @@ function fail(message, code = 'ERR_INPUT', suggestions = []) {
 
 function argAfter(flag, fallback) {
   const index = args.indexOf(flag)
-  return index >= 0 ? args[index + 1] : fallback
+  if (index < 0) return fallback
+  const value = args[index + 1]
+  if (!value || value.startsWith('--')) {
+    fail(`${flag} requires a value.`, 'ERR_ARGUMENT')
+    return null
+  }
+  return value
 }
 
 function help() {
@@ -150,6 +170,7 @@ function scaffoldTheme() {
 function init() {
   const target = resolve(values[0] ?? process.cwd())
   const theme = argAfter('--theme', 'utopia-default')
+  if (!theme) return
   if (!getTheme(theme)) return fail(`Unknown theme "${theme}".`, 'ERR_THEME', listThemes().map((item) => item.id))
   const pkgPath = join(target, 'package.json')
   if (!existsSync(pkgPath)) return fail(`No package.json found in ${target}.`, 'ERR_PROJECT')
@@ -186,8 +207,10 @@ function runMcp() {
 function copyTemplateProject(entry) {
   if (!entry.bundlePath) return fail(`Template "${entry.id}" is a blueprint contract and has no runnable bundle.`, 'ERR_TEMPLATE_BUNDLE')
   const requestedTarget = argAfter('--copy', entry.id.replace(/^template-/, ''))
+  if (!requestedTarget) return
   const target = resolve(requestedTarget)
   const theme = argAfter('--theme', 'utopia-default')
+  if (!theme) return
   if (!getTheme(theme)) return fail(`Unknown theme "${theme}".`, 'ERR_THEME', listThemes().map((item) => item.id))
   if (existsSync(target) && !args.includes('--force')) return fail(`Target already exists: ${target}. Pass --force to overwrite it.`, 'ERR_TARGET_EXISTS')
   const source = resolve(dirname(new URL(import.meta.url).pathname), '..', 'data', entry.bundlePath)

package/data/docs/foundations.md

@@ -121,9 +121,37 @@ The engine-neutral registry is published as `manifests/motion-profiles.json`. It
 - Core owns icon slots, icon-only controls, labels, and accessibility.
 - Theme manifests own icon philosophy and icon style.
 - Use `lucide-react` as the default shadcn/ui icon baseline for examples and previews.
+- Use `PhosphorIcon` when a product selects the Phosphor family. Import individual
+  `*Icon` exports from `@phosphor-icons/react` so bundlers can tree-shake unused icons.
+- `PhosphorIcon` uses `currentColor` and `--icon-size-xs|sm|md`; do not pass raw
+  color or pixel sizes.
+- Mark visual-only icons with `decorative`. Give meaningful standalone icons a
+  localized `label`. Put interactive icons inside `IconButton` and label the button.
 - Mirror arrows and chevrons when they mean previous/next, open/close, or inline movement.
 - Do not mirror direction-neutral icons such as settings, add, download, home, camera, or panel icons unless a theme says otherwise.
 
+```tsx
+import { ArrowRightIcon, HouseIcon } from '@phosphor-icons/react'
+import { PhosphorIcon } from '@utopia-studio-design/design-system/PhosphorIcon'
+
+export function IconExamples() {
+  return (
+    <>
+      <PhosphorIcon decorative icon={HouseIcon} size="sm" />
+      <PhosphorIcon
+        direction="directional"
+        icon={ArrowRightIcon}
+        label="Continue"
+      />
+    </>
+  )
+}
+```
+
+Phosphor is an additional supported family, not a silent replacement for
+Lucide-based component internals. Breadcrumb separators and existing Ceramic
+navigation defaults keep their documented icon contracts.
+
 ## Illustration Contract
 
 - Illustrations are theme and product media, not core component requirements.

package/data/docs/guide.md

@@ -87,6 +87,28 @@ import {
 - `BreadcrumbSeparator` provides an RTL-aware Lucide `ChevronRight` by default. Breadcrumb does not add a home icon.
 - Breadcrumb links own their no-underline treatment and compact typography, so consumer-level anchor styles do not require an override.
 
+## Phosphor Icon Composition
+
+Phosphor is an optional supported icon family. It does not replace Lucide-based
+defaults inside existing Ceramic components.
+
+```tsx
+import { GearIcon } from '@phosphor-icons/react'
+import { IconButton } from '@utopia-studio-design/design-system/IconButton'
+import { PhosphorIcon } from '@utopia-studio-design/design-system/PhosphorIcon'
+
+<IconButton label="Settings">
+  <PhosphorIcon decorative icon={GearIcon} size="sm" />
+</IconButton>
+```
+
+- Install `@phosphor-icons/react` in an application that imports Phosphor icons directly.
+- Import named `*Icon` exports so unused icons can be removed from the bundle.
+- Use `decorative` when the surrounding control or text already supplies the accessible name.
+- Use `label` for a meaningful standalone icon.
+- Set `direction="directional"` only for arrows, chevrons, and other meanings that follow reading direction.
+- Keep color inherited and select `xs`, `sm`, or `md`; do not pass raw color or pixel size values.
+
 ## AI Rule
 
 Before generating UI, read:

package/data/docs/quick-start-ai.md

@@ -5,7 +5,7 @@ Ceramic follows the Astryx principle that humans, coding agents, build tools, an
 ## Paste This Into Your AI
 
 ```text
-Install @utopia-studio-design/design-system and @utopia-studio-design/design-system-cli. Run `npx utopia-ds init --theme utopia-default`. Read the generated AGENTS.md and active theme config. Before editing UI, run `npx utopia-ds manifest --json`, search for the intended pattern, inspect its component or template contract, and read the Arabic-friendly guide when the product supports Arabic or RTL. Do not invent props, imports, tokens, or localized copy.
+Install @utopia-studio-design/design-system and @utopia-studio-design/design-system-cli. Run `npx utopia-ds init . --theme utopia-default --yes`. Read the generated AGENTS.md and active theme config. Before editing UI, run `npx utopia-ds manifest --json`, search for the intended pattern, inspect its component or template contract, and read the Arabic-friendly guide when the product supports Arabic or RTL. Do not invent props, imports, tokens, or localized copy.
 ```
 
 ## Install
@@ -13,7 +13,7 @@ Install @utopia-studio-design/design-system and @utopia-studio-design/design-sys
 ```sh
 npm install @utopia-studio-design/design-system
 npm install -D @utopia-studio-design/design-system-cli
-npx utopia-ds init --theme utopia-default
+npx utopia-ds init . --theme utopia-default --yes
 ```
 
 The init command creates:

package/data/manifests/catalog.json

@@ -71,6 +71,7 @@
             "Card",
             "Hover Card",
             "Popover",
+            "Tool Connector Block",
             "Tooltip"
           ]
         },
@@ -98,6 +99,7 @@
           "id": "chat",
           "label": "Chat",
           "items": [
+            "Assistant Panel",
             "Chat Composer",
             "Chat Composer Drawer",
             "Chat Composer Input",
@@ -133,6 +135,7 @@
             "Navigation Menu",
             "Pagination",
             "Sidebar",
+            "Sidebar Block Type 1",
             "Side Nav",
             "Side Nav Collapse Button",
             "Side Nav Heading",
@@ -174,6 +177,13 @@
             "Separator"
           ]
         },
+        {
+          "id": "utilities",
+          "label": "Utilities",
+          "items": [
+            "Phosphor Icon"
+          ]
+        },
         {
           "id": "data",
           "label": "Data Display",
@@ -249,6 +259,7 @@
       "Card",
       "Carousel",
       "Chart",
+      "Assistant Panel",
       "Chat Composer",
       "Chat Composer Drawer",
       "Chat Composer Input",
@@ -289,6 +300,7 @@
       "Native Select",
       "Navigation Menu",
       "Pagination",
+      "Phosphor Icon",
       "Popover",
       "Progress",
       "Radio Group",
@@ -307,6 +319,7 @@
       "Textarea",
       "Toggle Button",
       "Toggle Button Group",
+      "Tool Connector Block",
       "Tooltip",
       "Typography",
       "Utopia Wordmark Loader"
@@ -327,6 +340,7 @@
       "Card",
       "Carousel",
       "Chart",
+      "Assistant Panel",
       "Chat Composer",
       "Chat Composer Drawer",
       "Chat Composer Input",
@@ -367,6 +381,7 @@
       "Native Select",
       "Navigation Menu",
       "Pagination",
+      "Phosphor Icon",
       "Popover",
       "Progress",
       "Radio Group",
@@ -385,6 +400,7 @@
       "Textarea",
       "Toggle Button",
       "Toggle Button Group",
+      "Tool Connector Block",
       "Tooltip",
       "Typography",
       "Utopia Wordmark Loader"

package/data/manifests/components.json

@@ -1015,6 +1015,86 @@
         "Utopia brand primitives inside reusable component logic"
       ]
     },
+    {
+      "name": "Assistant Panel",
+      "category": "Chat",
+      "status": "available",
+      "packageImport": "import { AssistantPanel, AssistantPanelActions, AssistantPanelBody, AssistantPanelClose, AssistantPanelDescription, AssistantPanelEmptyState, AssistantPanelFooter, AssistantPanelHeader, AssistantPanelHeading, AssistantPanelTitle } from '@utopia-studio-design/design-system/AssistantPanel';",
+      "sourcePath": "packages/design-system/src/components/AssistantPanel.tsx",
+      "shadcnFoundation": [
+        "sidebar composition",
+        "sheet visual anatomy without dialog behavior",
+        "scrollable content and sticky composer regions",
+        "semantic Utopia wrapper"
+      ],
+      "fallbackToShadcn": "sidebar + resizable + message",
+      "requiredTokens": [
+        "--background",
+        "--surface",
+        "--foreground",
+        "--foreground-muted",
+        "--border",
+        "--primary",
+        "--space-1",
+        "--space-2",
+        "--space-3",
+        "--space-4",
+        "--space-6",
+        "--space-8",
+        "--space-12",
+        "--space-16",
+        "--font-size-supporting",
+        "--font-size-small",
+        "--font-size-body",
+        "--font-weight-strong",
+        "--line-height-supporting",
+        "--line-height-body",
+        "--line-height-tight",
+        "--tracking-heading",
+        "--icon-size-sm",
+        "--icon-size-md",
+        "--border-width-hairline"
+      ],
+      "useWhen": [
+        "An assistant, inspector, or contextual workflow must remain visible beside the primary workspace",
+        "The product needs a non-modal panel with fixed header and footer plus independently scrolling content",
+        "Chat primitives need a reusable application frame rather than page-local panel styling"
+      ],
+      "avoidWhen": [
+        "The panel must block the page or trap focus; use Sheet or Dialog",
+        "A temporary mobile action sheet is required; use Drawer",
+        "The content is primary navigation; use Sidebar"
+      ],
+      "neverInvent": [
+        "Overlay or focus-trap behavior",
+        "Raw shadcn theme colors",
+        "Product-specific assistant copy",
+        "Left/right-only layout rules",
+        "Utopia brand primitives inside reusable component logic"
+      ],
+      "ai": {
+        "parts": [
+          "AssistantPanel",
+          "AssistantPanelHeader",
+          "AssistantPanelHeading",
+          "AssistantPanelTitle",
+          "AssistantPanelDescription",
+          "AssistantPanelActions",
+          "AssistantPanelClose",
+          "AssistantPanelBody",
+          "AssistantPanelEmptyState",
+          "AssistantPanelFooter"
+        ],
+        "props": {
+          "AssistantPanel.header": "Compose AssistantPanelHeader or another product-owned header region.",
+          "AssistantPanel.body": "Compose AssistantPanelBody, usually containing ChatMessageList or task context.",
+          "AssistantPanel.footer": "Compose AssistantPanelFooter with ChatComposer or product actions.",
+          "AssistantPanelClose.label": "Required localized accessible label for the icon-only close action.",
+          "AssistantPanelEmptyState": "Supply product-owned title, description, optional icon, and actions."
+        },
+        "arabicFriendly": "The panel uses logical inline borders and spacing, inherits document direction, and does not encode left or right docking. Product copy and close labels must be localized by the consumer."
+      }
+    },
     {
       "name": "Chat Composer",
       "category": "Chat",
@@ -1076,6 +1156,86 @@
         "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": "Tool Connector Block",
+      "category": "Surface",
+      "status": "available",
+      "packageImport": "import { ToolConnectorBlock, ToolConnectorItem, ToolConnectorList, ToolConnectorSection } from '@utopia-studio-design/design-system/ToolConnector';",
+      "sourcePath": "packages/design-system/src/components/ToolConnector.tsx",
+      "shadcnFoundation": [
+        "item",
+        "badge",
+        "collapsible disclosure",
+        "settings and integration list composition",
+        "semantic Utopia wrapper"
+      ],
+      "fallbackToShadcn": "item + badge + collapsible",
+      "requiredTokens": [
+        "--surface",
+        "--surface-hover",
+        "--foreground",
+        "--muted-foreground",
+        "--border",
+        "--primary",
+        "--focus-ring",
+        "--radius-surface",
+        "--radius-control",
+        "--space-1",
+        "--space-3",
+        "--space-4",
+        "--space-6",
+        "--space-8",
+        "--space-16",
+        "--font-size-supporting",
+        "--font-size-small",
+        "--font-weight-medium",
+        "--font-weight-strong",
+        "--line-height-supporting",
+        "--line-height-tight",
+        "--icon-size-sm",
+        "--button-height-sm",
+        "--border-width-hairline",
+        "--duration-fast",
+        "--ease-standard"
+      ],
+      "useWhen": [
+        "A settings surface must list external tools, services, or data connectors with status and a clear next action",
+        "Connected and available integrations need compact scan-friendly grouping",
+        "A connector needs optional inline setup or management details without navigating away"
+      ],
+      "avoidWhen": [
+        "The product needs a searchable marketplace with hundreds of integrations; use a dedicated page with filters",
+        "The row is primary navigation rather than an integration action",
+        "Irreversible disconnect confirmation is required; compose Alert Dialog in the consumer"
+      ],
+      "neverInvent": [
+        "Third-party connection state or account identity",
+        "Raw brand colors for external services",
+        "Product-specific OAuth or disconnect logic",
+        "Left/right-only layout rules",
+        "Utopia brand primitives inside reusable component logic"
+      ],
+      "ai": {
+        "parts": [
+          "ToolConnectorBlock",
+          "ToolConnectorSection",
+          "ToolConnectorList",
+          "ToolConnectorItem"
+        ],
+        "props": {
+          "ToolConnectorSection.title": "Required localized group label such as Connected or Available tools.",
+          "ToolConnectorSection.description": "Optional concise explanation of the group.",
+          "ToolConnectorItem.icon": "Optional app-owned or design-system icon. Do not synthesize third-party logos.",
+          "ToolConnectorItem.title": "Required factual connector name.",
+          "ToolConnectorItem.description": "Required concise capability description.",
+          "ToolConnectorItem.status": "Optional short status rendered with Badge; use semantic statusVariant.",
+          "ToolConnectorItem.actionLabel": "Required explicit action such as Connect, Manage, Open, or Add link.",
+          "ToolConnectorItem.detail": "Optional consumer-owned setup or management content.",
+          "ToolConnectorItem.expanded": "Controls inline detail visibility; state remains consumer-owned."
+        },
+        "arabicFriendly": "The block uses logical spacing and inline alignment, keeps actions at inline-end, wraps to a compact mobile layout, and requires localized labels and status copy from the consumer."
+      }
+    },
     {
       "name": "Chat Composer Drawer",
       "category": "Chat",
@@ -2159,7 +2319,8 @@
       "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'"
+        "Arabic-friendly data displays that must preserve table meaning in dir='rtl'",
+        "Responsive dashboards where wide tables must scroll inside the component instead of expanding the page"
       ],
       "avoidWhen": [
         "Card lists are easier to scan",
@@ -2170,7 +2331,14 @@
         "Raw shadcn theme colors",
         "Left/right-only layout rules",
         "Utopia brand primitives inside reusable component logic"
-      ]
+      ],
+      "ai": {
+        "props": {
+          "DataTableShell": "Full-width bounded shell with min-inline-size: 0 and component-owned horizontal scrolling. Place DataTableToolbar, DataTable, and DataTableFooter inside it.",
+          "DataTable": "Semantic table content may exceed the available inline size; its nearest DataTableShell owns horizontal overflow."
+        },
+        "responsive": "Keep DataTableShell inside a min-inline-size: 0 grid or flex child. The shell prevents intrinsic table width from creating page-level horizontal scrolling."
+      }
     },
     {
       "name": "Date Picker",
@@ -2636,6 +2804,65 @@
         ]
       }
     },
+    {
+      "name": "Phosphor Icon",
+      "category": "Utilities",
+      "status": "available",
+      "packageImport": "import { PhosphorIcon } from '@utopia-studio-design/design-system/PhosphorIcon';",
+      "sourcePath": "packages/design-system/src/components/PhosphorIcon.tsx",
+      "shadcnFoundation": [
+        "@phosphor-icons/react",
+        "named icon imports",
+        "semantic icon size tokens",
+        "currentColor"
+      ],
+      "fallbackToShadcn": "lucide-react icon composed through the same semantic slot",
+      "requiredTokens": [
+        "--icon-size-xs",
+        "--icon-size-sm",
+        "--icon-size-md"
+      ],
+      "useWhen": [
+        "A product selects the Phosphor icon family",
+        "Ceramic must own icon sizing, accessibility, and RTL behavior",
+        "A named Phosphor icon is imported directly for tree-shaking"
+      ],
+      "avoidWhen": [
+        "The icon itself is interactive; compose it inside IconButton",
+        "An existing Ceramic component already owns its Lucide-based icon contract",
+        "Replacing Breadcrumb or Navigation defaults without a component-specific decision"
+      ],
+      "neverInvent": [
+        "Raw SVG paths copied into product code",
+        "Raw color or pixel icon sizes",
+        "Unlabeled meaningful standalone icons",
+        "Mirroring direction-neutral icons",
+        "Namespace imports that prevent per-icon tree-shaking",
+        "Left/right-only layout rules",
+        "Utopia brand primitives inside reusable component logic"
+      ],
+      "ai": {
+        "props": [
+          "icon",
+          "size",
+          "weight",
+          "decorative",
+          "label",
+          "direction"
+        ],
+        "rules": [
+          "Import individual *Icon exports from @phosphor-icons/react.",
+          "Use decorative for visual-only icons and a localized label for meaningful standalone icons.",
+          "Use direction=\"directional\" only when the icon meaning follows reading direction.",
+          "Color is inherited through currentColor and size comes from Ceramic semantic tokens."
+        ],
+        "arabicFriendly": [
+          "Directional arrows and chevrons mirror when the wrapper is inside dir=\"rtl\".",
+          "Home, settings, search, download, and other direction-neutral icons do not mirror.",
+          "Use localized accessible labels supplied by the product."
+        ]
+      }
+    },
     {
       "name": "Input",
       "category": "Forms",
@@ -4024,6 +4251,89 @@
         "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": "Sidebar Block Type 1",
+      "category": "Navigation",
+      "status": "available",
+      "packageImport": "import { SidebarBlockType1, SidebarBlockType1Trigger, SidebarBlockType1Workspace } from '@utopia-studio-design/design-system/Sidebar';",
+      "sourcePath": "packages/design-system/src/components/Sidebar.tsx",
+      "shadcnFoundation": [
+        "sidebar",
+        "button",
+        "off-canvas navigation",
+        "semantic Utopia application block"
+      ],
+      "fallbackToShadcn": "sidebar",
+      "requiredTokens": [
+        "--background",
+        "--foreground",
+        "--border",
+        "--primary",
+        "--muted-foreground",
+        "--surface-hover",
+        "--radius-control",
+        "--sidebar-width",
+        "--sidebar-width-collapsed",
+        "--sidebar-min-block-size",
+        "--nav-item-height",
+        "--button-height-sm",
+        "--icon-size-sm",
+        "--space-1",
+        "--space-2",
+        "--space-3",
+        "--space-4",
+        "--space-6",
+        "--space-12",
+        "--space-16",
+        "--border-width-hairline",
+        "--border-width-strong"
+      ],
+      "useWhen": [
+        "A clean application sidebar needs an expanded text-first navigation and icon-only desktop collapse",
+        "The same navigation must become a mobile off-canvas panel with a compact ghost hamburger trigger",
+        "Brand, grouped navigation, and an optional bottom-pinned workspace/details action should share one production-ready composition",
+        "A product needs a standard Sidebar block without copying page-local layout CSS"
+      ],
+      "avoidWhen": [
+        "A documentation tree should use Side Nav",
+        "Product routing, workspace data, dialog content, or brand artwork would be hardcoded into the design-system block",
+        "A temporary supplemental surface should use Sheet or Drawer"
+      ],
+      "neverInvent": [
+        "Product-specific menu destinations",
+        "Workspace names, user names, or organization data",
+        "Raw colors, spacing, or icon sizes",
+        "Left/right-only layout rules",
+        "Utopia brand primitives inside reusable component logic",
+        "A switcher chevron when no switching action exists",
+        "Desktop collapse controls on mobile"
+      ],
+      "ai": {
+        "parts": [
+          "SidebarProvider",
+          "SidebarBlockType1",
+          "SidebarBlockType1Trigger",
+          "SidebarBlockType1Workspace",
+          "SidebarGroup",
+          "SidebarGroupLabel",
+          "SidebarMenu",
+          "SidebarMenuItem",
+          "SidebarMenuButton",
+          "NavigationIcon"
+        ],
+        "props": {
+          "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.",
+          "SidebarBlockType1.footer": "Optional bottom-pinned action, commonly SidebarBlockType1Workspace composed with DialogTrigger asChild.",
+          "SidebarBlockType1Trigger": "Use in both the sidebar header and a mobile topbar. It chooses desktop panel control or mobile hamburger from SidebarProvider state.",
+          "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."
+      }
+    },
     {
       "name": "Slider",
       "category": "Forms",
@@ -4268,7 +4578,8 @@
       "useWhen": [
         "Peer views",
         "Same-context panels",
-        "Keyboard-switchable content sections"
+        "Keyboard-switchable content sections",
+        "Full-width application workspaces when layout='fluid'"
       ],
       "avoidWhen": [
         "Page navigation",
@@ -4282,6 +4593,7 @@
       ],
       "ai": {
         "props": {
+          "layout": "Use 'contained' for compact content panels (the default 42rem measure) or 'fluid' for dashboards and application workspaces that should fill the available inline size.",
           "motion": "Optional boolean. Defaults to the MotionProvider policy and disables this component pattern when false."
         }
       }

package/lib/api.mjs

@@ -8,7 +8,7 @@ const packagedDataRoot = join(packageRoot, 'data')
 const hasWorkspaceSource = existsSync(join(workspaceRoot, 'packages/design-system/src/manifests/components.json'))
 
 export const apiVersion = 1
-export const cliVersion = '0.3.3'
+export const cliVersion = '0.4.0'
 export const mcpLaunch = {
   command: 'npx',
   args: ['-y', '--package', '@utopia-studio-design/design-system-cli', 'utopia-ds', 'mcp'],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@utopia-studio-design/design-system-cli",
-  "version": "0.3.3",
+  "version": "0.4.0",
   "description": "AI-readable CLI and MCP server for Ceramic Design System",
   "type": "module",
   "license": "MIT",