Svelte Storybook Story Processor

Create comprehensive Storybook stories for Svelte components with all states, interactions, accessibility annotations, and documentation using modern CSF patterns.

When to Use This Command

Run this command when...

• You have a Svelte component that needs complete Storybook coverage including all prop combinations, interactive states, and edge cases
• You want stories that serve as living documentation with usage examples, prop tables, and interactive controls
• Your component has complex interactions like form validation, async loading, or multi-step flows that need individual story variants

Do NOT use this command when...

• The component does not exist yet -- create it first with the component command
• You need to set up Storybook itself -- use the setup command first

Quick Start

Copy
# .claude/commands/svelte-storybook-story-processor.md
# Create Storybook stories
Create stories for: $ARGUMENTS

Copy
# Run the command
claude "svelte-storybook-story-processor create stories for Button component with all variants and states"

Expected output:
- Button.stories.ts with meta configuration
- Default, Primary, Secondary, Disabled variants
- Interactive story with args and controls
- Loading and error state stories
- Accessibility annotations and viewport tests

Core Concepts

Concept	Description
CSF v5	Modern Component Story Format using defineMeta and named exports
Story Variants	Individual stories representing specific component states
Args and Controls	Interactive prop editing in the Storybook UI via argTypes
Play Functions	Automated interaction scripts that run within stories for testing
Documentation	Auto-generated prop tables, usage examples, and descriptions

Story File Structure:

  ComponentName.stories.ts
  |
  |-- defineMeta({ component, title, argTypes })
  |
  |-- export const Default = { args: {...} }
  |-- export const Primary = { args: {...} }
  |-- export const WithError = { args: {...} }
  |-- export const Interactive = {
  |     play: async ({ canvas }) => { ... }
  |   }
  |-- export const Mobile = {
        parameters: { viewport: { ... } }
      }

Configuration

Parameter	Default	Description
CSF Version	v5	Component Story Format version for story syntax
Story Location	Adjacent to component	Stories created next to their component files
Controls	Auto-detect from props	Whether to generate interactive controls for all props
Play Functions	For interactive components	Automated interaction test generation
Docs	Auto-generated	Whether to include autodocs page generation

Best Practices

1. Cover every visual state -- create individual stories for default, hover, active, disabled, loading, error, and empty states so designers and QA can review each
2. Use meaningful story names -- "WithLongUserName" tells more than "Variant3". Story names appear in the Storybook sidebar and serve as documentation
3. Add play functions for interactions -- form components, toggles, and multi-step flows benefit from automated interaction scripts that verify behavior
4. Configure argTypes for better controls -- specify control types (select, radio, range) and option lists for enum props instead of relying on auto-detection
5. Group related stories -- use the title hierarchy like "Components/Forms/Button" to organize the Storybook sidebar for easy navigation

Common Issues

1. Props not appearing in controls panel -- ensure the component exports typed props. Storybook extracts argTypes from TypeScript types or JSDoc annotations
2. Play function cannot find elements -- use data-testid attributes or accessible queries (getByRole, getByLabelText) rather than CSS selectors for reliable element targeting
3. Stories render differently than the app -- global styles, fonts, or context providers may be missing. Add them to preview.ts decorators for consistent rendering