design-systems

Guide creation of consistent, maintainable design systems using React and Tailwind CSS. Focus on reusability, clear naming, and systematic token usage.

Design Tokens

Define tokens in tailwind.config.js for consistency:

// tailwind.config.js
module.exports = {
  theme: {
    extend: {
      colors: {
        primary: { DEFAULT: '#4F46E5', hover: '#4338CA' },
        surface: { DEFAULT: '#FFFFFF', muted: '#F8FAFC' },
        border: { DEFAULT: '#E2E8F0', focus: '#4F46E5' },
      },
      spacing: {
        section: '4rem',
        card: '1.5rem',
      },
      borderRadius: {
        card: '0.75rem',
        button: '0.5rem',
      },
    },
  },
}

Component Architecture

Structure components with clear prop interfaces:

// Button with variants
interface ButtonProps {
  variant?: 'primary' | 'secondary' | 'ghost'
  size?: 'sm' | 'md' | 'lg'
  children: React.ReactNode
}

const variants = {
  primary: 'bg-primary text-white hover:bg-primary-hover',
  secondary: 'border border-border bg-white text-slate-900 hover:bg-surface-muted',
  ghost: 'text-slate-600 hover:text-slate-900 hover:bg-surface-muted',
}

const sizes = {
  sm: 'px-3 py-1.5 text-sm',
  md: 'px-4 py-2 text-sm',
  lg: 'px-6 py-3 text-base',
}

Naming Conventions

• Components: PascalCase (Button, Card, InputField)
• Variants: Descriptive strings ('primary', 'outlined', 'destructive')
• Sizes: t-shirt sizing ('sm', 'md', 'lg', 'xl')
• States: Boolean props (disabled, loading, selected)

Composition Patterns

Build complex components from primitives:

// Card composed of sub-components
<Card>
  <Card.Header>
    <Card.Title>Dashboard</Card.Title>
  </Card.Header>
  <Card.Content>
    {/* content */}
  </Card.Content>
  <Card.Footer>
    <Button variant="primary">Save</Button>
  </Card.Footer>
</Card>

Theming

Support light/dark modes with CSS variables:

// globals.css
@layer base {
  :root {
    --background: 250 250 250;
    --foreground: 15 23 42;
  }
  .dark {
    --background: 15 23 42;
    --foreground: 248 250 252;
  }
}

Principles

• One source of truth for colors, spacing, typography
• Components accept className for composition
• Variants over boolean props for exclusive options
• Document component usage with examples
• Use cn() utility (clsx + tailwind-merge) for class merging