Design system framework

Pages are the screens and flows people use. Build them with shared layouts, components, interactions, and foundation tokens. Product teams own their pages and share useful patterns with the system.

Interactions are optional decorative motion and pointer effects that bring a page to life. They are not required to complete a task. Use them selectively for atmosphere, brand character, and delight. Prefer reduced-motion fallbacks and keep essential content usable without the effect.

Components are reusable interface building blocks. Use existing components before writing custom markup. Interactive components come from shadcn/ui and include live examples. Use foundation tokens when a component does not meet the need.

Foundations define color, type, spacing, and states across the product. They use shadcn/ui and Tailwind CSS v4. Semantic tokens live in src/index.css. Use these tokens instead of one-off Tailwind values.

Principles are the rules that guide layout and interaction. They are based on Gestalt psychology, NN/g’s visual design guidance, and Jakob Nielsen’s usability heuristics. They are ordered by importance to make tradeoffs clear.