---
name: Storybook Integration
description: Set up and configure Storybook for design system documentation and development
globs:
  - "**/.storybook/**"
  - "**/*.stories.tsx"
  - "**/*.stories.jsx"
  - "**/*.stories.mdx"
  - "**/storybook-static/**"
alwaysApply: false
---

# Storybook Integration

## Overview

This skill helps set up, configure, and generate Storybook stories for design system components. It creates comprehensive documentation and interactive examples.

## When to Use

Use this skill when the user asks to:
- Set up Storybook for a project
- Generate stories for components
- Configure Storybook theme
- Create component documentation
- Add Storybook addons

## Capabilities

### 1. Story Generation
- Automatic story creation from components
- Props documentation extraction
- Default story with all props
- Variant stories for different states

### 2. Theme Configuration
- Design token integration
- Light/dark mode themes
- Custom branding
- Typography setup

### 3. Addon Configuration
- Controls for prop editing
- Actions for event logging
- Viewport for responsive testing
- Accessibility testing

### 4. Documentation
- MDX documentation pages
- Component API tables
- Usage examples
- Design guidelines

## Workflow

1. **Scan Existing Setup**
   ```
   Use dss_setup_storybook with action: scan
   ```

2. **Generate Stories**
   ```
   Use dss_setup_storybook with action: generate
   ```

3. **Configure Theme**
   ```
   Use dss_setup_storybook with action: configure
   ```

4. **Review and Refine**
   - Check generated stories
   - Add custom documentation
   - Configure addons

## Example Interaction

**User:** "Set up Storybook for my design system components"

**Assistant Response:**
```
I'll help you set up Storybook for your design system.

[Uses dss_setup_storybook with action: scan]

**Current Status:**
- Storybook: Not installed
- Components found: 23
- Existing stories: 0

Let me set up Storybook with your design tokens.

[Uses dss_setup_storybook with action: configure]

**Storybook Configuration Created:**

.storybook/main.js:
```javascript
module.exports = {
  stories: ['../src/**/*.stories.@(js|jsx|ts|tsx|mdx)'],
  addons: [
    '@storybook/addon-essentials',
    '@storybook/addon-a11y',
    '@storybook/addon-links'
  ],
  framework: '@storybook/react'
};
```

.storybook/preview.js:
```javascript
import { themes } from '@storybook/theming';
import '../src/styles/tokens.css';

export const parameters = {
  actions: { argTypesRegex: '^on[A-Z].*' },
  controls: { expanded: true },
  docs: {
    theme: themes.light
  }
};
```

Now generating stories for your components...

[Uses dss_setup_storybook with action: generate]

**Stories Generated:**
- Button.stories.tsx (4 variants)
- Card.stories.tsx (3 variants)
- Input.stories.tsx (5 variants)
- Modal.stories.tsx (2 variants)

Run `npm run storybook` to see your component library!
```

## Story Template

```tsx
// Button.stories.tsx
import type { Meta, StoryObj } from '@storybook/react';
import { Button } from './Button';

const meta: Meta<typeof Button> = {
  title: 'Components/Button',
  component: Button,
  tags: ['autodocs'],
  argTypes: {
    variant: {
      control: 'select',
      options: ['primary', 'secondary', 'ghost']
    },
    size: {
      control: 'select',
      options: ['sm', 'md', 'lg']
    }
  }
};

export default meta;
type Story = StoryObj<typeof Button>;

export const Primary: Story = {
  args: {
    variant: 'primary',
    children: 'Click me'
  }
};

export const Secondary: Story = {
  args: {
    variant: 'secondary',
    children: 'Click me'
  }
};
```

## Configuration Options

### Theme Branding
```javascript
// .storybook/theme.js
import { create } from '@storybook/theming';

export default create({
  base: 'light',
  brandTitle: 'My Design System',
  brandUrl: 'https://example.com',
  brandImage: '/logo.svg',

  // UI colors from tokens
  colorPrimary: '#0066cc',
  colorSecondary: '#6c757d',

  // Typography
  fontBase: '"Inter", sans-serif',
  fontCode: 'monospace'
});
```

## Related Tools

- `dss_setup_storybook` - Main Storybook tool
- `dss_generate_theme` - Generate theme for Storybook
- `dss_audit_components` - Find components to document

## Server Configuration

DSS Storybook runs on port 6006 by default:
- Host: 0.0.0.0 (configurable)
- Port: 6006 (configurable)
- Auto-open: disabled by default

## Best Practices

1. **Story Organization**
   - Group by component category
   - Use consistent naming
   - Include edge cases

2. **Documentation**
   - Write clear descriptions
   - Show usage examples
   - Document props thoroughly

3. **Maintenance**
   - Update stories with components
   - Test in CI/CD
   - Review accessibility regularly