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:

```js
// 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:

```tsx
// 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:

```tsx
// 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:

```tsx
// globals.css
@layer base {
  :root {
    --backgro