# [Org Name] · Design System

A shadcn/ui-based design system, themed via Tailwind v4 tokens, documented in Storybook, regression-tested with Chromatic.

## Source of truth
The Storybook (published to a static URL) is the canonical reference for what components look like and how they behave. Chromatic baselines are the source for "is this change a regression."

## Tech stack
React 19 + TypeScript + Tailwind v4 (CSS-first config). shadcn/ui as the base component layer (Radix primitives + Tailwind styling). Storybook 8 + the `@storybook/test` runner. Chromatic for visual regression. Published as a private npm package via changesets.

## Deploy
- Storybook: `npm run build-storybook` -> hosted on Vercel or Chromatic
- Package: published to npm (or org's private registry) via changesets

## File map
- `src/components/` shadcn-based components (Button, Input, Dialog, etc)
- `src/styles/tokens.css` Tailwind v4 `@theme` block with brand tokens
- `src/styles/globals.css` Tailwind import + base layer overrides
- `.storybook/` Storybook config (main.ts, preview.tsx)
- `src/stories/` one `.stories.tsx` per component
- `chromatic.config.json`
- `tsup.config.ts` (or tsc) to build the npm package

## .env keys
- `CHROMATIC_PROJECT_TOKEN` for publishing baselines (in CI)
- `NPM_TOKEN` for `npm publish` (in CI)

## Hard rules
- Every component has a story. Every story has at least: default, hover, focus, disabled, error states.
- Tokens (`tokens.css`) are the ONLY place colors, spacing, radii, font sizes live. Components reference token vars, never hex.
- Visual regression test runs in CI on every PR. Chromatic-approved changes go to baseline.
- Don't fork shadcn components unless you have to. Compose. The whole point of shadcn is the components are YOURS.
- `package.json` `exports` is explicit per component. Tree-shakeable: importing `Button` doesn't pull `Dialog`.
- A11y is non-negotiable. Every component passes `axe` in its Storybook test.

## Recent significant changes
- 2026-04-24: Scaffolded. Locked: shadcn/ui over Radix-direct (componentized starting point), Storybook over Ladle (Chromatic integration), Tailwind v4 tokens (CSS variables, themable at runtime).

## Next session: start here
1. `npx shadcn@latest init` if from scratch (already done in this template).
2. Define your brand tokens in `src/styles/tokens.css`.
3. Pick first 3 components: Button, Input, Card. Build stories for each.
4. Set up Chromatic. Baseline the first PR.
5. Publish a v0.1.0. Import it from one of your apps. Confirm tree-shaking works.