Design System Builder
A structured guide for building production-ready component libraries and design systems. Covers architecture,
tokens, components, documentation, theming, testing, and publishing.
Quick Decision Map
1. Architecture & Monorepo Setup
Recommended Structure
Use pnpm workspaces + Turborepo for monorepo management.
my-design-system/
├── packages/
│ ├── tokens/ # Design tokens (CSS vars, JS objects)
│ ├── icons/ # SVG icon components
│ ├── components/ # Core UI components
│ ├── themes/ # Theme definitions
│ └── utils/ # Shared utilities (cn, clsx, etc.)
├── apps/
│ └── docs/ # Storybook documentation site
├── package.json # Root workspace config
├── pnpm-workspace.yaml
├── turbo.json
└── tsconfig.base.json
Bootstrap Commands
# Initialize monorepo
mkdir my-design-system && cd my-design-system
pnpm init
pnpm add -D turbo -w
# Create workspace config
echo "packages:\n - 'packages/*'\n - 'apps/*'" > pnpm-workspace.yaml
turbo.json — task pipeline:
{
"$schema": "https://turbo.build/schema.json",
"pipeline": {
"build": { "dependsOn": ["^build"], "outputs": ["dist/**"] },
"dev": { "cache": false, "persistent": true },
"test": { "dependsOn": ["^build"] },
"lint": {}
}
}
Build Tooling Choice
| Tool | Best for | Notes |
|---|
| Vite + vite-plugin-dts | React/Vue components | Fast, ESM-first |
| tsup | Utility packages | Zero-config, dual CJS/ESM |
| Rollup | Fine-grained control | More config overhead |
Recommended packages/components/package.json:
{
"name": "@myds/components",
"version": "0.1.0",
"main": "./dist/index.cjs",
"module": "./dist/index.js",
"types": "./dist/index.d.ts",
"exports": {
".": {
"import": "./dist/index.js",
"require": "./dist/index.cjs",
"types": "./dist/index.d.ts"
}
},
"scripts": {
"build": "tsup src/index.ts --format cjs,esm --dts",
"dev": "tsup src/index.ts --format cjs,esm --dts --watch"
}
}
2. Design Tokens
Design tokens are the single source of truth for visual decisions.
Read references/tokens.md for the complete token schema, naming conventions,
CSS variable patterns, and multi-brand token examples.
Quick Start
# Install Style Dictionary (token transformation tool)
pnpm add -D style-dictionary -w
Token files live in packages/tokens/src/. Style Dictionary transforms them to CSS variables, JS/TS constants,
and platform-specific outputs (iOS, Android).
Core token categories: color, typography, spacing, border-radius, shadow, z-index, motion.
3. Component Development Standards
Every component should follow consistent conventions for long-term maintainability.
Read references/component-patterns.md for detailed patterns:
file structure, Props API design, compound components, polymorphic components, accessibility requirements,
and documentation templates.
Non-Negotiable Rules
- TypeScript first — all props typed with explicit interfaces, no
any
forwardRef for all leaf elements (React)aria-* attributes — never ship an inaccessible component- Controlled + Uncontrolled — support both patterns for form components
data-testid — include for E2E testability
Component File Structure
Button/
├── Button.tsx # Component implementation
├── Button.types.ts # Props interface & type exports
├── Button.test.tsx # Unit + interaction tests
├── Button.stories.tsx # Storybook stories
└── index.ts # Public barrel export
4. Storybook
Storybook is the primary documentation and development environment.
Read references/storybook-setup.md for full configuration:
addon setup, autodocs, MDX pages, controls, theming the Storybook UI, and deployment.
Bootstrap
cd apps/docs
pnpm dlx storybook@latest init
# Select React + Vite when prompted
Essential addons:
@storybook/addon-essentials (controls, actions, docs, viewport)@storybook/addon-a11y (accessibility audit)@storybook/addon-themes (theme switching)storybook-addon-pseudo-states (hover/focus/active states)
5. Theme System
Read references/theming.md for full theming architecture:
CSS custom properties strategy, dark mode implementation (media query vs. class-based),
ThemeProvider pattern for React, and Vue 3 provide/inject approach.
Core Concept
Tokens define semantic aliases that point to primitive values:
/* Primitive */
--color-blue-500: #3b82f6;
/* Semantic (theme-aware) */
[data-theme="light"] { --color-primary: var(--color-blue-500); }
[data-theme="dark"] { --color-primary: var(--color-blue-400); }
Components reference semantic tokens only — never primitives directly.
6. Testing Strategy
Read references/testing-strategy.md for the full pyramid:
unit tests (Vitest), interaction tests (Testing Library), visual regression (Chromatic/Percy),
and accessibility automation.
Test Pyramid for Component Libraries
[Visual Regression] ← Chromatic / Percy
[Interaction Tests] ← @testing-library/react
[Unit / Logic Tests] ← Vitest
Minimum bar per component:
- Renders without errors
- Props produce expected output
- Interactive states (hover, focus, disabled) work
- No critical a11y violations (axe-core)
7. Release Pipeline
Read references/release-pipeline.md for the complete release flow:
Changesets setup, versioning strategy, automated changelog, CI/CD pipeline, and npm publishing.
Tool: Changesets
pnpm add -D @changesets/cli -w
pnpm changeset init
Workflow:
pnpm changeset — create a changeset (describe changes)pnpm changeset version — bump versions + update CHANGELOG.mdpnpm changeset publish — publish to npm
Vue 3 Notes
Most patterns apply to Vue 3 with minor adaptations:
- Props: use
defineProps<T>() with TypeScript generics
expose() replaces React's forwardRef- Theme injection:
provide/inject replaces React Context
- Testing:
@vue/test-utils + Vitest
- See references/component-patterns.md for Vue-specific examples
Recommended Tech Stack Summary
| Layer | React | Vue 3 |
|---|
| Monorepo | pnpm + Turborepo | pnpm + Turborepo |
| Build | tsup / Vite | tsup / Vite |
| Tokens | Style Dictionary | Style Dictionary |
| Docs | Storybook 8 | Storybook 8 |
| Unit tests | Vitest + Testing Library | Vitest + @vue/test-utils |
| Visual regression | Chromatic | Chromatic |
| Release | Changesets | Changesets |
| CSS | CSS Modules / CSS-in-JS | CSS Modules / scoped SFC |
