storybook

Storybook

• ALWAYS use mcp__storybook__get-storybook-story-instructions before writing stories.
• ALWAYS use mcp__storybook__preview-stories to preview stories after writing them.
• Stories use parameters.fixtures for fixture overrides.
• API mocking (handlers, fixtures, story-scoped overrides, msw-storybook-addon wiring and its v2→v3 break): svelte-5:msw skill.
• Storybook is usually already running: just navigate with Playwright MCP.
• Verify every story in the browser via Playwright MCP: don't assume it works.
• CSS imports: trace chains through BOTH App.svelte AND .storybook/preview.ts. Moving imports out of the SCSS chain breaks Storybook unless also added to preview.ts or storybook.scss.

Svelte 4 writable stores need wrapper components in stories

Components that import and read from Svelte 4 module-level writable() stores (from svelte/store) render with default/ empty data in Storybook unless the stores are populated before the component mounts. This does NOT apply to Svelte 5 runes- based state in .svelte.ts modules, those are reactive on their own.

Pattern: Create a <ComponentName>Wrapper.svelte that:

1. Calls setContext() for any required Svelte contexts
2. Calls store.set() with mock data for every Svelte 4 writable() store the component imports
3. Wraps children in a layout div with sensible dimensions

Use asChild in the story, NEVER decorators for components that depend on Svelte 4 writable stores. Decorators lose complex args (Writable stores, objects with methods) through Storybook's arg serialization.

<!-- stories/MyComponentWrapper.svelte -->
<script lang="ts">
  import { setContext } from 'svelte'
  import { writable } from 'svelte/store'
  import { myWritableStore } from '../stores'  // Svelte 4 writable()
  setContext('myContext', true)
  myWritableStore.set({ /* mock data */ })
</script>
<div style="max-width: 600px; padding: 1rem;">
  <slot />
</div>

<!-- stories/MyComponent.stories.svelte -->
<Story name="Default" asChild>
  <MyComponentWrapper>
    <MyComponent />
  </MyComponentWrapper>
</Story>