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

package/data/docs/guide.md

@@ -23,6 +23,70 @@ Guide pages are the operating layer of Ceramic. They define how humans and AI ag
 - Guide pages must not put Utopia Default visual philosophy into reusable core rules.
 - Guide pages must link AI agents back to manifests, package exports, foundations, and Arabic-friendly rules.
 
+## Navigation Composition
+
+Ceramic owns the visual primitives for standard product navigation. Consumers provide route labels and destinations, while the design system provides icons, collapsed behavior, tooltips, current-state treatment, and surface-aware Breadcrumb colors.
+
+```tsx
+import {
+  Breadcrumb,
+  BreadcrumbItem,
+  BreadcrumbLink,
+  BreadcrumbList,
+  BreadcrumbPage,
+  BreadcrumbSeparator,
+  NavigationIcon,
+  PanelIcon,
+  SideNavCollapseButton,
+} from '@utopia-studio-design/design-system/Navigation'
+import {
+  SidebarMenuButton,
+  SidebarMenuItem,
+} from '@utopia-studio-design/design-system/Sidebar'
+
+<SideNavCollapseButton aria-expanded={!collapsed} aria-label="Collapse navigation">
+  <PanelIcon />
+</SideNavCollapseButton>
+
+<SidebarMenuItem>
+  <SidebarMenuButton activeVariant="both" isActive tooltip="Projects">
+    <NavigationIcon name="projects" />
+    <span>Projects</span>
+  </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>
+        <BreadcrumbPage>Co-Build Hub</BreadcrumbPage>
+      </BreadcrumbItem>
+    </BreadcrumbList>
+  </Breadcrumb>
+</div>
+```
+
+- Use `NavigationIcon` instead of an app-owned icon package or raw SVG for standard destinations.
+- Keep `tooltip` on collapsed Sidebar items; it also supplies an accessible name when no explicit `aria-label` is provided.
+- 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
 
 Before generating UI, read:

package/data/manifests/components.json

@@ -481,9 +481,17 @@
         "--foreground",
         "--muted-foreground",
         "--foreground-subtle",
+        "--inverse-foreground",
+        "--inverse-foreground-muted",
+        "--inverse-foreground-subtle",
+        "--inverse-hover",
+        "--inverse-focus-ring",
         "--surface-hover",
         "--radius-control",
         "--space-2",
+        "--font-size-small",
+        "--line-height-supporting",
+        "--icon-size-xs",
         "--control-height-sm",
         "--duration-fast",
         "--ease-standard",
@@ -493,7 +501,8 @@
       "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"
+        "A long path may need collapsed middle items or an overflow menu",
+        "A top bar on --surface-inverse needs Ceramic-owned link, separator, current-page, hover, and focus colors"
       ],
       "avoidWhen": [
         "Primary navigation is needed; use Top Nav, Side Nav, or Navigation Menu",
@@ -508,14 +517,21 @@
       "ai": {
         "props": {
           "aria-label": "Required localized label for the breadcrumb navigation landmark.",
+          "variant": "Use default for ordinary surfaces and inverse when the Breadcrumb is placed on --surface-inverse.",
           "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."
       }
     },
@@ -559,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."
       }
@@ -3624,7 +3640,7 @@
       "name": "Side Nav",
       "category": "Navigation",
       "status": "available",
-      "packageImport": "import { PanelIcon, SideNav, SideNavAccount, SideNavAuxiliary, SideNavCollapseButton, SideNavCommand, SideNavContent, SideNavFooter, SideNavHeader, SideNavHeading, SideNavItem, SideNavMain, SideNavNestedGroup, SideNavNestedItems, SideNavSearch, SideNavSection, SideNavStatus, SideNavWorkspaceSwitcher } from '@utopia-studio-design/design-system/Navigation';",
+      "packageImport": "import { NavigationIcon, PanelIcon, SideNav, SideNavAccount, SideNavAuxiliary, SideNavCollapseButton, SideNavCommand, SideNavContent, SideNavFooter, SideNavHeader, SideNavHeading, SideNavItem, SideNavMain, SideNavNestedGroup, SideNavNestedItems, SideNavSearch, SideNavSection, SideNavStatus, SideNavWorkspaceSwitcher } from '@utopia-studio-design/design-system/Navigation';",
       "sourcePath": "packages/design-system/src/components/Navigation.tsx",
       "shadcnFoundation": [
         "sidebar",
@@ -3683,6 +3699,7 @@
           "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.",
+          "NavigationIcon": "Official Ceramic destination icon set. Use names such as dashboard, projects, tasks, inbox, files, analytics, team, settings, and help without importing an app icon package.",
           "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."
@@ -3948,6 +3965,8 @@
         "--foreground",
         "--border",
         "--surface-hover",
+        "--primary",
+        "--font-size-supporting",
         "--popover-surface",
         "--radius-control",
         "--radius-surface",
@@ -3997,6 +4016,11 @@
           "SidebarTrigger",
           "useSidebar"
         ],
+        "props": {
+          "SidebarMenuButton.activeVariant": "Use background for backward compatibility, indicator for a logical inline-start current marker, or both for the marker plus background.",
+          "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."
       }
     },

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.3'
 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.1",
+  "version": "0.3.3",
   "description": "AI-readable CLI and MCP server for Ceramic Design System",
   "type": "module",
   "license": "MIT",