Svelte Storybook Setup Processor

Initialize and configure Storybook for SvelteKit projects with optimal addon selection, TypeScript integration, and build pipeline setup.

When to Use This Command

Run this command when...

• You are adding Storybook to an existing SvelteKit project for the first time and want a production-ready configuration
• You need to configure Storybook with the correct framework package, addons, and TypeScript support for your project
• Your Storybook setup needs addon configuration for accessibility testing, viewport simulation, or visual regression testing

Do NOT use this command when...

• Storybook is already configured and you need to create stories -- use the story creation command instead
• You need to upgrade an existing Storybook installation -- use the migration command instead

Quick Start

Copy
# .claude/commands/svelte-storybook-setup-processor.md
# Setup Storybook for SvelteKit
Setup: $ARGUMENTS

Copy
# Run the command
claude "svelte-storybook-setup-processor initialize Storybook with a11y addon and Tailwind CSS support"

Expected output:
- Storybook packages installed via package manager
- .storybook/main.ts with framework and addon config
- .storybook/preview.ts with global decorators and parameters
- Tailwind CSS integration in Storybook build
- Sample story demonstrating the setup

Core Concepts

Concept	Description
Framework Package	@storybook/sveltekit providing SvelteKit-aware integration
Main Configuration	.storybook/main.ts defining stories glob, addons, and framework
Preview Configuration	.storybook/preview.ts defining global decorators and parameters
Addon Ecosystem	Extensions for accessibility, viewport, docs, interactions, and testing
Build Integration	Vite-based Storybook build sharing your project's Vite configuration

Setup Structure:

  SvelteKit Project
       |
  [Install Packages]
       |
  .storybook/
  |-- main.ts        (framework + addons)
  |-- preview.ts     (decorators + params)
  |-- manager.ts     (UI customization)
       |
  [Configure Addons]
       |
  [Add Sample Story]
       |
  npx storybook dev

Configuration

Parameter	Default	Description
Package Manager	Auto-detect	npm, pnpm, or yarn based on lockfile
TypeScript	Enabled	TypeScript configuration files and type checking
Addons	essentials + a11y	Addon bundle selection
Styles	Match project	CSS framework integration matching project setup
Port	6006	Development server port for Storybook

Best Practices

1. Use @storybook/sveltekit -- always use this framework package over @storybook/svelte-vite for SvelteKit projects to get automatic module mocking and routing support
2. Install essentials addon bundle -- it includes controls, actions, viewport, backgrounds, docs, and toolbars. Add specialized addons on top as needed
3. Configure global styles -- import your app's global CSS or Tailwind config in preview.ts so stories render with the same styling as your application
4. Add the a11y addon from the start -- accessibility testing integrated into your component development workflow catches issues before they reach production
5. Create a sample story immediately -- verify the setup works end-to-end with a simple component story before investing time in configuration refinement

Common Issues

1. Vite config conflicts -- Storybook shares your project Vite config but may conflict with certain plugins. Use the viteFinal hook in main.ts to resolve conflicts
2. CSS not loading in stories -- global styles must be explicitly imported in preview.ts. Storybook does not automatically import your layout styles
3. PostCSS or Tailwind not processing -- ensure postcss.config.js is at the project root and that content paths in tailwind.config.js include your .stories files