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

Run tests:

```bash
pnpm test
pnpm test:e2e:smoke
```

Run lint and typecheck:

```bash
pnpm lint
pnpm typecheck
```

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

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

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