.storybook/
├── pages/
│   ├── Introduction.mdx          # Design system overview
│   ├── GettingStarted.mdx        # Installation and usage
│   ├── DesignPrinciples.mdx      # Design philosophy
│   ├── Accessibility.mdx         # A11y guidelines
│   └── Contributing.mdx          # Contribution guide
├── design-tokens/
│   ├── Colors.mdx                # Color palette docs
│   ├── Typography.mdx            # Typography scale
│   ├── Spacing.mdx               # Spacing system
│   ├── Elevation.mdx             # Shadows and depth
│   └── Borders.mdx               # Border styles
├── components/
│   ├── Button/
│   │   ├── Button.tsx
│   │   ├── Button.stories.tsx
│   │   └── Button.mdx            # Component docs
│   ├── Input/
│   └── Card/
└── patterns/
    ├── Forms.mdx                  # Form patterns
    ├── Navigation.mdx             # Navigation patterns
    └── Layouts.mdx                # Layout patterns

# Welcome to Our Design System

A comprehensive collection of reusable components, design tokens, and guidelines
for building consistent user experiences.

## Quick Links

- [Getting Started](/docs/getting-started)
- [Design Tokens](/docs/design-tokens-colors)
- [Components](/docs/components)
- [Accessibility](/docs/accessibility)

## Design Principles

1. **Consistency**: Use established patterns across the product
2. **Accessibility**: WCAG 2.1 AA compliance by default
3. **Performance**: Optimized components for fast load times
4. **Flexibility**: Composable primitives for custom needs

## Installation

```bash
npm install @your-org/design-system

import { Button, Card } from '@your-org/design-system';

function App() {
  return (
    <Card>
      <Button variant="primary">Get Started</Button>
    </Card>
  );
}

### Color Documentation Page

```mdx
import { ColorPalette, ColorItem } from '@storybook/blocks';

# Colors

Our color system is designed for accessibility, consistency, and scalability.

## Primary Colors

<ColorPalette>
  <ColorItem
    title="Primary"
    subtitle="Brand color"
    colors={{
      'Primary 50': '#e3f2fd',
      'Primary 100': '#bbdefb',
      'Primary 500': '#2196f3',
      'Primary 900': '#0d47a1',
    }}
  />
</ColorPalette>

## Semantic Colors

<ColorPalette>
  <ColorItem
    title="Success"
    colors={{ Success: '#4caf50' }}
  />
  <ColorItem
    title="Warning"
    colors={{ Warning: '#ff9800' }}
  />
  <ColorItem
    title="Error"
    colors={{ Error: '#f44336' }}
  />
  <ColorItem
    title="Info"
    colors={{ Info: '#2196f3' }}
  />
</ColorPalette>

## Accessibility

All color combinations meet WCAG 2.1 AA standards:

- Text on Primary 500: White (#ffffff) - Contrast ratio 4.5:1 ✓
- Text on Primary 900: White (#ffffff) - Contrast ratio 8.2:1 ✓

## Usage

```tsx
// CSS
.primary-button {
  background-color: var(--color-primary-500);
  color: white;
}

// Tailwind
<button className="bg-primary-500 text-white">
  Click me
</button>

### Typography Documentation Page

```mdx
import { Typeset } from '@storybook/blocks';

# Typography

Our typography system ensures consistent, accessible text across all products.

## Font Families

- **Sans**: 'Inter', -apple-system, system-ui, sans-serif
- **Serif**: 'Merriweather', Georgia, serif
- **Mono**: 'Fira Code', Consolas, monospace

## Type Scale

<Typeset
  fontSizes={[12, 14, 16, 20, 24, 32, 40, 48]}
  fontWeight={400}
  sampleText="The quick brown fox jumps over the lazy dog"
  fontFamily="'Inter', sans-serif"
/>

## Heading Styles

| Element | Size | Weight | Line Height | Usage |
|---------|------|--------|-------------|-------|
| H1 | 48px | 700 | 1.2 | Page titles |
| H2 | 40px | 700 | 1.2 | Section headings |
| H3 | 32px | 600 | 1.3 | Subsection headings |
| H4 | 24px | 600 | 1.4 | Card titles |
| H5 | 20px | 600 | 1.5 | Small headings |
| H6 | 16px | 600 | 1.5 | Overlines |

## Body Text

| Style | Size | Weight | Line Height | Usage |
|-------|------|--------|-------------|-------|
| Large | 18px | 400 | 1.6 | Introductions |
| Regular | 16px | 400 | 1.5 | Body text |
| Small | 14px | 400 | 1.5 | Captions, labels |
| Tiny | 12px | 400 | 1.5 | Helper text |

## Usage

```tsx
// CSS
h1 {
  font-size: var(--font-size-h1);
  font-weight: var(--font-weight-bold);
  line-height: var(--line-height-tight);
}

// React
<Text variant="h1">Heading</Text>
<Text variant="body">Regular text</Text>
<Text variant="small">Small text</Text>

### Spacing Documentation Page

```mdx
# Spacing

Consistent spacing creates visual rhythm and hierarchy.

## Spacing Scale

Our spacing system uses a 4px base unit:

| Token | Value | Usage |
|-------|-------|-------|
| `space-0` | 0px | No spacing |
| `space-1` | 4px | Tight spacing |
| `space-2` | 8px | Small spacing |
| `space-3` | 12px | Medium-small |
| `space-4` | 16px | Regular spacing |
| `space-5` | 20px | Medium spacing |
| `space-6` | 24px | Large spacing |
| `space-8` | 32px | XL spacing |
| `space-10` | 40px | XXL spacing |
| `space-12` | 48px | Section spacing |
| `space-16` | 64px | Page spacing |

## Visual Example

<div style={{ display: 'flex', gap: '16px', alignItems: 'flex-start' }}>
  <div style={{ background: '#e3f2fd', height: '40px', width: '4px' }} />
  <span>space-1 (4px)</span>
</div>

<div style={{ display: 'flex', gap: '16px', alignItems: 'flex-start', marginTop: '8px' }}>
  <div style={{ background: '#e3f2fd', height: '40px', width: '16px' }} />
  <span>space-4 (16px)</span>
</div>

<div style={{ display: 'flex', gap: '16px', alignItems: 'flex-start', marginTop: '8px' }}>
  <div style={{ background: '#e3f2fd', height: '40px', width: '32px' }} />
  <span>space-8 (32px)</span>
</div>

## Usage Guidelines

### Component Spacing
- **Between elements**: Use space-4 (16px) as default
- **Component padding**: Use space-4 or space-6 (16px or 24px)
- **Section spacing**: Use space-12 or space-16 (48px or 64px)

### Grid and Layout
- **Column gap**: space-4 (16px) for tight, space-6 (24px) for loose
- **Row gap**: space-6 (24px) for cards, space-4 (16px) for lists

## Usage

```tsx
// CSS
.card {
  padding: var(--space-6);
  margin-bottom: var(--space-4);
}

// Tailwind
<div className="p-6 mb-4">Card content</div>

// Styled components
const Card = styled.div`
  padding: ${props => props.theme.space[6]};
`;

## Component Documentation Pattern

### Button Component Documentation

```mdx
import { Meta, Canvas, Story, Controls } from '@storybook/blocks';
import * as ButtonStories from './Button.stories';

<Meta of={ButtonStories} />

# Button

Primary UI component for user interactions. Use buttons for actions like submitting forms, opening dialogs, or navigating.

## When to Use

✅ **Use buttons when:**
- Triggering actions (submit, save, delete)
- Opening modals or dialogs
- Navigating to new pages
- Confirming decisions

❌ **Don't use buttons for:**
- Navigation within content (use links instead)
- Selecting from multiple options (use radio/checkbox)
- Showing/hiding content (use disclosure patterns)

## Examples

### Primary Button

The primary button is for the main action on a page.

<Canvas of={ButtonStories.Primary} />

### Secondary Button

Use secondary buttons for secondary actions.

<Canvas of={ButtonStories.Secondary} />

### All Variants

<Controls of={ButtonStories.Primary} />

## Variants

| Variant | Usage |
|---------|-------|
| Primary | Main action on page |
| Secondary | Secondary actions |
| Outline | Tertiary actions |
| Ghost | Subtle actions |

## Sizes

| Size | Usage |
|------|-------|
| Small | Compact UIs, tables |
| Medium | Default size |
| Large | Hero sections, CTAs |

## States

- **Default**: Normal interactive state
- **Hover**: Visual feedback on hover
- **Active**: Visual feedback on click
- **Focus**: Keyboard focus indicator
- **Disabled**: Non-interactive state
- **Loading**: Async action in progress

## Accessibility

✅ **Built-in features:**
- Semantic `<button>` element
- Keyboard accessible (Enter/Space)
- Focus visible indicator
- `aria-busy` when loading
- Disabled state prevents interaction

## Best Practices

1. **Use clear labels**: "Save changes" not "Submit"
2. **One primary button per page**: Avoid multiple CTAs
3. **Loading states**: Show feedback for async actions
4. **Icon buttons**: Include `aria-label`

## Code Example

```tsx
import { Button } from '@your-org/design-system';

function MyComponent() {
  const [loading, setLoading] = useState(false);

  const handleSubmit = async () => {
    setLoading(true);
    await saveData();
    setLoading(false);
  };

  return (
    <Button
      variant="primary"
      onClick={handleSubmit}
      loading={loading}
    >
      Save Changes
    </Button>
  );
}

## Storybook Configuration

### Configure Docs in `.storybook/main.ts`

```typescript
import type { StorybookConfig } from '@storybook/react-vite';

const config: StorybookConfig = {
  stories: [
    '../docs/**/*.mdx',
    '../src/**/*.stories.@(js|jsx|ts|tsx)',
  ],
  addons: [
    '@storybook/addon-links',
    '@storybook/addon-essentials',
    '@storybook/addon-docs',
  ],
  docs: {
    autodocs: true,
    defaultName: 'Documentation',
  },
};

export default config;

export const parameters = {
  options: {
    storySort: {
      order: [
        'Introduction',
        'Getting Started',
        'Design Tokens',
        ['Colors', 'Typography', 'Spacing', 'Elevation'],
        'Components',
        'Patterns',
      ],
    },
  },
};

# Generate color palette visualization
python3 ${CLAUDE_PLUGIN_ROOT}/skills/visual-design/scripts/generate_mockup.py \
  "Color palette for modern design system with primary blue, success green, error red" \
  --output style-guide/color-palette.png

# Generate typography scale
python3 ${CLAUDE_PLUGIN_ROOT}/skills/visual-design/scripts/generate_mockup.py \
  "Typography scale showing font sizes from 12px to 48px" \
  --output style-guide/typography.png