Design Systems and Component Libraries

// Design System Structure Example
// A well-architected design system has clear layers:

// Layer 1: Design Tokens (Foundation)
// tokens/colors.ts
export const colors = {
  primary: {
    50: '#f0f9ff',
    100: '#e0f2fe',
    // ... more shades
    900: '#0c4a6e',
  },
  semantic: {
    success: '#10b981',
    error: '#ef4444',
    warning: '#f59e0b',
    info: '#3b82f6',
  },
};

// tokens/spacing.ts
export const spacing = {
  xs: '0.25rem',  // 4px
  sm: '0.5rem',   // 8px
  md: '1rem',     // 16px
  lg: '1.5rem',   // 24px
  xl: '2rem',     // 32px
};

// Layer 2: Primitive Components
// components/Button/Button.tsx
import { ButtonHTMLAttributes } from 'react';
import { colors, spacing } from '../../tokens';

export interface ButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
  variant?: 'primary' | 'secondary' | 'outline' | 'ghost';
  size?: 'sm' | 'md' | 'lg';
  isLoading?: boolean;
}

export function Button({
  variant = 'primary',
  size = 'md',
  isLoading,
  children,
  ...props
}: ButtonProps) {
  return (
    <button
      className={getButtonClasses(variant, size)}
      disabled={isLoading || props.disabled}
      {...props}
    >
      {isLoading ? <Spinner /> : children}
    </button>
  );
}

// Layer 3: Composite Components
// components/Form/FormField.tsx
import { Button } from '../Button';
import { Input } from '../Input';
import { Label } from '../Label';

export function FormField({ label, error, ...inputProps }) {
  return (
    <div className="form-field">
      <Label htmlFor={inputProps.id}>{label}</Label>
      <Input {...inputProps} aria-invalid={!!error} />
      {error && <ErrorMessage>{error}</ErrorMessage>}
    </div>
  );
}

Design systems are built in layers: tokens (foundation), primitives (basic components), composites (combined components), and patterns (page-level compositions). Each layer builds upon the previous one, ensuring consistency and reusability.

// tokens/index.ts - Complete token system
export const tokens = {
  // Color System
  color: {
    semantic: {
      primary: {
        base: 'var(--color-blue-600)',
        hover: 'var(--color-blue-700)',
        active: 'var(--color-blue-800)',
        disabled: 'var(--color-gray-300)',
      },
      success: {
        base: 'var(--color-green-600)',
        light: 'var(--color-green-100)',
        dark: 'var(--color-green-800)',
      },
    },
    background: {
      primary: 'var(--color-white)',
      secondary: 'var(--color-gray-50)',
      tertiary: 'var(--color-gray-100)',
    },
  },
  
  // Spacing System
  spacing: {
    scale: {
      0: '0',
      1: '0.25rem',  // 4px
      2: '0.5rem',   // 8px
      4: '1rem',     // 16px
      6: '1.5rem',   // 24px
      8: '2rem',     // 32px
    },
  },
  
  // Typography System
  typography: {
    fontFamily: {
      sans: ['Inter', 'system-ui', 'sans-serif'].join(', '),
      mono: ['Fira Code', 'Monaco', 'monospace'].join(', '),
    },
    fontSize: {
      xs: { value: '0.75rem', lineHeight: '1rem' },
      sm: { value: '0.875rem', lineHeight: '1.25rem' },
      base: { value: '1rem', lineHeight: '1.5rem' },
    },
  },
};

Design tokens provide a single source of truth for design values. They're organized by category (color, spacing, typography, etc.) and can be semantic (purpose-based) or base (raw values). CSS variables enable runtime theming while TypeScript provides type safety.

// Well-architected component example
import { forwardRef } from 'react';
import { cn } from '../../utils';

export interface ButtonProps
  extends React.ButtonHTMLAttributes<HTMLButtonElement> {
  variant?: 'primary' | 'secondary' | 'outline' | 'ghost';
  size?: 'sm' | 'md' | 'lg';
  isLoading?: boolean;
}

export const Button = forwardRef<HTMLButtonElement, ButtonProps>(
  ({ variant = 'primary', size = 'md', isLoading, children, ...props }, ref) => {
    return (
      <button
        ref={ref}
        disabled={isLoading || props.disabled}
        className={cn(/* styles */)}
        {...props}
      >
        {isLoading ? <Spinner /> : children}
      </button>
    );
  }
);

Well-architected components use forwardRef for ref forwarding, TypeScript for type safety, variant systems for styling, and composition patterns for flexibility. Compound components allow related components to share context while maintaining a clean API.

// Accessible Modal Component
export function Modal({ isOpen, onClose, title, children }: ModalProps) {
  const modalRef = useRef<HTMLDivElement>(null);
  
  // Trap focus within modal
  useEffect(() => {
    if (isOpen) {
      const firstFocusable = modalRef.current?.querySelector(
        'button, [href], input, select, textarea'
      ) as HTMLElement;
      firstFocusable?.focus();
      
      const handleEscape = (e: KeyboardEvent) => {
        if (e.key === 'Escape') onClose();
      };
      document.addEventListener('keydown', handleEscape);
      
      return () => document.removeEventListener('keydown', handleEscape);
    }
  }, [isOpen, onClose]);
  
  if (!isOpen) return null;
  
  return (
    <div
      role="dialog"
      aria-modal="true"
      aria-labelledby="modal-title"
      ref={modalRef}
    >
      <h2 id="modal-title">{title}</h2>
      {children}
    </div>
  );
}

Accessibility must be built into every component. Use proper ARIA attributes, manage focus, trap focus in modals, support keyboard navigation, provide screen reader announcements, and test with automated and manual methods.

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

const meta: Meta<typeof Button> = {
  title: 'Components/Button',
  component: Button,
  tags: ['autodocs'],
};

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

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

export const Variants: Story = {
  render: () => (
    <div className="flex gap-4">
      <Button variant="primary">Primary</Button>
      <Button variant="secondary">Secondary</Button>
      <Button variant="outline">Outline</Button>
    </div>
  ),
};

Storybook provides interactive documentation for components. Stories showcase different variants, states, and use cases. Well-documented components with comprehensive stories reduce onboarding time and improve consistency.

// Button.test.tsx
import { render, screen } from '@testing-library/react';
import userEvent from '@testing-library/user-event';
import { Button } from './Button';

describe('Button', () => {
  it('renders children correctly', () => {
    render(<Button>Click me</Button>);
    expect(screen.getByRole('button', { name: /click me/i })).toBeInTheDocument();
  });
  
  it('calls onClick when clicked', async () => {
    const handleClick = jest.fn();
    render(<Button onClick={handleClick}>Click me</Button>);
    
    await userEvent.click(screen.getByRole('button'));
    expect(handleClick).toHaveBeenCalledTimes(1);
  });
  
  it('has no accessibility violations', async () => {
    const { container } = render(<Button>Click me</Button>);
    const results = await axe(container);
    expect(results).toHaveNoViolations();
  });
});

Comprehensive testing ensures design system quality. Unit tests verify behavior, integration tests check interactions, visual regression tests catch styling bugs, accessibility tests ensure a11y compliance, and performance tests maintain speed.

// package.json - Design System Package Configuration
{
  "name": "@company/design-system",
  "version": "2.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"
  },
  "peerDependencies": {
    "react": ">=16.8.0",
    "react-dom": ">=16.8.0"
  }
}

Proper versioning and distribution are crucial for design systems. Use semantic versioning, provide clear migration guides, include deprecation warnings before breaking changes, offer codemods for automated migration, and structure packages for optimal tree-shaking.

// Contribution workflow example

// 1. RFC Process
// RFCs document proposed changes for review

// 2. Component Contribution Template
// CONTRIBUTING.md provides checklist:
// - Design review completed
// - TypeScript types defined
// - Unit tests written (80%+ coverage)
// - Accessibility tests pass
// - Storybook stories created
// - Documentation complete

// 3. Adoption tracking
export function trackComponentUsage(componentName: string) {
  window.analytics?.track('Design System: Component Used', {
    component: componentName,
    version: getDesignSystemVersion(),
  });
}

Governance, contribution processes, and adoption strategies are critical for design system success. Establish clear contribution workflows, track adoption metrics, provide feedback mechanisms, support migrations, and maintain transparent communication.