# Add Story

> Create comprehensive Storybook stories with test plans, play functions, and validated tests for a component. Use when a component needs Storybook coverage or story files. Use when this capability is needed.

- Skill: `tomevault-io/add-story` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/add-story`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/add-story/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/add-story

---


# Add Story

> **Purpose:** Create comprehensive Storybook stories with test plans, play functions, and validated passing tests
> **Usage:** `/add-story <ComponentName or path>`

## Prerequisites

- **Storybook** installed and configured in the project
- **@storybook/test** for `expect`, `userEvent`, `within`, `waitFor`
- **MSW (Mock Service Worker)** if the component has API dependencies
- **@storybook/addon-interactions** for play function debugging

## Constraints

- **Do not modify the original component** without explicit permission
- **Do not run full test suites** (`npm test`) -- scope to the component
- **Do not use querySelector** in tests -- use Testing Library queries
- **Do not skip waitFor** for async assertions
- **Test plan must be included** at top of story file
- **Create play functions for all interactive scenarios**
- **Run tests and ensure they pass**
- **Use Testing Library queries** (getByRole, getByLabelText, etc.)
- **Scope tests appropriately** (canvas for component, screen for modals)

## Workflow

### Step 0: Verify Storybook Setup

Before proceeding, verify Storybook is installed and configured:

```bash
# Check for Storybook config directory
ls .storybook/ 2>/dev/null

# Check for Storybook in package.json
grep -q "storybook" package.json && echo "Found" || echo "Not found"
```

**If Storybook is not installed:** Inform the user and suggest installation. Do not proceed without Storybook.

**Detect package manager:**
```bash
if [ -f "pnpm-lock.yaml" ]; then PKG_MGR="pnpm"
elif [ -f "yarn.lock" ]; then PKG_MGR="yarn"
elif [ -f "bun.lockb" ]; then PKG_MGR="bun"
else PKG_MGR="npm"; fi
```

### Step 1: Read the Component Structure

- Read the component file to understand props, slots, events, and behavior
- Identify component states and variants
- Note any conditional rendering or dynamic behavior
- List dependencies (API calls, stores, context providers)

### Step 2: Create a Test Plan

Document all meaningful component states to cover using Given/When/Then format. Include the test plan as a block comment at the top of the story file. See `references/story-patterns.md` for the test plan template.

### Step 3: Review Existing Patterns

Before writing stories:
- Check existing stories in the project for conventions
- Identify mocking requirements (MSW, stores, providers)
- Note the project's Storybook configuration

**Story file location and naming:**

Search for existing story files to discover project conventions:
```bash
find . -name "*.stories.tsx" -o -name "*.stories.ts" -o -name "*.story.tsx" | head -5
```

Common patterns:
| Pattern | Example |
|---------|---------|
| `__stories__/` directory | `src/components/__stories__/Button.stories.tsx` |
| Colocated | `src/components/Button.stories.tsx` |
| Root stories dir | `stories/Button.stories.tsx` |

**Always follow the existing project convention.** If no stories exist, default to colocated (next to the component file).

### Step 4: Write Stories for Visual States

Create stories covering all visual states (default, disabled, loading, error, etc.). Use meta configuration with title, component, parameters, and autodocs tag. See `references/story-patterns.md` for templates and the factory pattern.

**Context providers and decorators:**

If the component uses React context (identified in Step 1), wrap stories with the required providers via decorators:

```typescript
const meta: Meta<typeof Component> = {
  component: Component,
  decorators: [
    (Story) => (
      <ThemeProvider theme={defaultTheme}>
        <Story />
      </ThemeProvider>
    ),
  ],
};
```

Check the component's imports for context usage:
- `useContext(SomeContext)` → needs `SomeContext.Provider` decorator
- `useTheme()`, `useAuth()`, etc. → needs the corresponding provider
- Router-dependent components → wrap with `MemoryRouter` or equivalent

### Step 5: Write Play Functions for Interactions

Add play functions for all interactive scenarios using `step()` blocks, Testing Library queries, and `waitFor` for async assertions. See `references/story-patterns.md` for play function examples.

### Step 6: Add Mocking If Required

For components with API dependencies, use MSW handlers in story parameters. See `references/testing-best-practices.md` for MSW patterns.

### Step 7: Run Tests and Validate

```bash
# Use detected package manager from Step 0
$PKG_MGR run test-storybook -- --grep "ComponentName"
```

Fix failures, re-run until all pass. See `references/testing-best-practices.md` for debugging guidance.

## Story File Checklist

Before completing:

- [ ] Test plan documented at top of file
- [ ] Meta configuration complete (title, component, parameters)
- [ ] Default story exists
- [ ] All visual states covered (disabled, loading, error, etc.)
- [ ] Play functions for interactive scenarios
- [ ] MSW handlers for API dependencies (if applicable)
- [ ] Tests pass locally

## Acceptance Tests

| ID | Type | Prompt / Condition | Expected |
|----|------|--------------------|----------|
| STR-T1 | Positive | "Create a story for Button component" | Skill triggers |
| STR-T2 | Positive | "Add Storybook coverage for UserProfile" | Skill triggers |
| STR-T3 | Positive | "Write stories for this component" | Skill triggers |
| STR-T4 | Negative | "Write unit tests for this component" | Does NOT trigger (-> /test-coverage or /tdd) |
| STR-T5 | Negative | "How does this component work?" | Does NOT trigger (-> /explore) |
| STR-T6 | Boundary | "Test this component" | Context-dependent — if Storybook is the project's testing approach, trigger; otherwise route to /test-coverage |

## References

- `references/story-patterns.md` - Story templates, play functions, factory pattern, test plan format
- `references/testing-best-practices.md` - MSW mocking, Testing Library queries, async handling, example workflow

---
> Converted and distributed by [TomeVault](https://tomevault.io/claim/hypejunction) — claim your Tome and manage your conversions.
<!-- tomevault:4.0:skill_md:2026-04-13 -->