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', fn() from storybook/test for callbacks, args vs parameters vs globals.
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: