132 lines
3.7 KiB
Markdown
132 lines
3.7 KiB
Markdown
# 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: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.
|
|
- 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.
|