@utopia-studio-design/design-system-cli 0.3.4 → 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

@@ -177,6 +177,13 @@
             "Separator"
           ]
         },
+        {
+          "id": "utilities",
+          "label": "Utilities",
+          "items": [
+            "Phosphor Icon"
+          ]
+        },
         {
           "id": "data",
           "label": "Data Display",
@@ -293,6 +300,7 @@
       "Native Select",
       "Navigation Menu",
       "Pagination",
+      "Phosphor Icon",
       "Popover",
       "Progress",
       "Radio Group",
@@ -373,6 +381,7 @@
       "Native Select",
       "Navigation Menu",
       "Pagination",
+      "Phosphor Icon",
       "Popover",
       "Progress",
       "Radio Group",

package/data/manifests/components.json

@@ -2319,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",
@@ -2330,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",
@@ -2796,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",
@@ -4511,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",
@@ -4525,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.4'
+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.4",
+  "version": "0.4.0",
   "description": "AI-readable CLI and MCP server for Ceramic Design System",
   "type": "module",
   "license": "MIT",