| name | add-story |
| description | 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. |
| category | meta |
| triggers | ["create story","storybook","component story","add stories"] |
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:
ls .storybook/ 2>/dev/null
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:
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:
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:
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
$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:
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