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:

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:e2e:smoke

Run lint and typecheck:

pnpm lint
pnpm typecheck

Install source-owned components into another project:

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

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:

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.

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

3.7 KiB Raw Blame History