@utopia-studio-design/design-system-cli 0.1.0 → 0.2.0

package/data/docs/ai-platform-plan.md

@@ -0,0 +1,53 @@
+# Ceramic AI Platform Plan
+
+## Goal
+
+Humans and AI agents must discover, understand, apply, and validate Ceramic through the same package-owned contracts. The docs website is a renderer. CLI, JSON, programmatic API, generated agent instructions, and MCP are transport layers over the same manifests.
+
+## Phase 1: Shared Contract - Complete
+
+- Publishable `@utopia-studio-design/design-system` package with ESM, types, CSS, themes, and manifests.
+- Publishable `@utopia-studio-design/design-system-cli` package.
+- `manifest`, `search`, `component`, `template`, `theme`, `docs`, and `doctor` commands.
+- Typed JSON success and error envelopes.
+- `init` generation for AGENTS.md, Claude, Cursor, Copilot, Ceramic config, and MCP config.
+- Programmatic API at `@utopia-studio-design/design-system-cli/api`.
+- Stdio MCP server using the same query functions as the CLI.
+- Package dry-run and external consumer smoke tests.
+
+## Phase 2: Authoring Operations
+
+1. Add `template apply` with dry-run, conflict reporting, and idempotent writes.
+2. Add `swizzle` to copy component source plus dependency and token metadata.
+3. Add `theme build` to validate and compile third-party theme manifests.
+4. Add `upgrade` codemods with versioned migration records.
+5. Add `discover` for approved external registries without silently installing code.
+
+Every authoring command must support `--json`, `--dry-run`, deterministic output, explicit file lists, and non-zero failure codes.
+
+## Phase 3: Agent Evaluation
+
+- Create prompt fixtures for common website, SaaS, chat, data, Arabic, and mixed-script tasks.
+- Score imports, semantic tokens, accessibility, RTL behavior, theme compliance, and invented API usage.
+- Run LTR and RTL browser checks against generated fixtures.
+- Make regression scores a release gate for CLI, manifest, component, and theme changes.
+
+## MCP Client Setup
+
+The generated `.mcp.json` works for clients that support project-local MCP configuration. Codex CLI can register the same stdio server explicitly:
+
+```sh
+codex mcp add ceramic -- npx -y @utopia-studio-design/design-system-cli mcp
+```
+
+The server exposes read-only design-system discovery. File-writing operations remain CLI commands with dry-run and explicit user control.
+
+## Release Gates
+
+- Package build and external tarball import pass.
+- CLI text and JSON return equivalent records.
+- MCP tool responses match the CLI/programmatic API.
+- `init` generates valid files in a clean consumer project.
+- Component manifest audit passes.
+- Docs render in LTR and RTL without horizontal overflow.
+- No reusable component depends on raw theme primitives or invented localization copy.

package/data/docs/arabic-friendly.md

@@ -0,0 +1,72 @@
+# Arabic Friendly Design
+
+Arabic-friendly support is a first-class design-system goal. It is broader than RTL.
+
+- Use logical CSS properties.
+- Support `dir="ltr"` and `dir="rtl"`.
+- Use start/end naming, not left/right APIs.
+- Mirror or replace directional icons in RTL contexts.
+- Validate mixed English/Arabic labels.
+- Do not invent Arabic copy.
+- Require localized props for visible labels, `aria-label`, live-region status, empty-state copy, pagination controls, and formatter-generated accessibility text. Reusable components must not fall back to embedded English UI strings.
+
+## Side Navigation Requirements
+
+Side navigation is a release-gate component for Arabic-friendly quality because it controls product IA.
+
+- Keep page links and collapsible section titles separate. A page row such as `Side Nav` must not also be the disclosure trigger for its parts.
+- Preserve scroll position when a persistent side navigation collapses and expands.
+- Use `inline-start` and `inline-end` spacing for depth, nested section borders, badges, and trailing slots.
+- In `dir="rtl"`, collapsed disclosure indicators must rotate toward inline start. Direction-neutral panel icons may stay unmirrored.
+- Keep `icon`/`startContent` as inline-start slots and `badge`/`endContent` as inline-end slots.
+- Test mixed-script labels, numeric badges, current page state, disabled state, focus-visible, hover, and collapse/expand in both `dir="ltr"` and `dir="rtl"`.
+- Use Arabic strings only as supplied localization or explicitly marked test placeholders. Do not write production Arabic copy inside examples, manifests, or reusable components.
+
+## Arabic Typography Requirements
+
+Arabic typography needs its own role contract. It is not Latin typography translated into Arabic.
+
+- Required font roles: `--font-arabic`, `--font-arabic-body`, and `--font-arabic-display`.
+- Required rhythm roles: `--line-height-arabic`, `--line-height-arabic-body`, and `--line-height-arabic-display`.
+- Required display roles: `--font-size-arabic-display`, `--font-weight-arabic-display`, and `--tracking-arabic-display`.
+- Required body roles: `--font-size-arabic-body`, `--font-size-arabic-body-lg`, `--font-weight-arabic-body`, and `--tracking-arabic`.
+- Arabic display text must use scale, weight, rhythm, and Arabic display typeface rules. Do not map Latin all-caps styling to Arabic.
+- Arabic display size should track the Latin display scale at about 95%, rather than becoming visually larger than the Latin equivalent.
+- Arabic contexts must force `text-transform: none`.
+
+## RTL Layout Requirements
+
+Every reusable component and template must be written in logical layout terms.
+
+- Use `padding-inline`, `margin-inline`, `border-inline`, `inset-inline`, `inline-size`, and `block-size`.
+- Use `start`, `end`, `inline`, `block`, `leading`, or `trailing` naming in APIs.
+- Avoid `left`, `right`, `margin-left`, `padding-right`, and left/right-only prop names unless documenting a physical side.
+- Navigation, drawer, sidebar, pagination, carousel, progress, timeline, stepper, tabs, and menu patterns require explicit RTL checks.
+
+## Directional Mirroring Requirements
+
+Directional UI must mirror intentionally.
+
+- Mirror or replace arrows and chevrons used for previous/next, expand/collapse, breadcrumb, carousel, and inline motion.
+- Do not mirror direction-neutral icons by default: settings, add, home, camera, download, panel, and document icons.
+- Progress indicators and steppers should reverse visual flow only when the product sequence follows reading direction.
+- Motion should enter from inline start/end instead of physical left/right.
+
+## Accessibility Localization Contract
+
+- Icon-only actions require a localized accessible label from the consumer.
+- Composite widgets require localized landmark and slot labels, including Breadcrumb, Pagination, Input OTP, Chat actions, Spinner, and tool-call summaries.
+- Numeric values remain machine-readable while visible and spoken formatting comes from product locale data.
+- Direction-neutral icons such as loading spinners do not mirror; directional actions mirror through component direction.
+
+## Required Arabic Mockups
+
+The design system should include Arabic/RTL previews for:
+
+- Hero or display section.
+- Form.
+- Dashboard or table.
+- Empty state.
+- Side navigation.
+
+Mockups may use clearly marked test placeholder Arabic. They must not invent production Arabic marketing copy.

package/data/docs/foundations.md

@@ -0,0 +1,154 @@
+# Foundations
+
+Foundations define the semantic contract for humans, AI agents, themes, and reusable components. Components consume roles. Themes map those roles to visual primitives. The design-system app renders these pages at `/docs/foundations/*`.
+
+## Foundation Pages
+
+- `All Tokens`: complete semantic contract and required roles.
+- `Color`: role-based color, swatches, state matrix, and contrast/state guidance.
+- `Typography`: Latin/default type, Arabic type, mixed-script rhythm, and code typography.
+- `Spacing`: spacing scale plus RTL-aware logical layout rules.
+- `Shape`: control, surface, size, border, and round roles across theme styles.
+- `Motion`: duration/easing roles, disclosure motion, and directional motion rules.
+- `Elevation`: surface hierarchy, popovers, dialogs, and border-led elevation.
+- `Icons`: icon slots, icon-only actions, and directional mirroring.
+- `Illustrations`: media rules, empty states, and illustration boundaries.
+
+## Token Contract
+
+- Use semantic roles such as `--background`, `--foreground`, `--primary`, `--secondary`, `--surface`, `--surface-elevated`, `--border`, `--ring`, `--radius-control`, `--radius-surface`, `--font-sans`, `--font-arabic-body`, and `--font-arabic-display`.
+- Do not hardcode Utopia Default primitives such as Brick Red, Special Black, TWK Lausanne, or IBM Plex Sans Arabic inside reusable components.
+- Use logical CSS properties: `padding-inline`, `margin-inline`, `border-inline`, `inset-inline`, `block-size`, and `inline-size`.
+- Use start/end API names instead of left/right names.
+
+## Color Contract
+
+- Name tokens by purpose, not hue.
+- Components use `--primary`, `--secondary`, `--destructive`, `--muted`, `--border`, and `--ring`.
+- Themes may map those roles to brand primitives.
+- Focus-visible color is required; do not remove it for visual polish.
+- Disabled and selected states must remain readable in both LTR and RTL.
+
+## Typography Contract
+
+Arabic support is not a translation pass. Themes must define Arabic body and display roles.
+
+- `--font-arabic`
+- `--font-arabic-body`
+- `--font-arabic-display`
+- `--font-weight-arabic-body`
+- `--font-weight-arabic-display`
+- `--font-size-arabic-body`
+- `--font-size-arabic-body-lg`
+- `--font-size-arabic-display`
+- `--line-height-arabic`
+- `--line-height-arabic-body`
+- `--line-height-arabic-display`
+- `--tracking-arabic`
+- `--tracking-arabic-display`
+
+Latin all-caps display styling does not transfer to Arabic. For Arabic display, use scale, weight, rhythm, and Arabic display typeface tokens. Keep `text-transform: none`.
+
+Arabic display sizing should follow the Latin display scale at about 95%, rather than making Arabic headings larger than Latin headings. Keep Arabic line-height readable for connected letterforms and diacritics.
+
+## Spacing Contract
+
+- Use the spacing scale through semantic layout decisions.
+- Use `inline-start` and `inline-end` instead of physical left/right.
+- Navigation, sidebars, drawers, tabs, pagination, carousels, progress indicators, and steppers require RTL smoke checks.
+- Preserve DOM meaning and keyboard order. Do not reverse data or workflow meaning unless product rules require it.
+
+## Shape Contract
+
+- Controls consume `--radius-control`.
+- Cards, dialogs, popovers, and other framed surfaces consume `--radius-surface`.
+- Avatars, pills, and circular affordances may consume a round role when present.
+- Control dimensions use size roles such as `--size-control-sm`, `--size-control-md`, and `--size-control-lg`.
+- Borders use semantic width/style roles such as `--border-width-hairline`, `--border-width-focus`, and `--border-style-default`.
+- Utopia Default can be square. Future themes may be rounded without component rewrites.
+
+## Motion Contract
+
+- Ceramic defines five semantic patterns: `press`, `page`, `expand`, `reveal`, and `icon`.
+- Components consume `--motion-duration-*` and `--motion-ease-*` roles rather than hardcoded milliseconds or easing curves.
+- `MotionProvider` sets the subtree default. Motion-aware components expose `motion?: boolean` for a local override.
+- `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.
+
+```tsx
+import { MotionProvider } from '@utopia-studio-design/design-system/Motion'
+import { Button } from '@utopia-studio-design/design-system/Button'
+
+export function App() {
+  return (
+    <MotionProvider motion>
+      <Button motion={false}>Static local action</Button>
+    </MotionProvider>
+  )
+}
+```
+
+## Elevation Contract
+
+- Elevation is semantic hierarchy, not a mandatory shadow style.
+- Utopia Default prefers border-led surfaces.
+- Popovers and dialogs use elevated surface roles and focus management.
+- Do not hardcode `box-shadow` recipes inside reusable component logic.
+
+## Icon Contract
+
+- 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.
+- 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.
+
+## Illustration Contract
+
+- Illustrations are theme and product media, not core component requirements.
+- Empty states must work without decorative imagery.
+- Use real product/place/object media when inspection matters.
+- Do not use generic gradients or decorative blobs as a substitute for system content.
+
+## Usage Sections
+
+Every foundation page should expose:
+
+1. `Overview`: what the foundation controls and what it does not own.
+2. `Tokens`: the semantic roles and AI usage rule for each role.
+3. Foundation-specific visualization: swatches, type scale, spacing scale, shape preview, motion preview, elevation surfaces, icon mirroring, or empty state media.
+4. `Usage`: when to use the foundation in real UI.
+5. `Best Practices`: do/don't/check guidance.
+6. `AI Usage Rules`: machine-readable setup and generation instructions.
+7. `Arabic / RTL Check`: compact page-specific RTL guidance. Use `All Tokens` and the Arabic Friendly page for full product mockups.
+
+## Best Practice Baseline
+
+- Keep primitive tokens inside theme manifests and semantic roles inside reusable components.
+- Do not generate raw brand colors, shadcn visual defaults, or physical left/right spacing into reusable code.
+- Verify hover, focus-visible, active, disabled, selected, expanded, loading, empty, and destructive states.
+- Verify Arabic/RTL with mixed-script labels, Arabic numerals, truncation, badges, and direction-aware icons.
+- Treat illustration, icon philosophy, brand-specific geometry, and display casing as theme-owned unless a component contract explicitly owns the behavior.
+
+## AI Usage Rules
+
+Before generating UI:
+
+1. Read `packages/design-system/src/manifests/themes.json`.
+2. Read the active theme policy manifest.
+3. Read `packages/design-system/src/manifests/components.json`.
+4. Use semantic tokens only.
+5. Check Arabic/RTL behavior with `dir="rtl"`, `lang="ar"`, mixed-script labels, Arabic numerals, badges, truncation, focus-visible, and no invented production Arabic copy.
+
+## Required Arabic Mockups
+
+All Tokens and the Arabic Friendly page must include or link to these RTL previews:
+
+- Hero or display section
+- Form
+- Dashboard or table
+- Empty state
+- Side navigation
+
+Individual Foundation pages should show a compact Arabic / RTL check instead of repeating the full product mockups.

package/data/docs/guide.md

@@ -0,0 +1,37 @@
+# Guide
+
+Guide pages are the operating layer of Ceramic. They define how humans and AI agents should use the design system before reaching for components, templates, or theme primitives.
+
+## Pages
+
+- `Getting Started`: installation, theme CSS, first component, examples, CLI discovery, Arabic-friendly entrypoint.
+- `What's New`: release notes for package, manifest, theme, and docs changes.
+- `Quick Start with AI`: dense setup workflow for AI coding tools.
+- `Working with AI`: how manifests, docs, and examples stay machine-readable.
+- `Principles`: semantic-first, shadcn-founded, theme-extensible, Arabic-friendly, AI-readable rules.
+- `Theme System`: required semantic roles, Utopia Default as first theme, and future theme boundaries.
+- `Arabic Friendly`: RTL-first layout, Arabic typography, mixed-script resilience, localization readiness, and icon/motion mirroring.
+- `Styling Components`: safe component styling through semantic tokens and app-layer className.
+- `Styling Library Interop`: Tailwind, plain CSS, CSS modules, and CSS-in-JS bridges through Ceramic CSS variables.
+- `Migration Guide`: safe migration from app-local UI or raw shadcn usage into `packages/design-system`.
+
+## Guide Contract
+
+- Each guide page must include `Overview`, `Usage`, `Rules`, and `AI Checklist`.
+- Migration pages may rename `Usage` to `Migration Order` and `Rules` to `Safe Boundaries`.
+- Guide pages must not duplicate component API contracts that belong in `components.json`.
+- 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.
+
+## AI Rule
+
+Before generating UI, read:
+
+1. `docs/design-system/quick-start-ai.md`
+2. `docs/design-system/guide.md`
+3. `docs/design-system/foundations.md`
+4. `docs/design-system/arabic-friendly.md`
+5. `docs/design-system/shadcn-conversion.md`
+6. `packages/design-system/src/manifests/catalog.json`
+7. `packages/design-system/src/manifests/components.json`
+8. `packages/design-system/src/manifests/themes.json`

package/data/docs/quick-start-ai.md

@@ -0,0 +1,122 @@
+# Quick Start with AI
+
+Ceramic follows the Astryx principle that humans, coding agents, build tools, and MCP clients use the same source of truth. The docs site does not maintain a separate component contract.
+
+## 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
+
+```sh
+npm install @utopia-studio-design/design-system
+npm install -D @utopia-studio-design/design-system-cli
+npx utopia-ds init --theme utopia-default
+```
+
+The init command creates:
+
+- `AGENTS.md` and `CLAUDE.md`
+- `.cursor/rules/ceramic-design-system.mdc`
+- `.github/copilot-instructions.md`
+- `.ceramic/config.json`
+- `.mcp.json`
+- stable `ceramic` and `ceramic:doctor` npm scripts
+
+## Add Theme CSS
+
+```css
+@import '@utopia-studio-design/design-system/core.css';
+@import '@utopia-studio-design/design-system/themes/utopia-default.css';
+```
+
+## Add A Component
+
+```tsx
+import { Button } from '@utopia-studio-design/design-system/Button'
+
+export function SaveAction() {
+  return <Button>Save changes</Button>
+}
+```
+
+## 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.
+
+```tsx
+import { MotionProvider } from '@utopia-studio-design/design-system/Motion'
+import { Button } from '@utopia-studio-design/design-system/Button'
+
+export function App() {
+  return (
+    <MotionProvider motion>
+      <Button>Animated by the press contract</Button>
+      <Button motion={false}>Static override</Button>
+    </MotionProvider>
+  )
+}
+```
+
+Never bypass `MotionProvider`, semantic motion tokens, or `prefers-reduced-motion`. The `motion` prop changes transition behavior, not component state or accessibility.
+
+## Discover Before Generating
+
+```sh
+npx utopia-ds manifest --json
+npx utopia-ds search "Arabic settings form" --json
+npx utopia-ds component Button --json
+npx utopia-ds template --list --json
+npx utopia-ds template template-saas-solution-homepage --copy ./saas-solution-website
+npx utopia-ds template template-saas-solution-homepage --theme dextrum --copy ./dextrum-website
+npx utopia-ds theme utopia-default --json
+npx utopia-ds theme create nova
+npx utopia-ds docs arabic-friendly --dense
+npx utopia-ds doctor --json
+```
+
+Use `--dense` for small prompt context and `--json` for automation. Every JSON success response uses `{ apiVersion, type, data, meta }`; errors use `{ apiVersion, error, code, suggestions }`.
+
+## MCP
+
+The MCP server exposes the same API as the CLI. A generated `.mcp.json` uses:
+
+```json
+{
+  "mcpServers": {
+    "ceramic": {
+      "command": "npx",
+      "args": ["-y", "@utopia-studio-design/design-system-cli", "mcp"]
+    }
+  }
+}
+```
+
+Available tools include search, component/template/theme/doc discovery, and doctor. An MCP client must never receive capabilities that the CLI cannot expose.
+
+## Agent Decision Loop
+
+1. Run `manifest --json` to discover supported operations.
+2. Run `search <intent> --json` instead of guessing a component name.
+3. Inspect the chosen template and every component contract.
+4. Read the active theme and Arabic-friendly contract.
+5. Implement with package exports and semantic tokens.
+6. Run product tests and `doctor --json` before handoff.
+
+## Create A Theme
+
+Run this from the Ceramic Design System workspace:
+
+```sh
+npx utopia-ds theme create nova
+npm run sync-data --workspace @utopia-studio-design/design-system-cli
+npm run ds -- doctor
+```
+
+The command creates `nova.css`, `theme-nova.json`, and registers the theme in `themes.json`. The scaffold includes dark, light, Arabic typography, shape, and semantic motion contracts. Replace its placeholder brand primitives before publishing it.
+
+## Core And Theme Boundary
+
+Core owns shadcn-style architecture, semantic roles, accessibility, Arabic-friendly baseline behavior, and agent-readable contracts. Themes own brand visual philosophy. Utopia Default owns Brick Red, Special Black, TWK Lausanne, IBM Plex Sans Arabic, square geometry, and its declared icon policy.

package/data/docs/shadcn-conversion.md

@@ -0,0 +1,35 @@
+# shadcn/ui Conversion Contract
+
+Utopia Design System uses shadcn/ui as the implementation foundation, not as a visual theme.
+
+## Rules
+
+- Keep `components.json` pointed at `packages/design-system/src/components`.
+- Convert shadcn source into Utopia package exports before app usage.
+- Components consume semantic tokens such as `--background`, `--foreground`, `--surface`, `--border`, `--radius-control`, and `--radius-surface`.
+- Do not copy raw shadcn colors, default radius assumptions, or left/right-only layout rules into reusable components.
+- Utopia Default Theme maps the semantic contract to the current Utopia brand. Other themes may map it differently.
+- Arabic-friendly behavior is required: logical CSS properties, `dir="rtl"` checks, mixed-script text tolerance, and no invented Arabic production copy.
+
+## Workflow
+
+```bash
+pnpm dlx shadcn@latest init
+```
+
+The project already has a `components.json` file. Do not overwrite it unless the Utopia DS aliases are preserved.
+
+```bash
+npm run ds -- component --list --dense
+npm run ds -- component "Accordion" --dense
+```
+
+Use the dense CLI output to pick the Utopia package import. If a component still points to `ShadcnPrimitives`, it has a safe semantic wrapper and should be specialized before complex production usage.
+
+## Current Source Of Truth
+
+- shadcn setup: `components.json`
+- Utopia catalog: `packages/design-system/src/manifests/catalog.json`
+- Component contracts: `packages/design-system/src/manifests/components.json`
+- Safe conversion wrappers: `packages/design-system/src/components/ShadcnPrimitives.tsx`
+- Core semantic styling: `packages/design-system/src/core.css`

package/data/docs/theme-authoring.md

@@ -0,0 +1,46 @@
+# Theme Authoring
+
+Themes are token-contract and visual-policy implementations.
+
+## Scaffold A Theme
+
+```sh
+npx utopia-ds theme create nova
+```
+
+Run the command from the Design System workspace. It writes the theme CSS and policy manifest and registers the theme in the catalog. Theme IDs use lowercase kebab-case. The generated colors and typography are safe placeholders, not a finished brand direction.
+
+## Required Read Order
+
+1. `packages/design-system/src/core.css`
+2. `packages/design-system/src/manifests/themes.json`
+3. The active theme policy manifest, such as `theme-utopia-default.json`
+4. Component and template manifests
+
+## Core Boundary
+
+Core owns semantic roles, component APIs, accessibility, Arabic-friendly requirements, and shadcn-style architecture.
+
+Core does not own brand palette, brand typography, icon style, brand voice, or brand-specific layout philosophy.
+
+## Theme Boundary
+
+A theme maps primitives to semantic roles and declares its own visual policy:
+
+- Color primitives
+- Typography family and weights
+- Radius and shape
+- Elevation model
+- Icon policy
+- Motion profile
+- Copy and casing guidance
+
+Theme CSS owns both `[data-theme="<id>"]` and `[data-theme="<id>"][data-color-mode="light"]`. Templates set theme and color-mode attributes but must not remap brand primitives themselves.
+
+Utopia Default is strict about Brick Red, Special Black, TWK Lausanne, square geometry, and dot/bar icons. Those are not global design-system rules.
+
+## Motion Profile
+
+Every theme implements the stable semantic roles `--motion-duration-press`, `--motion-duration-page`, `--motion-duration-expand`, `--motion-duration-reveal`, `--motion-duration-icon`, `--motion-ease-standard`, and `--motion-ease-emphasized`. A theme may change timing and easing, but it must preserve the intent of each pattern and reduced-motion behavior.
+
+Components use `MotionProvider` and their optional `motion` prop. Theme authors must not introduce component-specific hardcoded milliseconds or a generic bounce animation.