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:

pnpm install

Start Storybook:

pnpm dev:docs

Build the packages:

pnpm build

Build Storybook:

pnpm build:docs

Run tests:

pnpm test
pnpm test:e2e:smoke

Run lint and typecheck:

pnpm lint
pnpm typecheck

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

How the component system is organized

The system is layered:

Tokens define semantic color, type, surface, radius, shadow, and motion values.
Primitives build on Radix where accessibility and interaction behavior matter.
Motion recipes provide reusable transition patterns instead of ad hoc animation rules.
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 before adding or changing components. It documents the component contract, story expectations, reduced motion and theme requirements, and the minimum validation workflow.