React Design System

Atomic decision guides for building reusable, composable, well-typed React components. Targets React 19, Next.js App Router, Tailwind CSS v4, Radix UI, and CVA.

I need to...	Guide	Summary
Decide component architecture (flat vs compound vs headless)	Component Architecture Decisions	Use flat props for simple single-purpose UI. Use compound components when the caller needs to place named slots (header/body/footer) in their markup.
Design a component's props API	Props Patterns	Use these patterns when defining the public API of a component. Well-designed props prevent breaking changes and communicate intent clearly.
Handle children, slots, or asChild	Children and Slot Patterns	Use when a component needs to render content it doesn't control — layouts, wrappers, trigger+panel pairs.
Build compound components with shared state	Composition Patterns	Use when building multi-part components (select, tabs, accordion, dialog) where sub-components need to share state without prop drilling.
Use Tailwind with cn() and CVA	Tailwind Integration	Use cn() and CVA in every component that uses Tailwind classes. cn() handles merging; CVA handles variant definitions.
Manage size/color/state variants	Variant Management	Use when a component has multiple dimensions of variation (size, color/intent, state) that combine in predictable ways. CVA makes these combinations type-safe and conflict-free.
Connect design tokens in Tailwind v4	Design Token Consumption	Use when connecting design tokens (colors, spacing, typography scales) from a design tool or token file into React components. Tailwind v4 changes the approach significantly — there is no tailwind.config.ts.
Type components in TypeScript	TypeScript Patterns	Use in every design system component. TypeScript is how the system communicates its API to consumers — it's not optional.
Make components accessible	Accessibility Patterns	Use in every interactive component. Accessibility is a correctness requirement — a design system that ships inaccessible components ships broken components.
Document components in Storybook	Storybook Integration	Use for all design system components. Storybook is the development environment, living documentation, and visual regression baseline — not optional.
Organize component files and folders	Component Organization	Use when setting up a design system repository or deciding where to put a new component.
Build form components with react-hook-form	Form Components	Use when building Input, Select, Checkbox, Textarea, or any form field component. Form components have unique requirements: validation state, error display, accessibility linking, and library integration.
Build layout primitives (Stack, Flex, Grid)	Layout Components	Use when building reusable spacing, flex, and grid primitives. Layout components standardize spacing and remove repetitive Tailwind class sets from feature code.
Optimize render performance	Performance	Use when a design system component is causing measurable performance issues, or when designing components that appear in long lists, frequently updating UIs, or high-traffic render paths. Profile first — do not optimize speculatively.
Test design system components	Testing	Use for every design system component. Tests protect the API contract — they catch regressions before consumers notice.
Follow best practices and avoid anti-patterns	Best Practices and Anti-Patterns	Use before shipping a component to design system consumers, and during code review.
Find source references and maintenance notes	Sources and Maintenance