Design a Scalable Component Library

You're tasked with building a shared component library for a company with 10+ product teams and 200+ engineers.

Requirements

Support theming (dark/light + per-product customization)
Accessible by default (WCAG AA)
Tree-shakeable
Type-safe API
Versioned and documented

Architecture

Token Layer

tokens/
  colors.json     → semantic color tokens
  spacing.json    → spacing scale
  typography.json → font stack, sizes, weights
  build.js        → compile to CSS vars, SCSS, JS objects

Tokens compile to multiple formats so any framework can consume them.

Component Layer

Each component follows the same pattern:

Button/
  Button.tsx       → main component
  Button.types.ts  → prop types
  Button.css       → styles using CSS custom properties
  Button.test.tsx  → unit + a11y tests
  Button.stories.tsx → Storybook stories
  index.ts         → public API

Key API Design Decisions

Compound components over prop-heavy APIs:

// Flexible, composable
<Dialog>
  <Dialog.Trigger asChild>
    <Button>Open</Button>
  </Dialog.Trigger>
  <Dialog.Content>
    <Dialog.Title>Settings</Dialog.Title>
    <Dialog.Body>...</Dialog.Body>
    <Dialog.Footer>
      <Dialog.Close asChild>
        <Button variant="ghost">Cancel</Button>
      </Dialog.Close>
    </Dialog.Footer>
  </Dialog.Content>
</Dialog>

Polymorphic components for flexibility:

<Button as="a" href="/settings">Settings</Button>
<Text as="label" htmlFor="email">Email</Text>

Versioning Strategy

Semantic versioning with changesets
Breaking changes go through RFC process
Codemods for automated migrations
LTS branches for major versions

A component library is a product. The consumers are your fellow engineers. Design the API you'd want to use.