style-guide-generator

What this skill does

# Style Guide Generator Skill

## Overview

Generate comprehensive design system documentation for Storybook, including design tokens (colors, typography, spacing), component guidelines, and usage patterns. Create a centralized source of truth for your design system.

This skill provides guidance on structuring design system documentation using Storybook's docs features (MDX, Doc Blocks) and organizing design tokens.

## What This Skill Provides

### Design System Documentation
Create comprehensive documentation for:
- **Design tokens**: Colors, typography, spacing, shadows, borders
- **Component guidelines**: Usage patterns, do's and don'ts
- **Brand guidelines**: Logo usage, voice and tone
- **Accessibility standards**: WCAG compliance, keyboard navigation
- **Code examples**: Implementation snippets

### Storybook Docs Integration
Use Storybook's documentation features:
- **MDX pages**: Rich documentation with interactive examples
- **Doc Blocks**: Pre-built components for common documentation patterns
- **Custom pages**: Design system landing page, getting started guides
- **Auto-generated docs**: Component API documentation

### Design Token Organization
Structure and document design tokens:
- **Color system**: Primary, secondary, semantic colors
- **Typography scale**: Font families, sizes, weights, line heights
- **Spacing scale**: Consistent spacing system (4px, 8px, 16px, etc.)
- **Elevation system**: Shadows and z-index
- **Border styles**: Radius, width, colors

### Component Documentation
Document component patterns:
- **Anatomy**: Component structure and parts
- **Variants**: Available options and use cases
- **States**: Hover, focus, active, disabled, loading
- **Accessibility**: ARIA attributes, keyboard support
- **Examples**: Real-world usage scenarios

## Design System Structure

### Recommended Storybook Organization

```
.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
```

## Creating MDX Documentation Pages

### Introduction Page

```mdx
# 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
```

## Usage

```tsx
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 list