Use whenever creating, configuring, or extending Storybook for a TS/React component library — covers main.ts/preview.ts setup, CSF3 story authoring, args/argTypes/controls, decorators and providers, MSW and module mocking, play-function interaction tests via the Vitest addon, the @storybook/addon-a11y workflow (axe-core), autodocs vs MDX docs, design tokens, Figma linking, Chromatic deployment, and on-demand build performance. Triggers on tasks like "write a story", "set up Storybook", "configure addon-a11y", "fix this play function", "deploy Storybook", "test Storybook in CI" — even when the user doesn't say "storybook" but is editing `*.stories.tsx`, `.storybook/main.ts`, or `.storybook/preview.ts`. Targets Storybook 9+/10 (modern `storybook/test` import, Vitest addon, CSF3 + `satisfies Meta`). Does NOT cover generic React patterns (use the `react` skill), generic Testing Library queries (use `react-testing-library`), or WCAG primer (points at addon-a11y + axe rule config).
Use whenever creating, configuring, or extending Storybook for a TS/React component library — covers main.ts/preview.ts setup, CSF3 story authoring, args/argTypes/controls, decorators and providers, MSW and module mocking, play-function interaction tests via the Vitest addon, the @storybook/addon-a11y workflow (axe-core), autodocs vs MDX docs, design tokens, Figma linking, Chromatic deployment, and on-demand build performance. Triggers on tasks like "write a story", "set up Storybook", "configure addon-a11y", "fix this play function", "deploy Storybook", "test Storybook in CI" — even when the user doesn't say "storybook" but is editing `*.stories.tsx`, `.storybook/main.ts`, or `.storybook/preview.ts`. Targets Storybook 9+/10 (modern `storybook/test` import, Vitest addon, CSF3 + `satisfies Meta`). Does NOT cover generic React patterns (use the `react` skill), generic Testing Library queries (use `react-testing-library`), or WCAG primer (points at addon-a11y + axe rule config).
dot-skills Storybook Best Practices
Comprehensive guide for using Storybook 9+ as the workshop and test bench for a TypeScript/React component library. 52 rules across 8 categories, ordered by the lifecycle of a component in your design system: a wrong .storybook/main.ts cascades into every story; a malformed CSF Meta blocks autodocs, controls, tests, and the a11y panel for that file.
What this skill covers
Setup — main.ts, preview.ts, framework selection (Vite vs Webpack, Next.js vs React-only), addon installation via the CLI, staticDirs.
Story authoring (CSF3) — satisfies Meta<typeof Component>, named exports = stories, tags: ['autodocs'] placement, when render is appropriate, story naming conventions.
Args, argTypes, controls — when to rely on inference, when to declare control: 'select', from for callbacks, args vs parameters vs globals.
fn()
storybook/test
Decorators & composition — global providers in preview.ts, MSW for network mocks, subpath-import module mocking (Storybook 9+), decorator signature pitfalls.
Interaction testing — play functions, the storybook/test import path (NOT @storybook/test), destructured canvas/userEvent, findBy* over waitFor, addon-vitest for CI, portable stories.
Accessibility (axe-core via @storybook/addon-a11y) — parameters.a11y.test = 'error' as a real gate, per-rule disables, runOnly scoped to your WCAG target, portal context, globals.a11y.manual for intentional-violation fixtures.
Documentation & design system — autodocs vs MDX, MDX referencing stories with <Canvas of={...} />, status tags, design tokens as stories, Figma links via parameters.design.
Build & deployment — Vite over Webpack, on-demand bundling for large libraries, deploy to Chromatic/Vercel for designer review, CI cache configuration.
When to Apply
Reach for this skill when:
Editing or creating a *.stories.tsx, *.mdx, .storybook/main.ts, .storybook/preview.ts, or vitest.config.ts that loads storybookTest.
Setting up Storybook on a new project (framework choice, npx storybook init follow-up).
Adding or upgrading an addon (a11y, vitest, designs, msw).
Wiring component tests through play functions and the Vitest addon.
Investigating "Storybook is slow", "controls show text instead of select", "a11y panel shows nothing for my dialog", "play function is flaky in CI".
Skip this skill and use:
react-optimise / clean-code-ts-react for the underlying component design.
react-testing-library for render/screen/userEvent semantics outside Storybook.
WCAG/ARIA reference docs for the spec itself; this skill assumes you know what aria-labelledby does and tells you how addon-a11y checks it.
Rule Categories by Priority
Order reflects the component lifecycle (configure → author → wire → decorate → test → audit → document → ship). Earlier stages cascade.
For "I'm setting up Storybook," read all config- rules then csf-.
For "I'm writing a new story," read csf- and args-.
For "I want tests on my stories," read test- and deco-msw-for-network-mocks.
For "I want a11y to fail CI on violations," read all axe- rules.
For "I'm building a design system from scratch," read in this order: config-tokens-css-vars-in-preview, config-story-sort-for-large-libraries, csf-title-hierarchy-for-design-systems, deco-themes-addon-for-multi-brand, build-manager-brand, build-chromatic-modes-multi-theme. Then docs-component-status-tags and docs-design-tokens-as-stories for the governance + token-display layer.
For "I have a multi-package monorepo design system," read build-storybook-composition-refs first, then the design-system path above.
For "I need RTL / multi-direction coverage," read deco-rtl-direction-toggle then build-chromatic-modes-multi-theme to wire RTL into visual regression.
For gotchas.md: failure modes discovered over time; always check before debugging an obscure issue.
