# 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

## 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.

## 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:registry:consumer
pnpm test:e2e:smoke
```

Run lint and typecheck:

```bash
pnpm lint
pnpm typecheck
```

Install source-owned components into another project:

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

## 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`.

## Registry install flow

Cadence UI now ships a minimal internal registry flow for source-owned adoption.
Consumers pin this repo to a reviewed commit or tag, then run the local installer to
copy selected items into their own codebase.

- Registry metadata lives in `registry/index.json` and is generated by `pnpm registry:build`.
- 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
- Storybook interaction coverage for representative examples
- Playwright smoke coverage for core Storybook flows
- Storybook a11y checks as part of the docs review surface

## 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.