Design Systems

Build UI components that are accessible, themeable, composable, and visually polished.

Spec vs components. If the user asks for DESIGN.md, a style guide, documenting existing tokens, or standing up the design system — or they pass route:/mood:/name:/framework: overrides — follow references/design-spec.md and stop after that loop. Do not run the spec loop just because this skill loaded for a .tsx/.css edit. Component work uses the sections below. If DESIGN.md exists, implement against it; do not rewrite it unless asked.

Companion skills: React performance (vercel-react-best-practices), composition (vercel-composition-patterns), CSS techniques (modern-css), UI code review (web-design-guidelines).

1. Component Architecture

Headless + Styled Layers

Separate behavior from appearance. Use headless primitives (Radix, Ark UI, Headless UI) for accessibility and interaction, then add your styling layer on top. This gives you accessible-by-default components you can theme however you want.

Compound Components Over Prop-Heavy Monoliths

Complex UI should be composed of named parts, not configured with dozens of props: