@utopia-studio-design/design-system-cli 0.3.2 → 0.3.4

package/data/docs/guide.md

@@ -55,12 +55,24 @@ import {
   </SidebarMenuButton>
 </SidebarMenuItem>
 
+<Breadcrumb aria-label="Current location">
+  <BreadcrumbList>
+    <BreadcrumbItem>
+      <BreadcrumbLink href="/dashboard">Dashboard</BreadcrumbLink>
+    </BreadcrumbItem>
+    <BreadcrumbSeparator />
+    <BreadcrumbItem>
+      <BreadcrumbPage>Sessions</BreadcrumbPage>
+    </BreadcrumbItem>
+  </BreadcrumbList>
+</Breadcrumb>
+
 <div style={{ background: 'var(--surface-inverse)' }}>
   <Breadcrumb aria-label="Current location" variant="inverse">
     <BreadcrumbList>
-      <BreadcrumbItem><BreadcrumbLink href="/">Home</BreadcrumbLink></BreadcrumbItem>
-      <BreadcrumbSeparator />
-      <BreadcrumbItem><BreadcrumbPage>Projects</BreadcrumbPage></BreadcrumbItem>
+      <BreadcrumbItem>
+        <BreadcrumbPage>Co-Build Hub</BreadcrumbPage>
+      </BreadcrumbItem>
     </BreadcrumbList>
   </Breadcrumb>
 </div>
@@ -71,6 +83,9 @@ import {
 - Use `activeVariant="indicator"` or `"both"` when current navigation needs the logical inline-start accent. The default `"background"` variant remains backward compatible.
 - `isActive` supplies `aria-current="page"` unless the consumer explicitly provides another valid value.
 - Use `Breadcrumb variant="inverse"` on `--surface-inverse`; do not remap `--foreground` or add component selectors in the consuming app.
+- Compose separators only between path items. Never render a separator before the first item.
+- `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.
 
 ## AI Rule
 

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",
@@ -249,6 +252,7 @@
       "Card",
       "Carousel",
       "Chart",
+      "Assistant Panel",
       "Chat Composer",
       "Chat Composer Drawer",
       "Chat Composer Input",
@@ -307,6 +311,7 @@
       "Textarea",
       "Toggle Button",
       "Toggle Button Group",
+      "Tool Connector Block",
       "Tooltip",
       "Typography",
       "Utopia Wordmark Loader"
@@ -327,6 +332,7 @@
       "Card",
       "Carousel",
       "Chart",
+      "Assistant Panel",
       "Chat Composer",
       "Chat Composer Drawer",
       "Chat Composer Input",
@@ -385,6 +391,7 @@
       "Textarea",
       "Toggle Button",
       "Toggle Button Group",
+      "Tool Connector Block",
       "Tooltip",
       "Typography",
       "Utopia Wordmark Loader"

package/data/manifests/components.json

@@ -489,6 +489,9 @@
         "--surface-hover",
         "--radius-control",
         "--space-2",
+        "--font-size-small",
+        "--line-height-supporting",
+        "--icon-size-xs",
         "--control-height-sm",
         "--duration-fast",
         "--ease-standard",
@@ -518,11 +521,17 @@
           "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.",
+          "BreadcrumbLink": "Clickable ancestor link with no underline, including when a consumer applies a global anchor underline. 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.",
+          "BreadcrumbSeparator": "Visual separator with an aria-hidden Lucide ChevronRight by default. It mirrors automatically in RTL.",
           "BreadcrumbEllipsis": "Collapsed middle path indicator. Pair with a menu when hidden parents need discovery."
         },
+        "rules": [
+          "Compose BreadcrumbSeparator only between items, never before the first item.",
+          "Do not add a home icon unless the product explicitly supplies one as item content.",
+          "Default Breadcrumb hover changes foreground only; inverse hover may use the inverse surface hover role.",
+          "Use the compact typography and alignment supplied by Ceramic instead of product CSS overrides."
+        ],
         "arabicFriendly": "Breadcrumb order, separator spacing, dropdown alignment, and focus rings must follow dir=\"rtl\" using logical properties. Arabic labels must come from localization."
       }
     },
@@ -566,7 +575,7 @@
           "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."
+          "BreadcrumbSeparator": "Visual hierarchy separator with an aria-hidden Lucide ChevronRight by default. Keep spacing logical; it mirrors automatically 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."
       }
@@ -1006,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",
@@ -1067,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",
@@ -4015,6 +4184,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",

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.1'
+export const cliVersion = '0.3.4'
 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.2",
+  "version": "0.3.4",
   "description": "AI-readable CLI and MCP server for Ceramic Design System",
   "type": "module",
   "license": "MIT",