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