@moldable-ai/ui 0.2.20 → 0.2.22

package/docs/adaptive-materials.md

@@ -0,0 +1,79 @@
+# Adaptive materials
+
+Moldable uses restrained translucent material to separate controls and
+navigation from the content they operate on. Material frames content; it does
+not replace content surfaces.
+
+## Roles
+
+Use `regular` material for normal toolbar and window chrome, grouped controls,
+menus, and temporary control overlays. It provides enough frosting for text
+and icons to remain stable as content moves behind it.
+
+Use `clear` material only for compact controls floating over photos, maps,
+video, or another richly colored canvas. Check the control against the
+lightest, darkest, and busiest content it can cover. If contrast is not stable,
+use `regular`.
+
+Documents, calendars, tables, forms, cards, sheets, inspectors, and primary
+working canvases remain opaque. Do not stack translucent content cards to
+create hierarchy.
+
+## Components
+
+`Material` applies one adaptive surface:
+
+```tsx
+<Material asChild variant="clear" shape="circle" interactive>
+  <IconButton label="Center map" variant="ghost">
+    <Locate />
+  </IconButton>
+</Material>
+```
+
+`MaterialGroup` applies one sampled layer to a related cluster:
+
+```tsx
+<MaterialGroup variant="regular" shape="capsule" spacing="compact">
+  <IconButton label="Previous" variant="ghost">
+    <ChevronLeft />
+  </IconButton>
+  <IconButton label="Next" variant="ghost">
+    <ChevronRight />
+  </IconButton>
+</MaterialGroup>
+```
+
+Children of a `MaterialGroup` should be ordinary transparent or ghost
+controls. Do not apply another `Material` to every child. A single grouped
+sampler produces clearer hierarchy and avoids accumulated blur.
+
+`Toolbar`, `AppFrameTitlebar`, and `AppFrameStatusbar` expose a `material`
+property. Their normal chrome uses `regular`; pass `material="none"` for an
+opaque or transparent composition that supplies its own surface.
+
+## Fallback behavior
+
+Every material starts from an opaque fallback. Translucent sampling is enabled
+only when the renderer supports backdrop filtering.
+
+- Reduced transparency uses opaque fills and removes blur and saturation.
+- Increased contrast makes fills more opaque and strengthens borders.
+- Forced colors use system surfaces and borders without blur or shadows.
+- Reduced motion removes material press transforms.
+
+The manual `data-transparency="reduced"`, `data-contrast="increased"`, and
+`data-motion="reduced"` attributes mirror system preferences for deterministic
+catalog and app testing.
+
+Do not animate blur, saturation, or backdrop filters. They are expensive,
+visually noisy, and difficult to make accessible. Limit the number of visible
+sampled layers and avoid nesting them.
+
+## Host boundary
+
+CSS material samples content inside the app renderer. It cannot sample the
+desktop behind a native window. Native behind-window material, window
+transparency, active-window appearance, and energy policy remain host-owned
+capabilities. Apps should use the same semantic variants regardless of which
+adapter renders them.

package/docs/app-anatomy.md

@@ -9,7 +9,9 @@ canvas independent of the desktop shell.
 ```tsx
 <AppFrame>
   <AppFrameTitlebar>
-    <AppFrameToolbar>{/* title, view controls, primary actions */}</AppFrameToolbar>
+    <AppFrameToolbar>
+      {/* title, view controls, primary actions */}
+    </AppFrameToolbar>
   </AppFrameTitlebar>
   <AppFrameContent scrollable={false}>
     {/* app-owned canvas and panes */}

package/docs/component-catalog.md

@@ -20,6 +20,7 @@ const manifest = createCatalogManifest({
         {
           id: 'primary-action',
           title: 'Primary action',
+          components: ['button'],
           interactions: ['rest', 'focus-visible', 'disabled', 'loading'],
           render: ({ interaction }) => (
             <Button
@@ -45,6 +46,8 @@ Every public interactive component should cover:
 - light and dark themes;
 - regular and compact density;
 - wide and narrow viewports;
+- standard accessibility behavior plus reduced transparency, increased
+  contrast, and reduced motion where material or motion is part of the recipe;
 - rest, focus-visible, disabled, invalid, selected, loading, and empty states
   where those states apply;
 - keyboard behavior in unit tests.
@@ -54,6 +57,26 @@ lets a visual-regression runner capture one addressable case at a time. Keep
 catalog stories deterministic: fixed content, fixed dates, no network calls,
 and no animation unless motion itself is under review.
 
-The included `coreComponentCatalog` is a smoke foundation, not the complete
-acceptance bar. Add each new public component and its meaningful states as part
-of the same change that adds the component.
+Accessibility environments are opt-in per story through
+`accessibilityModes`. Standard cases preserve the existing case ID; a
+nonstandard mode is appended as the final segment. The catalog maps those
+modes to deterministic `data-transparency`, `data-contrast`, and `data-motion`
+attributes.
+
+## Public component accountability
+
+Every story declares the public visual component modules it exercises through
+`components`. The core catalog test reads the barrel exports from
+`components/ui/index.ts` and requires every module to be either:
+
+- named by at least one deterministic story; or
+- listed in `coreCatalogExclusions` with a concise reason.
+
+Exclusions are visible debt, not permanent exemptions. Remove an exclusion in
+the same change that adds representative stories. Unknown component ids, stale
+exclusions, duplicate exclusions, and empty reasons fail the catalog test.
+
+The core catalog covers window materials, semantic controls, collections,
+navigation, representative popover material, and feedback recipes. Complex
+portals and geometry-dependent components remain explicitly deferred until an
+isolated browser fixture can make their states deterministic.

package/docs/design-tokens.md

@@ -119,15 +119,28 @@ related objects visually consistent. `rounded-window` is host-informed and
 normally only useful in previews; the native host owns the actual window
 shape.
 
-Material tokens keep depth and translucency restrained:
+Adaptive material has two semantic variants. Each includes fill, fallback,
+border, highlight, blur, and saturation tokens:
 
-- `--material-blur-toolbar` and `--material-blur-overlay`
-- `--material-saturation`
-- `shadow-panel`, `shadow-overlay`, and `shadow-window`
+- `--material-regular-*` supports normal toolbar and control chrome.
+- `--material-clear-*` supports compact controls over media or a richly
+  colored canvas.
+- `shadow-panel`, `shadow-overlay`, and `shadow-window` provide elevation
+  independently from translucency.
+
+Use `Material` and `MaterialGroup` instead of assembling those tokens in app
+markup. `MaterialGroup` owns one sampled layer for a related control cluster;
+its children must not add nested material.
 
 Translucency must have an opaque fallback. The token system removes blur and
 uses opaque toolbar and overlay surfaces when the operating system requests
 reduced transparency or an ancestor has `data-transparency="reduced"`.
+Unsupported renderers stay on the same opaque fallback. Increased contrast
+makes fills more opaque and strengthens their borders.
+
+Material is a control and navigation affordance. Primary canvases, documents,
+tables, calendars, forms, cards, sheets, and inspectors remain opaque. See
+[Adaptive materials](./adaptive-materials.md) for composition rules.
 
 ## Motion
 

package/docs/foundations.md

@@ -37,9 +37,11 @@ Status color communicates status only; it is not decoration.
 Use semantic tokens only. Do not introduce raw gray, zinc, white, or black
 classes in app UI.
 
-Use material tokens for translucency and elevation. Materials distinguish
-canvas, toolbar, sidebar, raised, recessed, and overlay roles; they are not
-decorative glass effects.
+Use adaptive material only for navigation and control layers. Regular material
+supports toolbars and grouped controls; clear material is reserved for compact
+controls over media. Content canvases and content-bearing surfaces stay
+opaque. Group related controls under one sampler and never nest material
+effects.
 
 ## Motion
 

package/docs/standalone-app-windows.md

@@ -41,6 +41,14 @@ the document root. Composite content insets then resolve automatically. The
 transport used to deliver those values belongs to the host integration layer,
 not individual apps.
 
+Dedicated windows use the host titlebar by default. An app with a unified
+toolbar can declare `{ "window": { "titlebar": "app" } }` in `moldable.json`.
+In that mode the host removes its strip and advertises the titlebar height and
+leading window-control inset. `AppFrameTitlebar` consumes those values, sends
+`startWindowDrag` on a non-interactive pointerdown, and sends
+`titlebarDoubleClick` on a non-interactive double-click. The latter toggles
+maximize as a cross-platform approximation of the macOS titlebar zoom action.
+
 Window appearance roles are `--window-chrome-background`,
 `--window-chrome-foreground`, `--window-chrome-muted-foreground`,
 `--window-border`, and `--material-shadow-window`. The host may update the

package/docs/visual-regression.md

@@ -0,0 +1,78 @@
+# Visual and accessibility regression
+
+The phase 1 runner exercises every authored story in the core component
+catalog. It does not start the desktop shell or any Moldable-managed app.
+
+## What runs
+
+`visual-host/` is a small Vite entry that renders one story at a time:
+
+```text
+?story=controls/button&theme=dark&width=360
+```
+
+Unique bare story ids are also accepted. Optional
+`transparency=reduced` and `contrast=increased` parameters set the same
+manual accessibility attributes used by the catalog. The host bundles Inter
+and Roboto Mono, waits for `document.fonts.ready`, and disables animations,
+transitions, scrolling, and the caret under `data-motion="reduced"`.
+
+The Playwright runner builds and serves that static host, blocks non-host
+network requests, freezes time and randomness, and tests Chromium at:
+
+- light and dark themes;
+- 360 × 720 and 960 × 720 viewports;
+- rest plus the browser-driven states declared by an exemplar story.
+
+A story opts into browser-driven states with `liveStates` and marks exactly
+one element:
+
+```tsx
+<Button data-state-target="hover focus pressed">Continue</Button>
+```
+
+Playwright performs real hover, focus, and held-pointer interactions on that
+element. Button, segmented control, and toggle stories are the phase 1
+exemplars.
+
+Every captured case also receives an axe WCAG 2 A/AA and WCAG 2.1 A/AA scan.
+Serious and critical violations fail. Per-story suppressions belong in
+`visual-tests/visual-matrix.ts` and must include a reason. Global
+suppressions are intentionally unsupported.
+
+## Local commands
+
+Install the pinned Chromium build once:
+
+```bash
+pnpm -C packages/ui exec playwright install chromium
+```
+
+Run against committed baselines:
+
+```bash
+pnpm -C packages/ui test:visual
+```
+
+Create or intentionally update baselines after reviewing the UI change:
+
+```bash
+pnpm -C packages/ui test:visual:update
+```
+
+Baseline PNGs live in `visual-tests/baselines/`. Failures emit actual,
+expected, diff, and trace artifacts in the gitignored `.visual-results/`
+directory.
+
+## Determinism and skips
+
+Stories must use fixed inputs and no live data, network, wall-clock timers, or
+unseeded randomness. Add an unavoidable phase 1 skip to
+`deterministicStorySkips` in `visual-tests/visual-matrix.ts` with a specific
+reason. Skips are reported in the runner summary; silent conditional skips
+are not allowed.
+
+## CI
+
+The `ui-regression` CI job installs Chromium and its Linux dependencies,
+builds only `@moldable-ai/ui`, then runs the combined visual and axe suite.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@moldable-ai/ui",
-  "version": "0.2.20",
+  "version": "0.2.22",
   "description": "Shared UI components for Moldable applications",
   "author": "Desiderata LLC",
   "license": "SEE LICENSE IN LICENSE",
@@ -42,11 +42,15 @@
   ],
   "scripts": {
     "build": "tsc",
+    "build:visual-host": "vite build --config vite.visual.config.ts",
     "dev": "tsc --watch",
     "lint": "eslint . --ext .ts,.tsx --max-warnings 0",
     "format": "prettier --write . --ignore-path ../../.prettierignore",
-    "check-types": "tsc --noEmit",
-    "test": "vitest run"
+    "check-types": "tsc --noEmit && tsc --noEmit -p tsconfig.visual.json",
+    "test": "vitest run",
+    "test:visual": "pnpm build:visual-host && playwright test --config playwright.visual.config.ts",
+    "test:visual:update": "pnpm build:visual-host && playwright test --config playwright.visual.config.ts --update-snapshots",
+    "visual:serve": "vite preview --config vite.visual.config.ts --host 127.0.0.1 --port 4179 --strictPort"
   },
   "dependencies": {
     "@base-ui/react": "^1.1.0",
@@ -80,7 +84,6 @@
     "@radix-ui/react-toggle": "^1.1.10",
     "@radix-ui/react-toggle-group": "^1.1.11",
     "@radix-ui/react-tooltip": "^1.2.8",
-    "@shadcn/react": "^0.2.1",
     "@tailwindcss/typography": "^0.5.16",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
@@ -106,14 +109,19 @@
     "zod": "^4.3.5"
   },
   "devDependencies": {
+    "@axe-core/playwright": "^4.12.1",
+    "@fontsource/inter": "^5.3.0",
+    "@fontsource/roboto-mono": "^5.3.0",
     "@moldable-ai/eslint-config": "workspace:*",
     "@moldable-ai/prettier-config": "workspace:*",
     "@moldable-ai/typescript-config": "workspace:*",
+    "@playwright/test": "^1.62.0",
     "@types/node": "^24.0.3",
     "@types/react": "^19.1.6",
     "@types/react-dom": "^19.1.6",
     "jsdom": "^26.1.0",
     "typescript": "^5.8.3",
+    "vite": "^6.4.3",
     "vitest": "^4.1.8"
   },
   "peerDependencies": {

package/src/components/ui/alert-dialog.md

@@ -0,0 +1,58 @@
+# Alert Dialog and Confirm Dialog
+
+Use `AlertDialog` when the user must acknowledge a consequential choice. Use the
+composed anatomy for custom content and `ConfirmDialog` for the common
+promise-aware confirmation path.
+
+```tsx
+<ConfirmDialog
+  trigger={<Button variant="destructive">Delete recording</Button>}
+  title="Delete recording?"
+  description="This removes the local audio and transcript."
+  confirmLabel="Delete"
+  pendingLabel="Deleting…"
+  variant="destructive"
+  onConfirm={() => deleteRecording()}
+/>
+```
+
+`ConfirmDialog` prevents duplicate submission, disables cancellation while the
+operation is pending, closes only after success, and keeps failures in the
+dialog. Pass `getErrorMessage` when a safe, actionable domain error can be
+shown. The default error deliberately avoids exposing internal details.
+
+`AlertDialogContent` supports `sm`, `default`, and `lg` and stays within the
+host safe area. Use `AlertDialogBody` when explanation or affected-item content
+can grow. Keep the consequence visible while the action is pending.
+
+For composed alert dialogs, put `loading` on `AlertDialogAction` while its
+request is in flight. This forwards the standard `Button` busy state, blocks
+duplicate activation, and preserves the action label width and accessible name.
+Use `pending` with `pendingLabel` when maintaining the confirmation-specific
+status-label pattern; `ConfirmDialog` manages that state automatically. Disable
+the surrounding form only when its other controls must not change during the
+request.
+
+Mark one confirming action with `primary` to enable Command+Enter on macOS or
+Control+Enter on other platforms. The shortcut does not run without a marked
+action, while that action is loading or disabled, during key composition or
+repeat, or when a focused control consumes the event with `preventDefault()`.
+Plain Enter remains native and Escape remains the Radix cancel behavior.
+
+```tsx
+<AlertDialogFooter>
+  <span className="text-muted-foreground mr-auto inline-flex items-center gap-1 text-xs">
+    Confirm <Kbd>⌘</Kbd>
+    <Kbd>Enter</Kbd>
+  </span>
+  <AlertDialogCancel>Cancel</AlertDialogCancel>
+  <AlertDialogAction primary loading={isDeleting}>
+    Delete recording
+  </AlertDialogAction>
+</AlertDialogFooter>
+```
+
+Use concrete labels such as “Delete recording,” not “OK.” Put the safe,
+reversible action first in keyboard order and the confirming action last. Do
+not use an alert dialog for ordinary navigation, long forms, or success
+messages.

package/src/components/ui/alert.md

@@ -2,7 +2,9 @@
 
 ## Purpose
 
-`Alert` presents an important inline message that belongs to the current surface. Use it for recoverable errors, permission or connection problems, and information the user should notice before continuing.
+`Alert` presents a persistent inline callout that belongs to the current
+surface. Use it for recoverable errors, permission or connection problems, and
+information the user should notice before continuing.
 
 Use `AlertDialog` when the user must confirm an action. Use `Empty` for the normal absence of data. Use a toast for brief feedback that does not need to remain in the layout.
 
@@ -12,23 +14,42 @@ Use `AlertDialog` when the user must confirm an action. Use `Empty` for the norm
 import { CircleAlert } from 'lucide-react'
 import { Alert, AlertDescription, AlertTitle } from '@moldable-ai/ui'
 
-;<Alert variant="destructive">
+;<Alert tone="danger">
   <CircleAlert />
   <AlertTitle>Could not save</AlertTitle>
   <AlertDescription>
     The file changed on disk. Reload it, then try again.
   </AlertDescription>
+  <AlertActions>
+    <Button size="sm">Reload</Button>
+  </AlertActions>
 </Alert>
 ```
 
-An alert can include a compact retry or setup action in its description, but the message should still stand on its own. Place the action close to the cause rather than at the top of the whole app.
+Dismissible informational callouts may use `AlertDismiss`. Dismissal state is
+owned by the caller:
+
+```tsx
+<Alert tone="info">
+  <InfoIcon />
+  <AlertTitle>Local-only data</AlertTitle>
+  <AlertDescription>This workspace has not been synced.</AlertDescription>
+  <AlertDismiss label="Dismiss local-only notice" onClick={dismiss} />
+</Alert>
+```
 
 ## API summary
 
-- `Alert`: a `div` with `role="alert"`.
-- `variant`: `default` or `destructive`; defaults to `default`.
+- `tone`: `neutral`, `info`, `success`, `warning`, or `danger`.
+- `density`: `compact` or `default`.
+- Neutral through warning tones default to `role="status"`; danger defaults to
+  `role="alert"`. The native `role` prop can override that choice.
+- `variant="default"` and `variant="destructive"` remain compatibility aliases.
 - `AlertTitle`: the short, emphasized heading.
 - `AlertDescription`: muted supporting content; supports nested paragraphs and controls.
+- `AlertActions`: a compact action row.
+- `AlertDismiss`: an icon action with a required accessible `label`; the caller
+  owns dismissal.
 - All parts accept the native props for their rendered element and a `className`.
 - A direct icon child on `Alert` receives the component’s grid placement and sizing.
 
@@ -44,9 +65,10 @@ An alert can include a compact retry or setup action in its description, but the
 
 - Do not use an alert as decorative introductory copy.
 - Do not show stack traces, raw exceptions, or secret values.
-- Do not use `destructive` for neutral notices.
+- Do not use `danger` for neutral notices.
 - Do not rely on the icon or color alone for meaning.
 - Do not use `Alert` as a confirmation surface.
+- Do not use an alert for brief success feedback that should be a toast.
 
 ## Moldable considerations
 

package/src/components/ui/app-frame.md

@@ -21,6 +21,9 @@ surface.
 - Let the host render real window controls. Never draw imitation traffic lights.
 - Make the app's primary canvas the visual focus; titlebars and status bars are
   supporting structure.
+- Titlebars and status bars use `material="regular"` by default. Use
+  `material="clear"` only when compact chrome overlays a rich canvas, or
+  `material="none"` when the composition supplies an opaque surface.
 - The app frame does not make the outer window draggable. A decorated native
   titlebar or host-owned drag region must provide that behavior.
 - The host owns the `--window-*` inset variables. The component only consumes
@@ -31,3 +34,5 @@ surface.
   tests. Runtime apps should normally use `mode="auto"`; a future host context
   may set `data-moldable-display-mode` before render when a window still uses an
   app iframe.
+- Material samples only renderer content. Native behind-window material remains
+  host-owned.

package/src/components/ui/button.md

@@ -25,9 +25,15 @@ import { RefreshCw } from 'lucide-react'
 >
   <RefreshCw />
 </Button>
+
+<Button type="submit" loading={isSaving}>
+  Save changes
+</Button>
 ```
 
-Keep toolbar actions compact (`xs`, `sm`, `icon-xs`, or `icon-sm`). Reserve `default` or `lg` for the primary action in a form, setup state, or focused control dock. While an async action is running, disable the button, preserve its width, and show a small spinner beside a short status label.
+Keep toolbar actions compact (`xs`, `sm`, `icon-xs`, or `icon-sm`). Reserve `default` or `lg` for the primary action in a form, setup state, or focused control dock. Set `loading` while that button's async action is in flight. The button blocks pointer and keyboard activation, exposes `aria-busy`, keeps its accessible label mounted, and centers a width-stable spinner.
+
+Use `loading` for the action that started the request. Disable the whole form only when editing during the request would be unsafe or would invalidate the submitted payload; do not disable unrelated controls merely to communicate progress.
 
 For links that should look like buttons:
 
@@ -42,13 +48,14 @@ For links that should look like buttons:
 - `variant`: `default`, `destructive`, `outline`, `secondary`, `ghost`, or `link`. Defaults to `default`.
 - `size`: `default`, `xs`, `sm`, `lg`, `icon`, `icon-xs`, `icon-sm`, or `icon-lg`. Defaults to `default`.
 - `asChild`: renders a Radix `Slot` so the child owns the element and semantics.
+- `loading`: blocks activation, applies disabled behavior and `aria-busy`, and overlays the shared `Spinner` without unmounting or resizing the label. Defaults to `false`.
 - Accepts native button props, including `type`, `disabled`, `aria-*`, and event handlers.
 - `buttonVariants` is exported for cases that need the same visual treatment on another component.
 
 ## Do
 
 - Set `type="button"` unless the control intentionally submits a form.
-- Add `cursor-pointer`; use the real `disabled` attribute for unavailable or busy actions.
+- Add `cursor-pointer`; use the real `disabled` attribute for unavailable actions and `loading` for an in-flight action.
 - Give icon-only buttons an `aria-label` and a tooltip.
 - Use a specific Lucide icon that names the action.
 - Put one visually primary action in a local action group.
@@ -60,7 +67,7 @@ For links that should look like buttons:
 - Do not rely on color alone to explain a destructive or selected action.
 - Do not use raw color classes, decorative gradients, or oversized call-to-action styling.
 - Do not use `Sparkles` as a generic AI marker.
-- Do not leave a busy button clickable or allow repeated submission.
+- Do not use `disabled` alone as the progress signal; use `loading` so progress is announced and the label width stays stable.
 - Do not hide essential actions behind hover-only icon buttons.
 
 ## Moldable considerations

package/src/components/ui/collapsible.md

@@ -0,0 +1,52 @@
+# Collapsible
+
+`Collapsible` exposes the unstyled Radix disclosure primitive.
+`CollapsibleSection` adds a consistent section trigger, state-aware chevron,
+border, and content spacing.
+
+```tsx
+<CollapsibleSection defaultOpen>
+  <CollapsibleSectionTrigger>Advanced options</CollapsibleSectionTrigger>
+  <CollapsibleSectionContent>
+    Controls that are useful less often.
+  </CollapsibleSectionContent>
+</CollapsibleSection>
+```
+
+## When to use
+
+Use a collapsible section for one independently disclosed region. Use
+`Accordion` when several peer sections need coordinated one-at-a-time or
+multi-section behavior.
+
+## API
+
+The base `Collapsible`, `CollapsibleTrigger`, and `CollapsibleContent` expose
+the Radix props directly.
+
+The section helpers add:
+
+- `CollapsibleSection`: bordered section root.
+- `CollapsibleSectionTrigger`: full-width trigger with a chevron driven by the
+  root `data-state`.
+- `CollapsibleSectionContent`: standard inset content.
+- `motion`: `default` or `none`.
+- `contentClassName`: styles the inset inner content without changing the
+  animated viewport.
+
+## Keyboard and accessibility
+
+The trigger is a button with `aria-expanded` and `aria-controls` managed by
+Radix. Space and Enter toggle it. The chevron is decorative.
+
+## Motion
+
+Motion is brief and uses the shared reduced-motion behavior. Set
+`motion="none"` for content where movement would distract or when a parent owns
+the transition.
+
+## Don't
+
+- Do not put another interactive control inside the trigger.
+- Do not hide required validation errors or primary actions by default.
+- Do not use a disclosure solely to make a sparse layout look busier.

package/src/components/ui/combobox.md

@@ -40,4 +40,3 @@ state, clear/trigger controls, and the chips family for multi-value input.
 - Label the input visibly or with an accessible name.
 - Do not deep-import the implementation; `Combobox` is exported from the
   package root.
-

package/src/components/ui/command.md

@@ -0,0 +1,54 @@
+# Command
+
+`Command` renders searchable, keyboard-driven actions and local choices.
+
+## When to use
+
+Use `CommandDialog` for an app-local command palette or picker with enough
+options to benefit from search. Use the item anatomy helpers when a result has
+supporting text or metadata.
+
+```tsx
+<CommandItem value="Open project">
+  <CommandItemIcon>
+    <FolderIcon />
+  </CommandItemIcon>
+  <CommandItemContent>
+    <CommandItemTitle>Open project</CommandItemTitle>
+    <CommandItemDescription>Choose a local folder</CommandItemDescription>
+  </CommandItemContent>
+  <CommandShortcut>⌘O</CommandShortcut>
+</CommandItem>
+```
+
+## Anatomy
+
+- `Command`, `CommandInput`, and `CommandList` own filtering and navigation.
+- `CommandGroup`, `CommandEmpty`, and `CommandSeparator` organize results.
+- `CommandItem` is the interactive cmdk option.
+- `CommandItemIcon`, `CommandItemContent`, `CommandItemTitle`, and
+  `CommandItemDescription` provide consistent row alignment.
+- `CommandShortcut` displays a trailing shortcut hint; it does not install the
+  shortcut.
+
+Use `NotificationDot`, `Status`, or `Spinner` as a trailing child when a result
+needs an indicator. Keep those states semantic instead of adding decoration to
+the row anatomy.
+
+## Keyboard and accessibility
+
+cmdk owns arrow-key navigation, selection, and filtering. Give icon-only
+information an accessible text equivalent. `CommandItemIcon` is decorative by
+default because the adjacent title should name the command.
+
+## Platform behavior
+
+This is a portable renderer component. An app-local palette does not replace
+the host command surface. Register host-visible commands through the Moldable
+command API and use this component only for commands owned by the current app.
+
+## Don't
+
+- Do not create a second interactive row inside `CommandItem`.
+- Do not install keyboard shortcuts from `CommandShortcut`.
+- Do not use a command palette for a small fixed set that fits in a menu.

package/src/components/ui/date-field.md

@@ -9,7 +9,7 @@
 ```tsx
 import { DateField } from '@moldable-ai/ui'
 
-<DateField
+;<DateField
   aria-label="Due date"
   value={dueDate}
   min="2026-01-01"