Design a Design System

This is the quintessential senior/staff frontend system design question. It tests architectural thinking, API design, and understanding of scale.

The Prompt

Design a design system and component library used by 50+ engineers across 5 product teams. It should support theming, accessibility, and multiple frameworks.

Clarifying Questions to Ask

Before designing anything, ask:

How many products? Are they all React, or do we need framework-agnostic components?
Theming needs? White-label? Dark mode? Per-product customization?
Current state? Are we migrating from existing components or starting fresh?
Distribution? Monorepo or published packages?
Who are the consumers? Only frontend engineers, or designers too?

Architecture Layers

1. Design Tokens

The foundation. Framework-agnostic values that define the visual language:

{
  "color": {
    "primary": { "value": "#00FFB2", "type": "color" },
    "background": { "value": "#0B0F19", "type": "color" }
  },
  "spacing": {
    "sm": { "value": "8px", "type": "dimension" },
    "md": { "value": "16px", "type": "dimension" }
  },
  "typography": {
    "heading": {
      "fontFamily": { "value": "Inter", "type": "fontFamily" },
      "fontWeight": { "value": "700", "type": "fontWeight" }
    }
  }
}

Tokens compile to CSS custom properties, SCSS variables, JS objects — whatever consumers need.

2. Primitive Components

Unstyled, accessible building blocks:

Button, Input, Select, Dialog, Tooltip
Built with WAI-ARIA patterns
Controlled and uncontrolled variants
Composable (compound component pattern)

3. Themed Components

Primitives + design tokens + product-specific styling.

4. Composition Patterns

Higher-order components for common layouts:

PageLayout, FormSection, DataTable
These are opinionated and product-specific

Key Decisions

Styling Strategy

Approach	Pros	Cons
CSS Modules	No runtime cost, standard CSS	Harder to theme dynamically
CSS-in-JS	Dynamic theming, colocation	Runtime cost, bundle size
Tailwind	Rapid development, consistent	Harder to abstract as library
CSS Custom Properties	Zero runtime, dynamic theming	Need fallbacks for older browsers

Recommendation: CSS Custom Properties for tokens + CSS Modules for components. Zero runtime overhead, full theming support.

API Design Principles

Composable over configurable — prefer <Dialog><Dialog.Title> over <Dialog title="">
Controlled by default — let consumers own state
Accessible by default — ARIA attributes built in, not opt-in
Polymorphic — <Button as="a" href="/foo"> renders an anchor with button styles

Distribution

packages/
  tokens/           → @company/tokens
  primitives/       → @company/primitives
  react-components/ → @company/react
  docs/             → Storybook + usage docs

Use changesets for versioning. Semantic versioning. Breaking changes go through an RFC process.

Architect Thinking

A design system is a product, not a project. It needs:

A dedicated team (even if small)
Versioning and migration guides
Documentation that's better than your product docs
Metrics: adoption rate, accessibility scores, bundle size budgets

The best design systems constrain just enough to create consistency without killing velocity.