Design7 min read

Design Systems

Build a shared design language - reusable components, tokens, and documentation that keep product teams aligned and UIs consistent at scale.

Design SystemsComponent LibraryFigmaStorybookUI

skill: Design Systems category: Design tags: [Design Systems, Component Library, Figma, Storybook, UI] readingTime: 7

A design system is a product, not a project - it requires ownership, versioning, documentation, and an adoption strategy. Before building one, audit existing UI for patterns. A premature design system built before sufficient pattern evidence creates overhead without benefit. Start with tokens and 5-10 core components before expanding.

Workflow

Audit and inventory existing UIBuilding a design system on top of guessed patterns leads to a system nobody uses. Audit to find the 20% of components used 80% of the time.
Define design tokensTokens are the foundation - named design decisions (colors, spacing, typography) that propagate from Figma to code automatically.
Build components with StorybookStorybook develops and documents components in isolation - no need to run the full app to work on a button. Stories serve as living documentation.
Publish as an npm packagePublishing the component library as an npm package enables any team in the org to install and update it with standard package management.
Write a contribution guideWithout contribution guidelines, the system becomes inconsistent as teams add components differently. A guide defines standards, review process, and what qualifies for inclusion.

Output Format

Design system: tokens → components → Storybook docs → npm package → contribution guidelines.

@myorg/ui/
├── src/
│   ├── index.ts           # Public exports
│   ├── tokens/            # Design tokens
│   └── components/
│       ├── Button/
│       │   ├── Button.tsx
│       │   ├── Button.stories.tsx
│       │   └── Button.test.tsx
│       └── Input/
├── storybook/
├── CONTRIBUTING.md
└── CHANGELOG.md

Examples

Input

Output

Edge Cases & Gotchas

Component API instability - Changing component props is a breaking change for every consumer. Collect usage data before renaming props. Use deprecated prop forwarding with console.warn for migration.
Monorepo vs. separate repo - A design system in a monorepo can use local imports during development but must publish to npm for consumption. Use Turborepo or Nx to manage the monorepo build.
Figma↔Code sync drift - Figma tokens diverge from code tokens over time. Use Tokens Studio for Figma + Style Dictionary + a CI check to detect drift.
Adoption without forcing - Forcing teams to use the design system without showing value creates resentment. Provide migration guides, office hours, and clear before/after performance/consistency wins.

When to Break These Rules

Use shadcn/ui instead of building from scratch - it's a collection of accessible, Tailwind-based components you copy into your codebase, giving full control without the publishing overhead.
Don't build a design system for a single product with one team - the overhead isn't justified until you have 3+ teams consuming the same components.

Reference Files

https://storybook.js.org/docs/
https://design-tokens.github.io/community-group/format/