Design Systems at Scale: Lessons from Building Component Libraries

// Example of a well-designed Button API
interface ButtonProps {
  variant?: 'primary' | 'secondary' | 'destructive' | 'ghost'
  size?: 'sm' | 'md' | 'lg'
  disabled?: boolean
  loading?: boolean
  children: React.ReactNode
  className?: string
  onClick?: () => void
}

const Button: React.FC<ButtonProps> = ({
  variant = 'primary',
  size = 'md',
  disabled = false,
  loading = false,
  children,
  className,
  onClick,
  ...props
}) => {
  return (
    <button
      className={cn(
        buttonVariants({ variant, size }),
        className
      )}
      disabled={disabled || loading}
      onClick={onClick}
      {...props}
    >
      {loading ? <Spinner /> : children}
    </button>
  )
}

// Design tokens structure
export const tokens = {
  colors: {
    // Semantic tokens
    primary: {
      50: '#eff6ff',
      100: '#dbeafe',
      500: '#3b82f6',
      900: '#1e3a8a'
    },
    semantic: {
      success: '#10b981',
      warning: '#f59e0b',
      error: '#ef4444',
      info: '#3b82f6'
    }
  },
  spacing: {
    xs: '0.25rem',   // 4px
    sm: '0.5rem',    // 8px
    md: '1rem',      // 16px
    lg: '1.5rem',    // 24px
    xl: '2rem'       // 32px
  },
  typography: {
    fontSizes: {
      xs: '0.75rem',
      sm: '0.875rem',
      base: '1rem',
      lg: '1.125rem',
      xl: '1.25rem'
    },
    fontWeights: {
      normal: 400,
      medium: 500,
      semibold: 600,
      bold: 700
    }
  }
}

// Compound component pattern for complex UI
const Card = {
  Root: ({ children, className, ...props }) => (
    <div 
      className={cn('rounded-lg border bg-card shadow-sm', className)} 
      {...props}
    >
      {children}
    </div>
  ),
  
  Header: ({ children, className, ...props }) => (
    <div 
      className={cn('flex flex-col space-y-1.5 p-6', className)} 
      {...props}
    >
      {children}
    </div>
  ),
  
  Title: ({ children, className, ...props }) => (
    <h3 
      className={cn('text-2xl font-semibold leading-none tracking-tight', className)} 
      {...props}
    >
      {children}
    </h3>
  ),
  
  Content: ({ children, className, ...props }) => (
    <div 
      className={cn('p-6 pt-0', className)} 
      {...props}
    >
      {children}
    </div>
  )
}

// Usage
<Card.Root>
  <Card.Header>
    <Card.Title>Project Dashboard</Card.Title>
  </Card.Header>
  <Card.Content>
    <p>Welcome to your project overview.</p>
  </Card.Content>
</Card.Root>

// Storybook story with comprehensive documentation
import type { Meta, StoryObj } from '@storybook/react'
import { Button } from './Button'

const meta: Meta<typeof Button> = {
  title: 'Components/Button',
  component: Button,
  parameters: {
    docs: {
      description: {
        component: `
The Button component is used to trigger actions or events, such as submitting forms, 
opening dialogs, canceling actions, or performing delete operations.

## Usage Guidelines
- Use primary buttons for the main action on a page
- Use secondary buttons for less important actions
- Use destructive buttons for actions that cannot be undone
        `
      }
    }
  },
  argTypes: {
    variant: {
      control: 'select',
      options: ['primary', 'secondary', 'destructive', 'ghost'],
      description: 'Visual style variant'
    },
    size: {
      control: 'select', 
      options: ['sm', 'md', 'lg'],
      description: 'Size of the button'
    }
  }
}

export default meta
type Story = StoryObj<typeof meta>

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

export const AllVariants: Story = {
  render: () => (
    <div className="flex gap-4">
      <Button variant="primary">Primary</Button>
      <Button variant="secondary">Secondary</Button>
      <Button variant="destructive">Destructive</Button>
      <Button variant="ghost">Ghost</Button>
    </div>
  ),
  parameters: {
    docs: {
      description: {
        story: 'All available button variants side by side.'
      }
    }
  }
}