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

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

1. TypeScript first — all props typed with explicit interfaces, no any
2. forwardRef for all leaf elements (React)
3. aria-* attributes — never ship an inaccessible component
4. Controlled + Uncontrolled — support both patterns for form components
5. 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:
1. pnpm changeset — create a changeset (describe changes)
2. pnpm changeset version — bump versions + update CHANGELOG.md
3. pnpm 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