cadence-ui/README.md

Cadence UI

Cadence UI is a source-owned React component system built in a pnpm workspace. The repo keeps the Radix + Tailwind + source-owned components model, but replaces default styling with its own tokens, motion recipes, and component contract.

What this repo contains

• packages/tokens: theme tokens, motion tokens, and theme helpers
• packages/ui: component source, variants, contracts, and tests
• apps/docs: Storybook docs and usage reference
• registry: generated registry metadata plus the source-copy install contract
• tests/e2e: Playwright smoke coverage for high-value Storybook flows

Current status

• The foundation, token layer, authoring contract, Storybook docs, and unit coverage are in place.
• The public UI surface now includes the core form and overlay set plus advanced patterns such as DataTable, Command, Combobox, Sheet, and EmptyState.
• The default distribution path is package-first: @ai-ui/ui and @ai-ui/tokens are versioned and validated for package consumption.
• The internal source-copy registry flow remains available as an optional mode for teams that want local ownership of copied component source.
• The active visual direction is documented in DESIGN.md: a single Material You inspired language with dynamic color, tonal surfaces, large radii, and one shared motion system.

System principles

• Source owned: components live in this repo and are modified directly.
• Token first: colors, type, radius, shadow, and motion decisions come from tokens.
• Component contract over component count: stable APIs matter more than shipping many one-off parts.
• Accessibility by default: keyboard, focus, ARIA, and reduced motion are baseline expectations.
• Motion with purpose: animation should communicate state and hierarchy, not decorate at random.

System Of Record

When changing public visuals, docs, or interaction behavior, treat these files as the baseline context before making non-trivial changes:

• DESIGN.md
• README.md
• CONTRIBUTING.md
• roadmap.md
• packages/ui/src/lib/contracts.ts
• apps/docs/src/component-authoring.stories.tsx
• docs/harness-engineering.md
• docs/orchestration.md

Getting started

Requirements:

• node >= 24
• pnpm >= 10

Install dependencies:

pnpm install

Start Storybook:

pnpm dev:docs

Build the packages:

pnpm build

Build Storybook:

pnpm build:docs

Build the registry metadata:

pnpm registry:build

Run tests:

pnpm test
pnpm test:package:consumer
pnpm test:registry:consumer
pnpm test:e2e:smoke

Run lint and typecheck:

pnpm lint
pnpm typecheck

Package consumption

Package consumption is the default path for downstream apps:

pnpm add @ai-ui/ui

Prefer a single CSS entrypoint from @ai-ui/ui:

import { Button } from "@ai-ui/ui";

@import "tailwindcss";
@import "@ai-ui/ui/styles.css";
@source "../node_modules/@ai-ui/ui/src";

This keeps the app on one UI package import path while still pulling in token and skin styles together. Consumers that want lower-level control can still import @ai-ui/tokens/styles.css and @ai-ui/ui/skins.css separately. If you need token helpers such as setTheme or setDynamicColor, add @ai-ui/tokens directly as well.

If you need source ownership instead of package upgrades, use the optional registry installer to copy component source into another project:

pnpm registry:install --project ../acme-app button dialog

Package release details live in docs/releasing.md. Source-copy install and upgrade details live in docs/registry.md.

Workspace structure

apps/
  docs/        Storybook docs and interaction examples
packages/
  tokens/      Theme and motion tokens
  ui/          Component source, variants, tests, and contracts
tests/
  e2e/         Playwright smoke specs
registry/      Generated item metadata for copy-in installs

How the component system is organized

The system is layered:

1. Tokens define semantic color, type, surface, radius, shadow, and motion values.
2. Primitives build on Radix where accessibility and interaction behavior matter.
3. Motion recipes provide reusable transition patterns instead of ad hoc animation rules.
4. Components compose tokens, primitives, and recipes into the public API.

The current public component layer lives in packages/ui/src/components, with shared helpers in packages/ui/src/lib.

Optional Source-Copy Flow

Cadence UI still ships a registry installer for teams that want to copy component source into their own app and keep editing it there. This is the advanced customization path, not the default distribution path.

• Registry metadata lives in registry/index.json and is generated by pnpm registry:build.
• The generated index tracks transitive local helpers in addition to component entrypoints, so helper-import changes need a registry rebuild before merge.
• The installer copies components into src/cadence-ui, adds missing package dependencies, and writes src/cadence-ui/.install-manifest.json so upgrades can reuse the same item set.
• pnpm test:registry:consumer creates a temporary consumer app, runs the installer, and verifies the copied source typechecks and builds.
• Install and upgrade instructions live in docs/registry.md.

Docs and QA

Storybook is the main usage reference and review surface. Component stories are expected to document more than the default playground when behavior is non-trivial. The repo also uses:

• Vitest + Testing Library for unit and interaction coverage
• package consumer smoke coverage for published-package consumption
• Storybook interaction coverage for representative examples
• Playwright smoke coverage for core Storybook flows
• Storybook a11y checks as part of the docs review surface

Harness engineering

Cadence UI now includes a first-pass harness workflow for agent-friendly engineering. The goal is to make the repository easier to understand, plan against, and validate mechanically.

• System guidance lives in docs/harness-engineering.md.
• Non-trivial work should start with an execution plan under docs/exec-plans.
• Shared validation suites are exposed through the root pnpm harness:* scripts.
• Worktree-oriented orchestration defaults live in docs/orchestration.md.

Useful commands:

pnpm harness:select
pnpm harness:suites
pnpm harness:validate:static
pnpm harness:validate:changed
pnpm harness:validate:component
pnpm harness:validate:docs
pnpm harness:validate:docs-smoke
pnpm harness:validate:consumers
pnpm harness:validate:pr
pnpm harness:validate:release
pnpm harness:orch -- status --run <run-id>

Contributing

Read CONTRIBUTING.md before adding or changing components. It documents the component contract, story expectations, reduced motion and theme requirements, and the minimum validation workflow.