design-systems

name: design-systems description: "Comprehensive design system guidelines for building consistent, accessible, and scalable component libraries. Use when creating design tokens, building component libraries, implementing design systems, setting up theming architecture, or establishing UI governance processes."

Design Systems Best Practices

Guidelines for creating and maintaining design systems that ensure visual consistency, accessibility compliance, and scalable component architecture across digital products.

Workflow: Setting Up a Design System

Audit existing UI — Inventory current components, colors, typography, and spacing across the product to identify inconsistencies and reusable patterns.
Define design tokens — Establish primitive tokens (colors, spacing, typography, shadows) as CSS custom properties or a token format (e.g., Style Dictionary) that serves as the single source of truth.
Build foundational components — Create atomic components (Button, Input, Text, Icon) that consume design tokens and expose a clear props API with TypeScript types.
Compose patterns and layouts — Assemble atomic components into higher-order patterns (forms, cards, navigation) with documented usage guidelines.
Set up documentation and Storybook — Configure Storybook with stories for every component variant, state, and accessibility annotation. Publish as a living style guide.
Integrate testing and governance — Add visual regression tests (e.g., Chromatic), accessibility linting (e.g., axe-core), and a contribution/review process for new components.
Ship and iterate — Publish the library as a versioned package, gather consumer feedback, and run regular accessibility and performance audits.

Foundation Elements

Color System

Define primary, secondary, and accent colors
Include semantic colors for success, warning, error, info states
Ensure all color combinations meet WCAG contrast requirements
Document color usage guidelines and contexts
Provide light and dark mode variants

Typography

Establish a type scale with consistent ratios
Define font families for headings and body text
Set line heights and letter spacing standards
Document font weights and their usage
Ensure readability across screen sizes

Spacing System

Define consistent spacing scale (4px, 8px, 16px, 24px, etc.)
Create layout primitives for common patterns
Document margin and padding conventions
Ensure responsive spacing behavior
Use CSS custom properties for maintainability

Icons and Imagery

Maintain consistent icon style and sizing
Define icon grid and stroke weights
Document icon naming conventions
Optimize assets for web performance
Provide multiple formats when needed (SVG, PNG)

Component Architecture

Component Structure

Create atomic, reusable components
Define clear component APIs (props/attributes)
Document variants and states
Ensure components are accessible by default
Provide clear naming conventions

Component States

Default state
Hover state
Focus state (keyboard navigation)
Active/pressed state
Disabled state
Loading state
Error state

Component Variants

Size variants (small, medium, large)
Color/theme variants
Layout variants
Contextual variants

Accessibility Requirements

Follow WCAG 2.1 AA guidelines minimum
Use semantic HTML elements
Provide ARIA labels where needed
Ensure keyboard navigation
Test with screen readers
Maintain color contrast ratios
Support reduced motion preferences

Documentation Standards

Component Documentation

Purpose and use cases
Props/API reference
Code examples
Do's and don'ts
Accessibility notes
Related components

Pattern Documentation

When to use
Anatomy breakdown
Behavior specifications
Responsive considerations
Edge cases

Implementation Guidelines

CSS Architecture

Use CSS custom properties for tokens
Implement utility classes for common patterns
Follow BEM or similar naming convention
Ensure specificity is manageable
Support theming and customization

Component Libraries

Framework-agnostic when possible
Tree-shakeable exports
TypeScript support
Comprehensive test coverage
Storybook integration

Governance

Contribution Guidelines

How to propose new components
Review and approval process
Versioning strategy
Breaking change policy
Deprecation process

Maintenance

Regular accessibility audits
Performance monitoring
Browser compatibility testing
Documentation updates
Community feedback incorporation

Design Tokens

Token Implementation

:root {
  /* Colors */
  --color-primary-500: #0066cc;
  --color-neutral-100: #f5f5f5;

  /* Spacing */
  --space-1: 4px;
  --space-2: 8px;
  --space-4: 16px;

  /* Typography */
  --font-size-sm: 0.875rem;
  --font-size-base: 1rem;
  --font-size-lg: 1.125rem;

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

Example: React Button Component Using Design Tokens

import React from "react";

interface ButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {
  variant?: "primary" | "secondary" | "danger";
  size?: "sm" | "md" | "lg";
  loading?: boolean;
}

const sizeStyles: Record<string, React.CSSProperties> = {
  sm: { padding: "var(--space-1) var(--space-2)", fontSize: "var(--font-size-sm)" },
  md: { padding: "var(--space-2) var(--space-4)", fontSize: "var(--font-size-base)" },
  lg: { padding: "var(--space-3) var(--space-6)", fontSize: "var(--font-size-lg)" },
};

export const Button: React.FC<ButtonProps> = ({
  variant = "primary",
  size = "md",
  loading = false,
  disabled,
  children,
  ...props
}) => (
  <button
    style={{
      ...sizeStyles[size],
      backgroundColor: `var(--color-${variant}-500)`,
      color: "var(--color-neutral-100)",
      borderRadius: "var(--radius-md)",
      boxShadow: "var(--shadow-sm)",
      cursor: disabled || loading ? "not-allowed" : "pointer",
      opacity: disabled ? 0.5 : 1,
    }}
    disabled={disabled || loading}
    aria-busy={loading}
    {...props}
  >
    {loading ? "Loading…" : children}
  </button>
);

Example: Storybook Configuration

// .storybook/preview.ts
import type { Preview } from "@storybook/react";
import "../src/tokens.css"; // import design tokens globally

const preview: Preview = {
  parameters: {
    a11y: { element: "#storybook-root" },
    backgrounds: {
      default: "light",
      values: [
        { name: "light", value: "#ffffff" },
        { name: "dark", value: "#1a1a1a" },
      ],
    },
  },
};

export default preview;

Quality Assurance

Visual regression testing
Accessibility automated testing
Cross-browser testing
Performance benchmarking
Component unit testing
Integration testing

When evolving the design system, validate changes against WCAG 2.1 AA, run visual regression tests, and ensure token updates propagate correctly across all consuming applications.