Back to projects
Projectadvanced 8 steps ~120 min

Design System Component Kit

Build semantic tokens with themes, a variant-driven Button, compound Tabs, and an accessible Dialog, organized as a real component library.

What you'll build

A themeable mini component library with tokens, Button, Tabs, and Dialog that pass keyboard and screen-reader checks.

  • React
  • CSS variables
  • compound components
  • ARIA
  • focus management
Project briefrequirements and design decisions

Requirements

  • Components consume semantic tokens only; switching theme re-renders nothing
  • Button supports variant (primary/secondary/ghost), tone (neutral/danger), size, and loading
  • Tabs work controlled and uncontrolled, with arrow-key navigation
  • Dialog traps focus, closes on Esc, and restores focus to its trigger
  • Every interactive element has a visible focus ring and an accessible name

Architecture decisions

  • Three token tiers (primitive → semantic → component), emitted as CSS variables
  • Variants resolved by a small typed resolver instead of boolean props
  • Compound components share state through context with a guard hook
  • Accessibility is built into the parts, so consumers can't forget it

Stretch goals

  • Add a headless useCombobox hook and build a styled Select on it
  • Generate a props table from TypeScript types
  • Add a high-contrast theme and an automated contrast check

Production checklist

  • Visual regression tests per component and theme
  • axe checks in component tests
  • Versioned package with changelog and codemods for breaking changes
  • Usage analytics across consuming repos

1What we're building

You'll build the core of a design system, the shared foundation that product teams build UI on. It's organized the way a real component library is:

1tokens.css semantic design tokens + themes 2components/ 3 index.js the public API: export { Button, Tabs, Dialog } 4 Button.jsx + .css variant-driven button 5 Tabs.jsx + .css compound tabs with keyboard support 6 Dialog.jsx + .css accessible modal dialog 7App.jsx product code that consumes the library

The architecture rules we'll follow:

  • Components use semantic tokens only (--action-primary, never #7c3aed), so theming never touches component code.
  • Each component colocates its styles (Button.css next to Button.jsx).
  • Product code imports only from ./components (the index file), never from individual files. That's what lets the library reorganize internals without breaking consumers.
  • Invalid prop combinations are impossible by design, and accessibility lives inside the components.

Each step's playground has the files built so far. Switch between them with the file tabs above the editor. Read the project brief above for the full requirements.

Design System Component Kit project | Bloom