Building a design system

oling, atomic updates, and immediate feedback loops. Product apps consume the system via workspace references during development.

• Token Pipeline: Implement a unidirectional token pipeline. Tokens are defined in a platform-agnostic format (JSON) and transformed into CSS variables, TypeScript constants, and Figma variables. This ensures strict parity between design and implementation.
• Headless Primitives: Base components on headless UI libraries (e.g., Radix UI, React Aria) rather than DOM-heavy wrappers. This delegates accessibility, focus management, and keyboard navigation to battle-tested primitives, allowing the design system to focus on styling and composition.
• Composition over Inheritance: Avoid monolithic components with massive prop APIs. Build components that compose smaller primitives. Use pattern libraries like class-variance-authority (CVA) to manage variant configurations safely.

2. Implementation Steps

Step A: Design Token Schema

Define tokens in a structured JSON schema. This serves as the source of truth.

// packages/tokens/src/tokens.json
{
  "color": {
    "brand": {
      "50": { "value": "#eff6ff" },
      "600": { "value": "#2563eb" }
    },
    "text": {
      "primary": { "value": "{color.neutral.900.value}" }
    }
  },
  "radius": {
    "md": { "value": "0.375rem" }
  }
}

Step B: Component Architecture with CVA and Slots

Components should be polymorphic, accessible, and type-safe. The following pattern uses class-variance-authority for variants and @radix-ui/react-slot for composition.

// packages/ui/src/components/button.tsx
import * as React from "react";
import { Slot } from "@radix-ui/react-slot";
import { cva, type VariantProps } from "class-variance-authority";
import { cn } from "../lib/utils";

// Variant configuration with strict type inference
const buttonVariants = cva(
  "inline-flex items-center justify-center whitespace-nowrap rounded-md text-sm font-medium ring-offset-background transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 disabled:pointer-events-none disabled:opacity-50",
  {
    variants: {
      variant: {
        primary: "bg-brand-600 text-white hover:bg-brand-500",
        secondary: "bg-secondary text-secondary-foreground hover:bg-secondary/80",
        ghost: "hover:bg-accent hover:text-accent-foreground",
      },
      size: {
        sm: "h-8 rounded-md px-3",
        md: "h-10 px-4 py-2",
        lg: "h-12 rounded-md px-8 text-base",
        icon: "h-10 w-10",
      },
    },
    defaultVariants: {
      variant: "primary",
      size: "md",
    },
  }
);

export interface ButtonProps
  extends React.ButtonHTMLAttributes<HTMLButtonElement>,
    VariantProps<typeof buttonVariants> {
  asChild?: boolean;
}

const Button = React.forwardRef<HTMLButtonElement, ButtonProps>(
  ({ className, variant, size, asChild = false, ...props }, ref) => {
    const Comp = asChild ? Slot : "button";
    return (
      <Comp
        className={cn(buttonVariants({ variant, size, className }))}
        ref={ref}
        {...props}
      />
    );
  }
);
Button.displayName = "Button";

export { Button, buttonVariants };

Rationale:

• asChild prop allows the button to render as a different element (e.g., Link from react-router) while retaining styles and accessibility attributes.
• cva provides compile-time validation of variants, preventing invalid combinations.
• forwardRef and displayName ensure compatibility with React DevTools and ref forwarding.

Step C: Documentation and Visual Regression

Integrate Storybook for interactive documentation. Configure Chromatic or Percy for automated visual regression testing. Every PR must pass visual diffs to prevent unintended style changes.

// packages/ui/src/stories/Button.stories.tsx
import type { Meta, StoryObj } from "@storybook/react";
import { Button } from "../components/button";

const meta = {
  title: "Components/Button",
  component: Button,
  tags: ["autodocs"],
  argTypes: {
    variant: { control: "select", options: ["primary", "secondary", "ghost"] },
    size: { control: "select", options: ["sm", "md", "lg", "icon"] },
  },
} satisfies Meta<typeof Button>;

export default meta;
type Story = StoryObj<typeof meta>;

export const Primary: Story = {
  args: { variant: "primary", children: "Button" },
};

3. CI/CD Integration

Automate publishing via semantic release. The pipeline should run linting, type checking, unit tests, and visual regression before publishing to the registry. Use changesets or similar tools to manage versioning and changelogs.

Pitfall Guide

1. The "Big Bang" Launch

Mistake: Attempting to build the entire system before releasing it to product teams. Impact: Development stalls, requirements drift, and adoption fails because teams are forced to migrate a massive codebase simultaneously. Best Practice: Adopt an incremental approach. Build core tokens and high-utility components first. Release early and iterate based on product team feedback.

2. API Bloat and Over-Engineering

Mistake: Creating components with dozens of props to handle every edge case. Impact: Components become difficult to use, type inference degrades, and internal complexity grows. Best Practice: Favor composition. If a component needs a specific layout, compose it using primitives rather than adding layout props to the component itself. Keep APIs minimal and predictable.

3. Ignoring Accessibility in the Pipeline

Mistake: Treating accessibility as a post-implementation checklist. Impact: Components fail WCAG standards, requiring costly retrofits. Best Practice: Integrate accessibility testing (e.g., axe-core) into the CI pipeline. Use headless primitives that enforce accessible patterns by default. Require a11y audits for all new components.

4. Token Drift

Mistake: Allowing product teams to define ad-hoc colors or spacing values that bypass the token system. Impact: The design system loses authority; visual consistency degrades. Best Practice: Enforce token usage via linting rules (e.g., stylelint rules that forbid hardcoded values). Automate token generation so that updating the token file propagates changes everywhere.

5. Versioning Nightmares

Mistake: Breaking changes in the design system cause cascading failures in dependent apps. Impact: Product teams delay upgrades, leading to fragmentation and security risks. Best Practice: Adhere strictly to Semantic Versioning. Use automated dependency management tools to keep apps updated. Provide codemods for breaking changes to automate migration.

6. Lack of Governance Model

Mistake: No clear process for contributions, reviews, or decision-making. Impact: The system becomes chaotic; quality varies; trust erodes. Best Practice: Establish a design system council with representatives from design and engineering. Define contribution guidelines, review SLAs, and a roadmap process. Treat the system as a product with a dedicated owner.

7. Poor Developer Experience (DX)

Mistake: Documentation is outdated, setup is complex, or error messages are unhelpful. Impact: Product teams avoid the system, building custom solutions instead. Best Practice: Prioritize DX. Ensure documentation is auto-generated and linked to code. Provide clear error boundaries and helpful console warnings. Measure adoption metrics to identify friction points.

Production Bundle

Action Checklist

• Define Token Schema: Establish a JSON-based token structure for colors, typography, spacing, and radii.
• Initialize Monorepo: Set up Turborepo or Nx with packages for tokens, ui, and docs.
• Implement Core Primitives: Build foundational components (Button, Input, Card) using CVA and headless libraries.
• Configure Storybook: Integrate Storybook with TypeScript, Tailwind CSS, and accessibility add-ons.
• Set Up CI Pipeline: Configure linting, type checking, unit tests, and visual regression testing.
• Establish Governance: Create contribution guidelines, code of conduct, and a review process.
• Pilot Adoption: Onboard one product team to validate the system and gather feedback.
• Automate Publishing: Implement semantic release with changesets for version management.

Decision Matrix

Scenario	Recommended Approach	Why	Cost Impact
Early-stage Startup	Shared Component Library + CSS Modules	Low overhead, fast iteration, minimal infrastructure	Low
Multi-Brand Enterprise	Design Tokens + Headless Primitives + Monorepo	Enables theming, strict consistency, scalable governance	High initial, Low long-term
Framework Agnostic Needs	Web Components + Design Tokens	Interoperability across React, Vue, Angular, etc.	Medium
Rapid Prototyping	Utility-First CSS (Tailwind) + Shared Config	Speed of development, easy customization	Low
Regulated Industry	Strict Token Enforcement + Automated A11y Testing	Compliance requirements, auditability, risk reduction	Medium

Configuration Template

turbo.json for Monorepo Orchestration:

{
  "$schema": "https://turbo.build/schema.json",
  "globalDependencies": ["**/.env.*local"],
  "tasks": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": ["dist/**", ".next/**", "!.next/cache/**"]
    },
    "lint": {
      "dependsOn": ["^lint"]
    },
    "dev": {
      "cache": false,
      "persistent": true
    },
    "storybook": {
      "cache": false,
      "persistent": true
    },
    "test": {
      "dependsOn": ["build"]
    }
  }
}

packages/ui/package.json Scripts:

{
  "name": "@acme/ui",
  "version": "0.0.1",
  "main": "./dist/index.js",
  "types": "./dist/index.d.ts",
  "scripts": {
    "build": "tsup src/index.ts --dts --format cjs,esm",
    "lint": "eslint src/",
    "dev": "tsup src/index.ts --watch --dts",
    "storybook": "storybook dev -p 6006",
    "test": "vitest run",
    "clean": "rm -rf dist node_modules"
  },
  "dependencies": {
    "@radix-ui/react-slot": "^1.0.2",
    "class-variance-authority": "^0.7.0",
    "clsx": "^2.0.0",
    "tailwind-merge": "^1.14.0"
  },
  "devDependencies": {
    "tsup": "^7.2.0",
    "typescript": "^5.2.0",
    "@types/react": "^18.2.0",
    "react": "^18.2.0"
  }
}

Quick Start Guide

1. Initialize Monorepo:

   npx create-turbo@latest design-system
   cd design-system
   pnpm install
   

2. Add UI Package Dependencies:

   cd packages
   mkdir ui && cd ui
   pnpm init
   pnpm add react react-dom @radix-ui/react-slot class-variance-authority clsx tailwind-merge
   pnpm add -D typescript @types/react tsup tailwindcss postcss autoprefixer
   

3. Create First Component: Create packages/ui/src/button.tsx with the Button implementation from the Core Solution. Export it from packages/ui/src/index.ts.

4. Configure Build: Add tsup configuration to package.json scripts as shown in the Configuration Template. Run pnpm build to verify output.

5. Integrate with App: In your app package, import the button:

   import { Button } from "@acme/ui";
   export default function Home() {
     return <Button variant="primary">Get Started</Button>;
   }
   

   Run pnpm dev in the root to see the component rendered with hot reloading.