feat: add empty state and expand overlay qa

2026-03-19 19:00:36 +08:00
parent f318f94c9a
commit 132bb6961d
20 changed files with 1094 additions and 6 deletions
@@ -0,0 +1,106 @@
+# 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.