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

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

@@ -7,13 +7,36 @@ import {
   listComponents, listDocs, listMotionProfiles, listTemplates, listThemes, mcpLaunch, repositoryDoctor, search,
 } from '../lib/api.mjs'
 import { createTemplateSubmissionUrl, validateTemplateSubmission } from '../lib/template-submission.mjs'
+import { installCliTelemetry } from '../lib/telemetry.mjs'
 
 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')
+const cliVersion = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version
+let telemetryErrorCode
+
+installCliTelemetry({
+  command,
+  packageVersion: cliVersion,
+  getErrorCode: () => telemetryErrorCode,
+})
+
+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))
@@ -22,6 +45,7 @@ function output(type, data, format = null) {
 }
 
 function fail(message, code = 'ERR_INPUT', suggestions = []) {
+  telemetryErrorCode = code
   if (json) console.error(JSON.stringify({ apiVersion: 1, error: message, code, suggestions }, null, 2))
   else console.error(message)
   process.exitCode = 1
@@ -29,7 +53,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 +180,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 +217,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

@@ -74,6 +74,7 @@ Arabic display sizing should follow the Latin display scale at about 95%, rather
 - Runtime recipes use four engine-neutral intents: `feedback`, `page`, `surface`, and `layout`.
 - Components consume `--motion-duration-*` and `--motion-ease-*` roles rather than hardcoded milliseconds or easing curves.
 - `MotionProvider` sets the theme profile and runtime adapter for a subtree. Motion-aware components expose `motion?: boolean` for a local override.
+- `MotionProvider asChild` applies that policy to exactly one semantic subtree root without adding a wrapper. The consumer root must accept `className`, `style`, `data-*`, and its children.
 - `motion={false}` and `prefers-reduced-motion: reduce` disable decorative movement while preserving state changes and accessibility.
 - Directional motion follows logical inline start/end and mirrors in RTL when direction carries meaning.
 - Icon motion follows the action: a bell swings from its top, download moves downward, and copy snaps once. Do not apply a generic bounce.
@@ -121,9 +122,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/observability.md

@@ -0,0 +1,165 @@
+# Ceramic Observability
+
+Ceramic observability has two explicit modes. It is not a hidden backdoor:
+
+- `operational` starts when a host configures and enables a collector. It
+  records only minimized error diagnostics, uses an in-memory page-session ID,
+  ignores actor/account IDs and custom properties, and does not use telemetry
+  cookies, `sessionStorage`, `localStorage`, usage events, or page-view events.
+  It needs no consent click, but hosts must publish notice, assess their lawful
+  basis, and provide an immediate opt-out.
+- `consented` records the allow-listed usage plan and optional opaque cohorts
+  only after explicit consent.
+
+## Decisions this data supports
+
+- Which Ceramic versions, components, and public composition paths are in use?
+- Which anonymous app/account cohort is encountering a repeated error?
+- Which route, viewport class, locale, direction, and release are affected?
+- Did a CLI command succeed or fail, without collecting its arguments or path?
+- Did a fixed error fingerprint stop recurring after a release?
+
+## Data minimization contract
+
+Consented Ceramic telemetry may collect:
+
+- event name and timestamp;
+- opaque app, account, actor, session, and event IDs;
+- component and operation names;
+- package version and application release;
+- route template supplied by the host;
+- locale, direction, and viewport bucket;
+- stable error code, error class, and non-reversible fingerprint;
+- allow-listed short boolean, numeric, or non-email string properties.
+
+Ceramic does not collect:
+
+- names, email addresses, raw database IDs, or authentication identifiers;
+- DOM, form values, user copy, component props, command arguments, or cwd;
+- error messages or raw stacks;
+- IP addresses in retained records;
+- session replay, screenshots, keystrokes, or network payloads.
+
+Operational mode accepts only `component_error` and `runtime_error`, and removes
+`accountId`, `actorId`, custom properties, and persistent telemetry storage even
+if the host passes them.
+
+In consented mode, pass pre-hashed or otherwise opaque `accountId` and `actorId` values. The SDK
+rejects identifiers with whitespace or email syntax. Route resolvers should
+return route templates such as `/projects/:projectId`, not raw URLs containing
+customer identifiers.
+
+## Start the private collector and dashboard
+
+Create two different random secrets:
+
+```sh
+export CERAMIC_TELEMETRY_INGEST_KEY="$(openssl rand -hex 32)"
+export CERAMIC_TELEMETRY_ADMIN_TOKEN="$(openssl rand -hex 32)"
+export CERAMIC_TELEMETRY_ALLOWED_ORIGINS="http://localhost:5173"
+npm run observability:start
+```
+
+Open `http://127.0.0.1:4318` and enter the admin token. The collector binds to
+loopback by default, retains data for 30 days, and stores newline-delimited JSON
+under `.ceramic/observability/`, which is ignored by Git.
+
+The dashboard shows aggregate event, error, app, opaque actor/account,
+component, release, and fingerprint counts plus the latest sanitized events.
+The admin can export the aggregate response or delete all retained events.
+
+For a shared deployment, place the collector behind TLS, SSO or a private
+network, persistent encrypted storage, rate limiting, and backups appropriate
+to the retention policy. Do not expose the Node reference collector directly
+to the public internet. The admin token must never be put in a `VITE_*`
+variable or browser bundle.
+
+## Configure a React/browser consumer
+
+```tsx
+import {
+  configureCeramicTelemetry,
+  installCeramicGlobalErrorTracking,
+  trackCeramicEvent,
+} from '@utopia-studio-design/design-system/Telemetry'
+
+configureCeramicTelemetry({
+  enabled: diagnosticsPreference !== 'disabled',
+  consent: 'unknown',
+  mode: 'operational',
+  appId: 'renacore-dashboard',
+  endpoint: 'https://observability.example.com',
+  ingestKey: publicWriteOnlyIngestKey,
+  packageVersion: '0.6.0',
+  release: appRelease,
+  routeResolver: () => currentRouteTemplate,
+  sampleRate: 0.1,
+})
+
+const removeGlobalTracking = installCeramicGlobalErrorTracking()
+```
+
+Global error listeners are never installed automatically by the package. The
+host owns notice, lawful-basis assessment, opt-out, route normalization,
+installation, and cleanup. Errors are sampled at 100%. Repeated reports with the same
+fingerprint inside two seconds are deduplicated so a component boundary and a
+global listener do not create duplicate incidents.
+
+Ceramic's validated `asChild` paths report `ERR_COMPOSITION_CHILD` through the
+configured client before throwing their explanatory development error. With no
+configured and enabled client, this call is a no-op.
+
+To enable usage events, obtain separate explicit consent and configure
+`mode: "consented"`, `consent: "granted"`, and any opaque cohort IDs.
+
+## Configure CLI diagnostics
+
+CLI telemetry is also disabled by default and never sends command arguments,
+queries, target directories, generated file names, or cwd.
+
+```sh
+export CERAMIC_TELEMETRY_ENABLED=true
+export CERAMIC_TELEMETRY_MODE=operational
+export CERAMIC_TELEMETRY_ENDPOINT=https://observability.example.com
+export CERAMIC_TELEMETRY_INGEST_KEY=replace-with-write-only-key
+export CERAMIC_TELEMETRY_APP_ID=renacore-dashboard
+npx utopia-ds doctor --json
+```
+
+Operational CLI mode sends failed completion only, without actor/account IDs.
+Consented mode additionally requires `CERAMIC_TELEMETRY_MODE=consented` and
+`CERAMIC_TELEMETRY_CONSENT=granted`, and may send successful completion and
+opaque cohorts. Network failure never changes CLI output or exit status.
+
+## Event plan
+
+| Event | Trigger | Decision fields |
+| --- | --- | --- |
+| `app_started` | Consented SDK initialization | app, release, package version |
+| `component_used` | Explicit host instrumentation | component, operation, route |
+| `component_error` | Ceramic component contract failure | component, operation, error code/fingerprint |
+| `runtime_error` | Explicit boundary/global error capture | route, release, error code/fingerprint |
+| `cli_command_completed` | Operational failure or consented CLI process exit | command, success, version |
+
+## Public notice and controls
+
+The Ceramic documentation site publishes `#/terms` and `#/privacy`. Its privacy
+page includes a browser-level operational-diagnostics opt-out and honors Global
+Privacy Control and Do Not Track. Consumer applications must publish their own
+notice and control because they determine the collector, purpose, retention,
+recipients, and jurisdiction.
+
+## Operations and deletion
+
+- Default retention: 30 days; configure 1–365 days.
+- `GET /health`: unauthenticated liveness only.
+- `POST /v1/events`: write-only ingest-key authentication.
+- `GET /v1/summary`: admin Bearer authentication.
+- `DELETE /v1/events`: admin Bearer authentication and full retained-data deletion.
+- `DELETE /v1/events?actorId=<opaque-id>` or `?accountId=<opaque-id>`:
+  selective deletion for a consent withdrawal or data-subject request.
+- Rotate ingest and admin secrets independently.
+- Treat the ingest key as public/write-only when used in browsers.
+- Treat the admin token as a server-side secret.
+- Publish a privacy notice before enabling identifiable account or actor
+  cohorts in a production consumer.

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:
@@ -42,6 +42,30 @@ export function SaveAction() {
 }
 ```
 
+For navigation, keep the anchor or framework link as the single interactive
+element:
+
+```tsx
+import Link from 'next/link'
+import { Button } from '@utopia-studio-design/design-system/Button'
+
+<Button asChild variant="outline" size="sm">
+  <a href="/docs">Docs</a>
+</Button>
+
+<Button asChild startContent={<FolderIcon />}>
+  <Link href="/settings">Settings</Link>
+</Button>
+```
+
+`asChild` accepts exactly one non-Fragment React element. The child must forward
+`ref`, `className`, events, `children`, and accessibility props to one
+interactive element. Anchor and Link props such as `href`, `target`, and
+`aria-*` are preserved. When `disabled` or `loading` is true, Ceramic does not
+pass the invalid `disabled` attribute to a link: it applies
+`aria-disabled="true"`, `tabIndex={-1}`, and blocks click activation while
+keeping the original `href`.
+
 ## Set Motion Policy
 
 Ceramic maps BeUI-inspired interaction patterns to semantic roles: `press`, `page`, `expand`, `reveal`, and `icon`. Set the application default once and override only when a local workflow needs to be static.
@@ -96,6 +120,14 @@ The MCP server exposes the same API as the CLI. A generated `.mcp.json` uses:
 
 Available tools include search, component/template/theme/doc discovery, and doctor. An MCP client must never receive capabilities that the CLI cannot expose.
 
+## Optional diagnostics
+
+Ceramic telemetry is disabled by default. If a product has an approved
+diagnostics consent flow, configure the write-only SDK and private dashboard
+using `npx utopia-ds docs observability --dense`. Never collect names, emails,
+DOM content, component props, command arguments, filesystem paths, error
+messages, or raw stacks.
+
 ## Agent Decision Loop
 
 1. Run `manifest --json` to discover supported operations.

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

@@ -671,7 +671,7 @@
       "sourcePath": "packages/design-system/src/components/Button.tsx",
       "shadcnFoundation": [
         "button",
-        "Slot",
+        "single-element asChild composition",
         "cva"
       ],
       "fallbackToShadcn": "button",
@@ -709,6 +709,7 @@
         "New button colors",
         "Gradient states",
         "Unlabeled icon-only buttons",
+        "Fragments or multiple root children inside Button asChild",
         "Left/right-only layout rules",
         "Utopia brand primitives inside reusable component logic",
         "Motion that bypasses MotionProvider or prefers-reduced-motion"
@@ -718,7 +719,10 @@
           "motion": "Optional boolean. Defaults to the MotionProvider policy and disables this component pattern when false.",
           "contentAlign": "Use 'start' for leading-aligned labels, 'center' for the default action layout, or 'between' to pin endContent to the logical inline end.",
           "startContent": "Optional leading icon or content slot with package-owned alignment.",
-          "endContent": "Optional trailing content slot. With contentAlign='between', it remains pinned while the label truncates."
+          "endContent": "Optional trailing content slot. With contentAlign='between', it remains pinned while the label truncates.",
+          "asChild": "Use with exactly one non-Fragment anchor or framework Link that forwards ref, className, events, children, and accessibility props to one interactive element. Button preserves the child href, target, aria attributes, className, and ref while composing its internal slots inside that element.",
+          "disabled": "Native buttons receive disabled. With asChild, disabled links keep href, receive aria-disabled=true and tabIndex=-1, and block click activation without receiving a disabled attribute.",
+          "loading": "Shows the spinner/loadingText and sets aria-busy. Native buttons are disabled; asChild links use the same aria-disabled, tabIndex, and activation-blocking contract as disabled."
         }
       }
     },
@@ -776,8 +780,9 @@
           "label",
           "children",
           "ButtonGroupSeparator.orientation",
-          "ButtonGroupText.asChild"
+        "ButtonGroupText.asChild"
         ],
+        "composition": "ButtonGroupText.asChild accepts exactly one text-compatible consumer element and preserves it as the semantic root while applying the group text class and props.",
         "shadcnReferencePatterns": [
           "button group",
           "button group with dropdown menu",
@@ -2319,7 +2324,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 +2336,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 +2809,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 +4583,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 +4598,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."
         }
       }
@@ -4602,6 +4676,7 @@
       "shadcnFoundation": [
         "toggle",
         "Radix Toggle",
+        "Slottable single-button asChild composition",
         "cva"
       ],
       "fallbackToShadcn": "shadcn/ui toggle",
@@ -4628,6 +4703,7 @@
       "neverInvent": [
         "New pressed colors",
         "Checkbox behavior",
+        "Fragments, multiple roots, anchors, or navigation links inside ToggleButton asChild",
         "Left/right-only state names",
         "Utopia brand primitives inside reusable component logic"
       ],
@@ -4642,9 +4718,11 @@
           "isIconOnly",
           "isDisabled",
           "isLoading",
+          "asChild",
           "variant",
           "size"
         ],
+        "composition": "ToggleButton.asChild requires exactly one non-Fragment button-compatible component that forwards ref, className, events, children, disabled, and accessibility props to one button. Ceramic keeps spinner, icon, pressed icon, and label slots inside that root.",
         "arabicFriendly": [
           "Use logical start/end language for labels and adjacent content.",
           "In RTL, keep persistent pressed state behavior identical; only directional layout and directional icons may mirror.",

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/lib/telemetry.mjs

@@ -0,0 +1,74 @@
+function safeId(value) {
+  return typeof value === 'string' && /^[a-zA-Z0-9][a-zA-Z0-9._:-]{0,127}$/.test(value)
+    ? value
+    : undefined
+}
+
+function randomId() {
+  return globalThis.crypto?.randomUUID?.() ?? `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 14)}`
+}
+
+const SAFE_COMMANDS = new Set([
+  'component',
+  'doctor',
+  'docs',
+  'help',
+  'init',
+  'manifest',
+  'motion',
+  'search',
+  'template',
+  'theme',
+])
+
+export function installCliTelemetry({ command, packageVersion, getErrorCode }) {
+  const endpoint = process.env.CERAMIC_TELEMETRY_ENDPOINT?.replace(/\/$/, '')
+  const ingestKey = process.env.CERAMIC_TELEMETRY_INGEST_KEY
+  const appId = safeId(process.env.CERAMIC_TELEMETRY_APP_ID)
+  const consented = process.env.CERAMIC_TELEMETRY_MODE === 'consented'
+    && process.env.CERAMIC_TELEMETRY_CONSENT === 'granted'
+  const enabled = process.env.CERAMIC_TELEMETRY_ENABLED === 'true'
+    && endpoint
+    && ingestKey
+    && appId
+    && command !== 'mcp'
+  if (!enabled) return
+
+  let sent = false
+  process.on('beforeExit', async () => {
+    if (sent) return
+    sent = true
+    const errorCode = getErrorCode()
+    const success = !errorCode && (process.exitCode ?? 0) === 0
+    if (!consented && success) return
+    const event = {
+      schemaVersion: 1,
+      id: randomId(),
+      occurredAt: new Date().toISOString(),
+      name: 'cli_command_completed',
+      appId,
+      source: 'cli',
+      sessionId: randomId(),
+      accountId: consented ? safeId(process.env.CERAMIC_TELEMETRY_ACCOUNT_ID) : undefined,
+      actorId: consented ? safeId(process.env.CERAMIC_TELEMETRY_ACTOR_ID) : undefined,
+      errorCode,
+      operation: SAFE_COMMANDS.has(command) ? command : 'unknown',
+      packageVersion,
+      release: process.env.CERAMIC_RELEASE?.slice(0, 128),
+      properties: consented ? { success } : undefined,
+    }
+    try {
+      await fetch(`${endpoint}/v1/events`, {
+        method: 'POST',
+        headers: {
+          'content-type': 'application/json',
+          'x-ceramic-ingest-key': ingestKey,
+        },
+        body: JSON.stringify(event),
+        signal: AbortSignal.timeout(750),
+      })
+    } catch {
+      // Telemetry is best effort and must never change CLI behavior.
+    }
+  })
+}

package/package.json

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