Skip to main content

Building Design Systems: Component Architecture, Storybook, and Design Tokens

Master design system architecture with component libraries, Storybook documentation, and design tokens. Learn to build scalable, maintainable design systems.

Table of Contents

Introduction

Design systems have become the cornerstone of modern frontend development. They provide consistency, scalability, and maintainability across applications, enabling teams to build faster while maintaining high quality standards. However, building a design system from scratch can be overwhelming—where do you start? How do you structure components? What tools should you use?

A well-architected design system goes beyond a simple component library. It includes design tokens for consistent styling, comprehensive documentation for developer experience, and a clear architecture that scales with your team and products. Whether you’re building a design system for a single application or an entire organization, understanding these fundamentals is crucial.

This comprehensive guide will teach you how to build production-ready design systems. You’ll learn component architecture patterns, how to implement design tokens, set up Storybook for documentation, and establish best practices that ensure your design system remains maintainable and scalable. We’ll cover everything from foundational concepts to advanced patterns used by companies like Material-UI, Ant Design, and Chakra UI.

By the end of this guide, you’ll have the knowledge and practical examples needed to build a design system that your team will actually want to use—one that improves productivity, reduces bugs, and creates a consistent user experience across all your applications.

Understanding Design Systems

Before diving into implementation, it’s essential to understand what a design system is and why it matters. A design system is more than just a collection of reusable components—it’s a living, evolving set of standards, guidelines, and tools that ensure consistency across products.

What Makes a Design System?

A complete design system includes:

  1. Design Tokens: The atomic values that define your design language (colors, spacing, typography, etc.)
  2. Component Library: Reusable UI components built on those tokens
  3. Documentation: Clear guidelines on how to use components and patterns
  4. Design Guidelines: Visual and interaction patterns that define your brand
  5. Tools: Development tools that make using the system easy

Benefits of Design Systems

Design systems provide numerous benefits:

  • Consistency: Ensures UI consistency across applications and teams
  • Efficiency: Reduces development time by reusing components
  • Quality: Fewer bugs through tested, reusable components
  • Scalability: Makes it easier to onboard new developers
  • Maintainability: Single source of truth for design decisions

💡 Pro Tip: Start small with your design system. Begin with the most commonly used components (buttons, inputs, cards) and expand gradually. A small, well-documented system is better than a large, incomplete one.

Design System vs Component Library

It’s important to distinguish between a design system and a component library:

  • Component Library: A collection of reusable UI components
  • Design System: A comprehensive system that includes components, design tokens, documentation, guidelines, and tools

A component library is part of a design system, but a design system encompasses much more. Think of it as the difference between a toolbox and a complete workshop.

Component Architecture Fundamentals

Component architecture is the foundation of any design system. Well-structured components are composable, maintainable, and easy to understand. Let’s explore the key principles and patterns.

Atomic Design Principles

Atomic Design, introduced by Brad Frost, breaks components into five levels:

  1. Atoms: Basic building blocks (buttons, inputs, labels)
  2. Molecules: Simple combinations of atoms (search form, navigation item)
  3. Organisms: Complex UI components (header, product card)
  4. Templates: Page-level layouts without content
  5. Pages: Specific instances of templates with real content

While you don’t need to strictly follow this hierarchy, understanding it helps structure your components logically.

Component Structure

✅ Best Practice: Organize components with a consistent structure:

components/
  Button/
    Button.tsx          # Main component
    Button.test.tsx     # Tests
    Button.stories.tsx  # Storybook stories
    Button.types.ts     # TypeScript types
    index.ts            # Public API

Here’s a well-structured Button component example:

Button.types.ts
export type ButtonVariant = "primary" | "secondary" | "danger" | "ghost";
export type ButtonSize = "sm" | "md" | "lg";


export type ButtonProps = {
  variant?: ButtonVariant;
  size?: ButtonSize;
  children: React.ReactNode;
  onClick?: () => void;
  disabled?: boolean;
  loading?: boolean;
  fullWidth?: boolean;
  type?: "button" | "submit" | "reset";
  "aria-label"?: string;
};
Button.tsx
import React from 'react';
import { ButtonProps, ButtonVariant, ButtonSize } from './Button.types';
import { buttonStyles, sizeStyles, variantStyles } from './Button.styles';


export const Button: React.FC<ButtonProps> = ({
  variant = 'primary',
  size = 'md',
  children,
  onClick,
  disabled = false,
  loading = false,
  fullWidth = false,
  type = 'button',
  'aria-label': ariaLabel,
  ...props
}) => {
  const baseStyles = buttonStyles;
  const variantStyle = variantStyles[variant];
  const sizeStyle = sizeStyles[size];


  const className = [
    baseStyles,
    variantStyle,
    sizeStyle,
    fullWidth && 'w-full',
    disabled && 'opacity-50 cursor-not-allowed',
    loading && 'cursor-wait'
  ]
    .filter(Boolean)
    .join(' ');


  return (
    <button
      type={type}
      className={className}
      onClick={onClick}
      disabled={disabled || loading}
      aria-label={ariaLabel || (loading ? 'Loading' : undefined)}
      aria-busy={loading}
      {...props}
    >
      {loading ? (
        <>
          <span className="spinner" aria-hidden="true" />
          <span className="sr-only">Loading</span>
        </>
      ) : (
        children
      )}
    </button>
  );
};

Composition Patterns

Composition is key to building flexible components. Instead of creating components with every possible prop combination, use composition to combine smaller pieces:

// ❌ Anti-pattern: Too many props
<Button
  variant="primary"
  size="lg"
  icon="arrow-right"
  iconPosition="right"
  loading={true}
  badge="3"
  badgePosition="top-right"
/>


// ✅ Better: Use composition
<Button variant="primary" size="lg">
  <ButtonIcon name="arrow-right" />
  Submit
  <ButtonBadge count={3} />
</Button>

Compound Components Pattern

For complex components, use the compound components pattern:

// Card.tsx - Compound component example
import React, { createContext, useContext } from 'react';


type CardContextType = {
  variant?: 'default' | 'outlined' | 'elevated';
};


const CardContext = createContext<CardContextType>({});


const useCardContext = () => {
  const context = useContext(CardContext);
  return context;
};


type CardProps = {
  variant?: 'default' | 'outlined' | 'elevated';
  children: React.ReactNode;
  className?: string;
};


const CardRoot: React.FC<CardProps> = ({
  variant = 'default',
  children,
  className
}) => {
  return (
    <CardContext.Provider value={{ variant }}>
      <div className={`card card-${variant} ${className || ''}`}>
        {children}
      </div>
    </CardContext.Provider>
  );
};


const CardHeader: React.FC<{ children: React.ReactNode }> = ({ children }) => {
  return <div className="card-header">{children}</div>;
};


const CardBody: React.FC<{ children: React.ReactNode }> = ({ children }) => {
  return <div className="card-body">{children}</div>;
};


const CardFooter: React.FC<{ children: React.ReactNode }> = ({ children }) => {
  return <div className="card-footer">{children}</div>;
};


// Export as compound component
export const Card = Object.assign(CardRoot, {
  Header: CardHeader,
  Body: CardBody,
  Footer: CardFooter,
});


// Usage:
// <Card variant="elevated">
//   <Card.Header>Title</Card.Header>
//   <Card.Body>Content</Card.Body>
//   <Card.Footer>Actions</Card.Footer>
// </Card>

Polymorphic Components

Polymorphic components allow a component to render as different HTML elements while maintaining type safety:

PolymorphicButton.tsx
import React from 'react';


type PolymorphicButtonProps<T extends React.ElementType = 'button'> = {
  as?: T;
  children: React.ReactNode;
  variant?: 'primary' | 'secondary';
} & React.ComponentPropsWithoutRef<T>;


export function PolymorphicButton<T extends React.ElementType = 'button'>({
  as,
  children,
  variant = 'primary',
  ...props
}: PolymorphicButtonProps<T>) {
  const Component = as || 'button';


  return (
    <Component className={`btn btn-${variant}`} {...props}>
      {children}
    </Component>
  );
}


// Usage:
// <PolymorphicButton as="a" href="/link">Link Button</PolymorphicButton>
// <PolymorphicButton as="div" onClick={handleClick}>Div Button</PolymorphicButton>

Design Tokens: The Foundation

Design tokens are the atomic values that define your design language. They’re the single source of truth for colors, spacing, typography, shadows, and other design decisions. When implemented correctly, design tokens ensure consistency and make it easy to maintain or update your design system.

What Are Design Tokens?

Design tokens are name-value pairs that represent design decisions. Instead of hardcoding values like #007bff or 16px, you use semantic names like color.primary or spacing.md.

Token Categories

Design tokens typically fall into these categories:

  1. Color: Primary, secondary, semantic colors, neutrals
  2. Typography: Font families, sizes, weights, line heights
  3. Spacing: Consistent spacing scale
  4. Shadows: Elevation and depth
  5. Border Radius: Corner rounding
  6. Motion: Animation durations and easing functions

Implementing Design Tokens

Here’s how to structure design tokens in TypeScript:

tokens/colors.ts
export const colors = {
  // Primary palette
  primary: {
    50: "#f0f9ff",
    100: "#e0f2fe",
    200: "#bae6fd",
    300: "#7dd3fc",
    400: "#38bdf8",
    500: "#0ea5e9", // Base primary color
    600: "#0284c7",
    700: "#0369a1",
    800: "#075985",
    900: "#0c4a6e",
  },


  // Semantic colors
  success: {
    500: "#10b981",
    600: "#059669",
  },
  error: {
    500: "#ef4444",
    600: "#dc2626",
  },
  warning: {
    500: "#f59e0b",
    600: "#d97706",
  },


  // Neutral colors
  gray: {
    50: "#f9fafb",
    100: "#f3f4f6",
    200: "#e5e7eb",
    300: "#d1d5db",
    400: "#9ca3af",
    500: "#6b7280",
    600: "#4b5563",
    700: "#374151",
    800: "#1f2937",
    900: "#111827",
  },
} as const;


// tokens/spacing.ts
export const spacing = {
  0: "0",
  1: "0.25rem", // 4px
  2: "0.5rem", // 8px
  3: "0.75rem", // 12px
  4: "1rem", // 16px
  5: "1.25rem", // 20px
  6: "1.5rem", // 24px
  8: "2rem", // 32px
  10: "2.5rem", // 40px
  12: "3rem", // 48px
  16: "4rem", // 64px
  20: "5rem", // 80px
  24: "6rem", // 96px
} as const;


// tokens/typography.ts
export const typography = {
  fontFamily: {
    sans: ["Inter", "system-ui", "sans-serif"],
    mono: ["Fira Code", "monospace"],
  },
  fontSize: {
    xs: "0.75rem", // 12px
    sm: "0.875rem", // 14px
    base: "1rem", // 16px
    lg: "1.125rem", // 18px
    xl: "1.25rem", // 20px
    "2xl": "1.5rem", // 24px
    "3xl": "1.875rem", // 30px
    "4xl": "2.25rem", // 36px
  },
  fontWeight: {
    normal: 400,
    medium: 500,
    semibold: 600,
    bold: 700,
  },
  lineHeight: {
    tight: 1.25,
    normal: 1.5,
    relaxed: 1.75,
  },
} as const;


// tokens/index.ts - Export all tokens
export { colors } from "./colors";
export { spacing } from "./spacing";
export { typography } from "./typography";
export { shadows } from "./shadows";
export { borderRadius } from "./borderRadius";
export { motion } from "./motion";

Using Tokens in CSS

For CSS-based projects, you can use CSS custom properties:

tokens.css
:root {
  /* Colors */
  --color-primary-500: #0ea5e9;
  --color-primary-600: #0284c7;
  --color-success-500: #10b981;
  --color-error-500: #ef4444;


  /* Spacing */
  --spacing-1: 0.25rem;
  --spacing-2: 0.5rem;
  --spacing-4: 1rem;
  --spacing-6: 1.5rem;


  /* Typography */
  --font-family-sans: "Inter", system-ui, sans-serif;
  --font-size-base: 1rem;
  --font-weight-medium: 500;


  /* Shadows */
  --shadow-sm: 0 1px 2px 0 rgba(0, 0, 0, 0.05);
  --shadow-md: 0 4px 6px -1px rgba(0, 0, 0, 0.1);
  --shadow-lg: 0 10px 15px -3px rgba(0, 0, 0, 0.1);
}


/* Usage in components */
.button {
  background-color: var(--color-primary-500);
  padding: var(--spacing-2) var(--spacing-4);
  font-family: var(--font-family-sans);
  box-shadow: var(--shadow-md);
}

Using Tokens in React/TypeScript

For React components, use tokens directly:

Button.styles.ts
import { colors, spacing, typography, shadows } from "@/tokens";


export const buttonStyles = {
  base: {
    fontFamily: typography.fontFamily.sans,
    fontWeight: typography.fontWeight.medium,
    borderRadius: "0.375rem",
    border: "none",
    cursor: "pointer",
    transition: "all 0.2s ease",
  },
  variants: {
    primary: {
      backgroundColor: colors.primary[500],
      color: "white",
      "&:hover": {
        backgroundColor: colors.primary[600],
      },
    },
    secondary: {
      backgroundColor: colors.gray[200],
      color: colors.gray[900],
      "&:hover": {
        backgroundColor: colors.gray[300],
      },
    },
  },
  sizes: {
    sm: {
      padding: `${spacing[1]} ${spacing[2]}`,
      fontSize: typography.fontSize.sm,
    },
    md: {
      padding: `${spacing[2]} ${spacing[4]}`,
      fontSize: typography.fontSize.base,
    },
    lg: {
      padding: `${spacing[3]} ${spacing[6]}`,
      fontSize: typography.fontSize.lg,
    },
  },
};

Token Naming Conventions

✅ Best Practice: Use semantic naming that describes purpose, not appearance:

// ❌ Bad: Describes appearance
const tokens = {
  blue500: "#0ea5e9",
  smallSpacing: "0.5rem",
};


// ✅ Good: Describes purpose
const tokens = {
  color: {
    primary: "#0ea5e9",
    interactive: "#0ea5e9",
  },
  spacing: {
    xs: "0.5rem",
    sm: "0.75rem",
  },
};

⚠️ Important: Design tokens should be semantic, not literal. If your brand color changes from blue to green, you shouldn’t need to rename tokens—just update their values.

Building with Storybook

Storybook is the industry standard for building and documenting component libraries. It provides an isolated environment for developing components, writing documentation, and testing different states.

Setting Up Storybook

Install Storybook in your project:

Terminal window
# For React projects
npx storybook@latest init


# This will:
# 1. Install dependencies
# 2. Create .storybook configuration folder
# 3. Add example stories
# 4. Add npm scripts

Basic Story Structure

A story is a component state. Here’s a basic example:

Button.stories.tsx
import type { Meta, StoryObj } from "@storybook/react";
import { Button } from "./Button";


const meta: Meta<typeof Button> = {
  title: "Components/Button",
  component: Button,
  parameters: {
    layout: "centered",
  },
  tags: ["autodocs"],
  argTypes: {
    variant: {
      control: "select",
      options: ["primary", "secondary", "danger", "ghost"],
      description: "Visual style variant",
    },
    size: {
      control: "select",
      options: ["sm", "md", "lg"],
      description: "Button size",
    },
    disabled: {
      control: "boolean",
      description: "Disable button interaction",
    },
    loading: {
      control: "boolean",
      description: "Show loading state",
    },
  },
};


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


// Default story
export const Default: Story = {
  args: {
    children: "Button",
    variant: "primary",
    size: "md",
  },
};


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


export const Secondary: Story = {
  args: {
    children: "Secondary Button",
    variant: "secondary",
  },
};


// Size stories
export const Small: Story = {
  args: {
    children: "Small Button",
    size: "sm",
  },
};


export const Large: Story = {
  args: {
    children: "Large Button",
    size: "lg",
  },
};


// State stories
export const Disabled: Story = {
  args: {
    children: "Disabled Button",
    disabled: true,
  },
};


export const Loading: Story = {
  args: {
    children: "Loading Button",
    loading: true,
  },
};


// Playground story (allows testing all combinations)
export const Playground: Story = {
  args: {
    children: "Playground",
  },
};

Advanced Story Patterns

Story Composition

Compose complex stories from simpler ones:

Card.stories.tsx
import { Card } from './Card';


export const WithHeader: Story = {
  render: () => (
    <Card variant="elevated">
      <Card.Header>
        <h3>Card Title</h3>
      </Card.Header>
      <Card.Body>
        <p>Card content goes here</p>
      </Card.Body>
      <Card.Footer>
        <Button>Action</Button>
      </Card.Footer>
    </Card>
  ),
};

Interactive Stories with Actions

Use actions to test component interactions:

import { fn } from "@storybook/test";
import { Button } from "./Button";


export const WithClick: Story = {
  args: {
    children: "Click me",
    onClick: fn(), // Logs clicks in Storybook
  },
};

Decorators for Context

Use decorators to wrap stories with providers or context:

import { ThemeProvider } from '../ThemeProvider';


export default {
  decorators: [
    (Story) => (
      <ThemeProvider theme="dark">
        <Story />
      </ThemeProvider>
    ),
  ],
};

Documentation with MDX

Storybook supports MDX for rich documentation:

Button.mdx
import { Meta, Story, Canvas, Controls } from '@storybook/blocks';
import \* as ButtonStories from './Button.stories';


<Meta of={ButtonStories} />


# Button


The Button component is used to trigger actions and navigate users.


## Usage


Buttons communicate actions that users can take. They're typically placed throughout your UI, in places like:


- Dialogs
- Forms
- Toolbars
- Cards


## Variants


<Canvas of={ButtonStories.Primary} />
<Canvas of={ButtonStories.Secondary} />


## Sizes


Buttons come in three sizes: small, medium (default), and large.


<Canvas of={ButtonStories.Small} />
<Canvas of={ButtonStories.Large} />


## Accessibility


- Buttons should have descriptive labels
- Use `aria-label` for icon-only buttons
- Disabled buttons should not be focusable
- Loading states should use `aria-busy`


## API Reference


<Controls of={ButtonStories.Playground} />

Storybook Addons

Essential addons for design systems:

.storybook/main.ts
export default {
  addons: [
    "@storybook/addon-essentials", // Includes docs, controls, actions, etc.
    "@storybook/addon-a11y", // Accessibility testing
    "@storybook/addon-viewport", // Test responsive designs
    "@storybook/addon-designs", // Link to Figma designs
    "storybook-addon-designs", // Design tokens visualization
  ],
};

Visual Testing

Use Chromatic or similar tools for visual regression testing:

Button.visual-test.tsx
import { expect, test } from "@playwright/test";
import { Button } from "./Button";


test("Button visual regression", async ({ page }) => {
  await page.goto("http://localhost:6006/?path=/story/button--default");
  await expect(page).toHaveScreenshot("button-default.png");
});

Component Documentation Best Practices

Good documentation is what separates a component library from a design system. Without clear documentation, developers won’t know how to use your components effectively.

Writing Component Documentation

✅ Best Practice: Include these sections in every component’s documentation:

  1. Overview: What the component does and when to use it
  2. Examples: Real-world usage examples
  3. Props API: Complete prop documentation with types
  4. Accessibility: Accessibility considerations and requirements
  5. Best Practices: Do’s and don’ts
  6. Related Components: Links to related components

Example Documentation Template

# Button


## Overview


The Button component triggers actions and navigates users. Use buttons for primary actions, form submissions, and navigation.


## When to Use


- ✅ Triggering actions (submit, save, delete)
- ✅ Navigation to other pages
- ✅ Opening modals or dialogs


## When Not to Use


- ❌ Secondary actions (use links instead)
- ❌ Decorative elements (use styled divs)
- ❌ Multiple actions in a row (consider a button group)


## Examples


### Basic Usage


\`\`\`tsx
import { Button } from '@design-system/button';


<Button onClick={handleClick}>Click me</Button>
\`\`\`


### With Variants


\`\`\`tsx


<Button variant="primary">Primary</Button>
<Button variant="secondary">Secondary</Button>
<Button variant="danger">Delete</Button>
\`\`\`


## Props


| Prop     | Type                                            | Default   | Description                |
| -------- | ----------------------------------------------- | --------- | -------------------------- |
| variant  | 'primary' \| 'secondary' \| 'danger' \| 'ghost' | 'primary' | Visual style variant       |
| size     | 'sm' \| 'md' \| 'lg'                            | 'md'      | Button size                |
| disabled | boolean                                         | false     | Disable button interaction |
| loading  | boolean                                         | false     | Show loading spinner       |


## Accessibility


- Buttons must have accessible labels
- Use `aria-label` for icon-only buttons
- Disabled buttons should not be focusable
- Loading states should use `aria-busy="true"`


## Related Components


- [Link](/components/link) - For navigation without actions
- [IconButton](/components/icon-button) - For icon-only buttons
- [ButtonGroup](/components/button-group) - For multiple related buttons

Code Examples in Documentation

Include practical, copy-paste ready examples:

// ✅ Good: Complete, runnable example
import { Button } from '@design-system/button';
import { useState } from 'react';


function Example() {
  const [loading, setLoading] = useState(false);


  const handleSubmit = async () => {
    setLoading(true);
    await submitForm();
    setLoading(false);
  };


  return (
    <Button
      onClick={handleSubmit}
      loading={loading}
      disabled={loading}
    >
      Submit Form
    </Button>
  );
}


// ❌ Bad: Incomplete example missing imports and context
<Button onClick={handleClick}>Submit</Button>

Design System Organization

How you organize your design system codebase significantly impacts maintainability and developer experience. Let’s explore effective organization patterns.

Monorepo Structure

Many design systems use monorepos to manage multiple packages:

design-system/
├── packages/
│   ├── tokens/           # Design tokens package
│   ├── components/       # React components
│   ├── icons/            # Icon library
│   ├── utils/            # Shared utilities
│   └── docs/             # Documentation site
├── apps/
│   ├── storybook/        # Storybook instance
│   └── playground/       # Component playground
├── package.json
└── pnpm-workspace.yaml

Package Structure

Each package should have a clear structure:

components/
├── src/
│   ├── Button/
│   │   ├── Button.tsx
│   │   ├── Button.test.tsx
│   │   ├── Button.stories.tsx
│   │   ├── Button.types.ts
│   │   └── index.ts
│   ├── Input/
│   └── index.ts          # Barrel export
├── package.json
└── tsconfig.json

Barrel Exports

Use barrel exports for clean imports:

components/src/index.ts
export { Button } from "./Button";
export type { ButtonProps } from "./Button/Button.types";


export { Input } from "./Input";
export type { InputProps } from "./Input/Input.types";


// Usage:
// import { Button, Input } from '@design-system/components';

TypeScript Configuration

Proper TypeScript setup ensures type safety across packages:

tsconfig.json
{
  "compilerOptions": {
    "target": "ES2020",
    "module": "ESNext",
    "lib": ["ES2020", "DOM", "DOM.Iterable"],
    "jsx": "react-jsx",
    "declaration": true,
    "declarationMap": true,
    "outDir": "./dist",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist", "**/*.test.ts", "**/*.stories.tsx"]
}

Versioning and Distribution

Design systems need versioning strategies and distribution methods that allow consumers to adopt updates safely.

Semantic Versioning

Follow Semantic Versioning (SemVer):

  • MAJOR: Breaking changes (1.0.0 → 2.0.0)
  • MINOR: New features, backward compatible (1.0.0 → 1.1.0)
  • PATCH: Bug fixes, backward compatible (1.0.0 → 1.0.1)

Publishing Packages

Use a tool like Changesets for version management:

Terminal window
# Install changesets
pnpm add -D @changesets/cli


# Initialize
pnpm changeset init


# Create a changeset
pnpm changeset


# Version packages
pnpm changeset version


# Publish
pnpm changeset publish

Distribution Methods

npm Package

package.json
{
  "name": "@your-org/design-system",
  "version": "1.0.0",
  "main": "./dist/index.js",
  "module": "./dist/index.esm.js",
  "types": "./dist/index.d.ts",
  "exports": {
    ".": {
      "import": "./dist/index.esm.js",
      "require": "./dist/index.js",
      "types": "./dist/index.d.ts"
    },
    "./styles": "./dist/styles.css"
  },
  "files": ["dist"]
}

CDN Distribution

For CDN usage, provide UMD builds:

// Build configuration for UMD
export default {
  input: "src/index.ts",
  output: {
    file: "dist/design-system.umd.js",
    format: "umd",
    name: "DesignSystem",
    globals: {
      react: "React",
      "react-dom": "ReactDOM",
    },
  },
};

Changelog Management

Maintain a clear changelog:

# Changelog


## [1.1.0] - 2024-12-25


### Added


- New `Card` component
- Support for dark mode in Button component


### Changed


- Improved Button accessibility
- Updated design tokens


### Fixed


- Fixed Input focus styles
- Resolved TypeScript type errors


## [1.0.0] - 2024-12-01


### Added


- Initial release
- Button, Input, Card components
- Design tokens package

Common Pitfalls and How to Avoid Them

Building design systems comes with common pitfalls. Learning from others’ mistakes helps you avoid them.

Pitfall 1: Over-Engineering Components

❌ Problem: Creating components with too many props and edge cases

// ❌ Bad: Too many props, hard to maintain
<Button
  variant="primary"
  size="lg"
  icon="arrow-right"
  iconPosition="right"
  loading={true}
  loadingText="Saving..."
  badge="3"
  badgePosition="top-right"
  tooltip="Click to save"
  tooltipPosition="top"
  fullWidth={true}
  rounded={true}
  shadow={true}
/>

✅ Solution: Use composition and keep components focused

// ✅ Good: Simple, composable
<Button variant="primary" size="lg" fullWidth>
  <ButtonIcon name="arrow-right" />
  Save
  <ButtonBadge count={3} />
</Button>

Pitfall 2: Inconsistent Naming

❌ Problem: Mixed naming conventions confuse developers

// ❌ Bad: Inconsistent naming
<Button primary />
<Input isDisabled />
<Card outlined />

✅ Solution: Establish and follow naming conventions

// ✅ Good: Consistent naming
<Button variant="primary" />
<Input disabled />
<Card variant="outlined" />

Pitfall 3: Missing Accessibility

❌ Problem: Components that aren’t accessible

// ❌ Bad: Missing accessibility
<button onClick={handleClick}>
  <Icon name="close" />
</button>

✅ Solution: Build accessibility in from the start

// ✅ Good: Accessible
<button
  onClick={handleClick}
  aria-label="Close dialog"
  type="button"
>
  <Icon name="close" aria-hidden="true" />
</button>

Pitfall 4: Poor Documentation

❌ Problem: Components without usage examples or prop documentation

✅ Solution: Document everything with examples

  • Include usage examples for every component
  • Document all props with types and descriptions
  • Provide accessibility guidelines
  • Show common patterns and anti-patterns

Pitfall 5: Tight Coupling

❌ Problem: Components that depend on specific implementations

// ❌ Bad: Tightly coupled to specific router
import { useRouter } from "next/router";


export function Button({ href, ...props }) {
  const router = useRouter();
  // ...
}

✅ Solution: Make components framework-agnostic when possible

// ✅ Good: Accepts render prop or children
export function Button({
  href,
  as: Component = 'button',
  ...props
}) {
  return <Component href={href} {...props} />;
}

Pitfall 6: Ignoring Performance

❌ Problem: Components that cause unnecessary re-renders

✅ Solution: Optimize with React.memo, useMemo, and useCallback when needed

// ✅ Good: Optimized component
export const Button = React.memo<ButtonProps>(({
  onClick,
  children,
  ...props
}) => {
  const handleClick = useCallback((e: React.MouseEvent) => {
    onClick?.(e);
  }, [onClick]);


  return (
    <button onClick={handleClick} {...props}>
      {children}
    </button>
  );
});

💡 Pro Tip: Don’t optimize prematurely. Measure first, then optimize based on actual performance issues. Check out our guide on React performance optimization for more details.

Conclusion

Building a design system is a journey that requires careful planning, consistent execution, and continuous improvement. By following the principles and patterns outlined in this guide, you’ll create a design system that:

  • Scales with your team and products
  • Maintains consistency across applications
  • Improves developer experience with clear documentation
  • Reduces bugs through reusable, tested components
  • Accelerates development by eliminating repetitive work

Remember, a design system is never “done”—it evolves with your products and team needs. Start small, document everything, gather feedback, and iterate. The best design systems are those that developers actually want to use.

Key Takeaways

  1. Component Architecture: Use composition, compound components, and clear structure
  2. Design Tokens: Build on semantic tokens as your foundation
  3. Documentation: Storybook and MDX make documentation part of development
  4. Organization: Clear structure and versioning enable maintainability
  5. Best Practices: Avoid common pitfalls through planning and consistency

Next Steps

  • Set up Storybook in your project
  • Define your design tokens
  • Build your first component with documentation
  • Establish versioning and distribution strategy
  • Gather feedback from your team

Additional Resources

Start building your design system today, and remember: consistency, documentation, and developer experience are the keys to success.