story-generation

What this skill does

# Story Generation Skill

## Overview

Generate Storybook stories automatically from existing components by parsing prop types, detecting variants, and creating comprehensive CSF 3.0 stories with interaction tests and accessibility validation.

This skill provides a complete component analysis and story generation pipeline for React, Vue, and Svelte components.

## What This Skill Provides

### Component Analysis
Parse component files to extract:
- Component name and type classification
- Props with TypeScript types
- Required vs optional props
- Default values
- Children/slots detection

### Intelligent Variant Detection
Automatically detect story variants from:
- Enum/union types: `'primary' | 'secondary' | 'outline'`
- Size props: `small`, `medium`, `large`
- Boolean states: `disabled`, `loading`, `error`
- Component-type specific patterns

### Story Generation
Create complete story files with:
- **CSF 3.0 format** (`satisfies Meta<typeof Component>`)
- **ArgTypes** with smart control inference (see Controls section below)
- **Variant stories** for all detected variations
- **Interaction tests** with play functions (Testing Library)
- **Accessibility tests** with axe-core rules
- **Component-specific test patterns** (button clicks, input validation, modal focus)

### Storybook 10 Controls (argTypes)

The generator infers appropriate control types based on prop names and types:

| Prop Pattern | Control Type | Example |
|--------------|--------------|---------|
| `boolean` type | `{ control: 'boolean' }` | `disabled`, `loading` |
| `number` type | `{ control: 'number' }` | `count`, `index` |
| `opacity`, `progress` | `{ control: { type: 'range', min: 0, max: 1 } }` | `opacity`, `percent` |
| `size`, `width`, `height` | `{ control: { type: 'range', min: 0, max: 100 } }` | `padding`, `margin` |
| `color`, `background`, `fill` | `{ control: 'color' }` | `backgroundColor`, `textColor` |
| `*Date`, `*Time`, `timestamp` | `{ control: 'date' }` | `createdDate`, `startTime` |
| `object`, `Record<>` | `{ control: 'object' }` | `style`, `config` |
| `array`, `[]` | `{ control: 'object' }` | `items`, `options[]` |
| `file`, `src`, `source` | `{ control: 'file' }` | `avatarFile`, `imageSrc` |
| Union type (2-4 options) | `{ options: [...], control: { type: 'radio' } }` | `'sm' \| 'md' \| 'lg'` |
| Union type (5+ options) | `{ options: [...], control: { type: 'select' } }` | `'a' \| 'b' \| 'c' \| 'd' \| 'e'` |
| `on*` (callbacks) | `{ action: 'propName' }` | `onClick`, `onChange` |
| `string` type | `{ control: 'text' }` | `label`, `placeholder` |
| `ReactNode`, `ReactElement` | `{ control: false }` | `children`, `icon` |

**Example generated argTypes:**
```typescript
argTypes: {
  variant: { options: ['primary', 'secondary', 'outline'], control: { type: 'radio' } },
  size: { options: ['sm', 'md', 'lg'], control: { type: 'radio' } },
  disabled: { control: 'boolean' },
  backgroundColor: { control: 'color' },
  onClick: { action: 'onClick' },
  label: { control: 'text' },
}
```

**Recommended preview.ts configuration:**
```typescript
// .storybook/preview.ts
const preview: Preview = {
  parameters: {
    controls: {
      matchers: {
        color: /(background|color)$/i,
        date: /Date$/,
      },
    },
  },
};
```

### Multi-Framework Support
- **React/TypeScript**: Parse interfaces, types, function components
- **Vue 3**: Parse `defineProps<T>` and runtime props
- **Svelte**: Parse `export let` statements

## Core Scripts

The skill provides four main scripts in `scripts/`:

### 1. parse_component.py
Parse component files to extract metadata.

**Usage:**
```bash
python3 ${CLAUDE_PLUGIN_ROOT}/skills/story-generation/scripts/parse_component.py \
  path/to/Component.tsx \
  --json
```

**Output:** Component metadata (name, framework, props, type classification)

### 2. detect_variants.py
Detect story variants from component props.

**Usage:**
```bash
python3 ${CLAUDE_PLUGIN_ROOT}/skills/story-generation/scripts/detect_variants.py \
  path/to/Component.tsx \
  --json
```

**Output:** List of variants with args and priorities

### 3. generate_story.py
Generate complete story file with tests.

**Usage:**
```bash
python3 ${CLAUDE_PLUGIN_ROOT}/skills/story-generation/scripts/generate_story.py \
  path/to/Component.tsx \
  --level full \
  --output path/to/Component.stories.tsx
```

**Testing levels:**
- `full`: All features (variants + interaction tests + a11y tests)
- `standard`: Variants + interaction tests
- `basic`: Variants with args/controls only
- `minimal`: Single default story

### 4. scan_components.py
Scan project directories for components.

**Usage:**
```bash
python3 ${CLAUDE_PLUGIN_ROOT}/skills/story-generation/scripts/scan_components.py \
  src \
  --json
```

**Output:** JSON array of discovered components with metadata

## Story Templates

Templates are located in `templates/` directory:

- `react-full.template` - React with full testing
- `react-basic.template` - React basic stories
- `vue-full.template` - Vue 3 with full testing
- `svelte-full.template` - Svelte with full testing

Templates use variable replacement:
- `{{COMPONENT_NAME}}` - Component name
- `{{VARIANT_STORIES}}` - Generated variant exports
- `{{INTERACTION_TEST_CODE}}` - Test code
- `{{A11Y_RULES}}` - Accessibility rules

## Workflow Integration

This skill integrates with the `/generate-stories` command:

1. **Scan**: Discover components with `scan_components.py`
2. **Parse**: Extract metadata with `parse_component.py`
3. **Detect**: Find variants with `detect_variants.py`
4. **Generate**: Create story with `generate_story.py`

## Component Type Support

The parser automatically detects and generates appropriate tests for:

| Type | Example | Special Handling |
|------|---------|------------------|
| button | Button, SubmitButton | Click tests, disabled check |
| input | TextField, Input | Type tests, value validation |
| checkbox | Checkbox | Click, checked state |
| select | Dropdown, Select | Option selection |
| card | Card, ProductCard | Render tests |
| modal | Dialog, Modal | Focus trap, ESC handler |
| table | DataTable, Table | Row/column tests |

15+ component types supported with custom test patterns.

## Example Usage

### Parse a Button Component

```bash
# Parse component
python3 scripts/parse_component.py src/components/Button.tsx

# Output:
# Component: Button
# Framework: react
# Type: button
# Props (6):
#   - variant: 'primary' | 'secondary' | 'outline' | 'ghost' (required)
#   - size: 'small' | 'medium' | 'large' (optional)
#   - disabled: boolean (optional)
#   - loading: boolean (optional)
#   - onClick: () => void (optional)
#   - children: React.ReactNode (required)
```

### Detect Variants

```bash
# Detect variants
python3 scripts/detect_variants.py src/components/Button.tsx

# Output:
# Detected 11 variants:
# 1. Primary (variant: primary)
# 2. Secondary (variant: secondary)
# 3. Outline (variant: outline)
# 4. Ghost (variant: ghost)
# 5-7. Small/Medium/Large (size variants)
# 8. Disabled (boolean state)
# 9. Loading (boolean state)
```

### Generate Complete Story

```bash
# Generate story with full testing
python3 scripts/generate_story.py \
  src/components/Button.tsx \
  --level full \
  --output src/components/Button.stories.tsx
```

**Generated story includes:**
- Meta configuration with argTypes
- 11 variant stories (Primary, Secondary, Outline, Ghost, Small, Large, Disabled, Loading, etc.)
- Interaction test with play function
- Accessibility test with axe-core rules

## Performance

- Component parsing: ~10ms per component
- Variant detection: ~1ms per component
- Story generation: ~15ms per component
- **Total**: ~26ms per component

Can process 100+ components in 2-3 seconds.

## Error Handling

The scripts handle common errors gracefully:
- **Parse failures**: Skip component, continue with others
- **Unknown types**: Fall back to generic component template
- **Missing files**: Clear error messages
- **Invalid syntax**: Report parsi