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](/Users/xd/project/cadence-ui/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](/Users/xd/project/cadence-ui/DESIGN.md)
- [README.md](/Users/xd/project/cadence-ui/README.md)
- [CONTRIBUTING.md](/Users/xd/project/cadence-ui/CONTRIBUTING.md)
- [roadmap.md](/Users/xd/project/cadence-ui/roadmap.md)
- [packages/ui/src/lib/contracts.ts](/Users/xd/project/cadence-ui/packages/ui/src/lib/contracts.ts)
- [apps/docs/src/component-authoring.stories.tsx](/Users/xd/project/cadence-ui/apps/docs/src/component-authoring.stories.tsx)
- [docs/harness-engineering.md](/Users/xd/project/cadence-ui/docs/harness-engineering.md)
- [docs/orchestration.md](/Users/xd/project/cadence-ui/docs/orchestration.md)

## Getting started

Requirements:

- `node >= 24`
- `pnpm >= 10`

Install dependencies:

```bash
pnpm install
```

Start Storybook:

```bash
pnpm dev:docs
```

Build the packages:

```bash
pnpm build
```

Build Storybook:

```bash
pnpm build:docs
```

Build the registry metadata:

```bash
pnpm registry:build
```

Run tests:

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

Run lint and typecheck:

```bash
pnpm lint
pnpm typecheck
```

## Package consumption

Package consumption is the default path for downstream apps:

```bash
pnpm add @ai-ui/ui
```

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

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

```css
@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:

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

Package release details live in [docs/releasing.md](/Users/xd/project/cadence-ui/docs/releasing.md).
Source-copy install and upgrade details live in [docs/registry.md](/Users/xd/project/cadence-ui/docs/registry.md).

## Workspace structure

```txt
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](/Users/xd/project/cadence-ui/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](/Users/xd/project/cadence-ui/docs/harness-engineering.md).
- Non-trivial work should start with an execution plan under
  [docs/exec-plans](/Users/xd/project/cadence-ui/docs/exec-plans/README.md).
- Shared validation suites are exposed through the root `pnpm harness:*` scripts.
- Worktree-oriented orchestration defaults live in
  [docs/orchestration.md](/Users/xd/project/cadence-ui/docs/orchestration.md).

Useful commands:

```bash
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](/Users/xd/project/cadence-ui/CONTRIBUTING.md) before adding or
changing components. It documents the component contract, story expectations, reduced
motion and theme requirements, and the minimum validation workflow.