rgoussu.dev
rgoussu@goussu: ~/library/frontend/exercises
❯ ~/library/frontend/exercises cat design-system-from-scratch.md

Design system from scratch

# Build a small design system end to end — semantic tokens, accessible atomic components, Storybook docs, versioned package — and prove it with a theme swap.

Exercisesaved 2026-08-08 #exercise#frontend#design-systems#atomic-design#accessibility#typescript

Goal

Build a miniature but complete design system — design tokens through documented, versioned component library — and prove it works by consuming it in a demo app and swapping themes without touching a component. It condenses the whole frontend theme into one artifact: the system-of-parts mindset, a11y centralized at the component level, and types as the API contract.

Subject: full brief & instructions

Practices

  • Design systems — tokens, library, docs, versioning: every layer of the concept, built by hand.
  • Atomic design — the composition hierarchy structures the library: atoms → molecules → organisms.
  • Accessibility — APG-complete keyboard and ARIA contracts, implemented once at the atom level.
  • TypeScript deep dive — typed props as component API design; discriminated unions for variants.

Milestones

  1. Token layer. Define a raw palette, then a semantic token set over it (color.action.primary, space.200, type scale) emitted as CSS variables. Add a dark theme by redefining only the semantic layer. Ship: a token showcase page.
  2. Atoms. Button, Input, Label, Icon — semantic HTML underneath, visible focus states, typed props (variants as unions, no boolean soup), styled exclusively through tokens. Ship: atoms rendering in both themes.
  3. Molecules & organisms. A form field (label + input + error wiring via aria-describedby), a dialog (focus trap, restore, Escape), a nav header with landmarks. Follow the WAI-ARIA APG contracts to the letter. Ship: keyboard-only walkthrough works.
  4. Storybook. A story per component state, do/don't usage docs, the a11y addon plus axe checks running in CI. Ship: the documented workbench a teammate could adopt from.
  5. Package & prove. Version and publish the library (npm workspace or tarball), consume it in a small demo app, then swap the theme — and change nothing else. Ship: the demo app on both themes.

Stretch goals

  • Visual regression testing on the stories (Chromatic or Playwright screenshots).
  • A second brand theme, to test whether the semantic tokens were honest.
  • Rebuild the dialog on a headless primitive (Radix/React Aria) and compare the a11y code you got to delete.

Related