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

1. Setup — main.ts, preview.ts, framework selection (Vite vs Webpack, Next.js vs React-only), addon installation via the CLI, staticDirs.
2. Story authoring (CSF3) — satisfies Meta<typeof Component>, named exports = stories, tags: ['autodocs'] placement, when render is appropriate, story naming conventions.
3. Args, argTypes, controls — when to rely on inference, when to declare control: 'select', fn() from storybook/test for callbacks, args vs parameters vs globals.
4. Decorators & composition — global providers in preview.ts, MSW for network mocks, subpath-import module mocking (Storybook 9+), decorator signature pitfalls.
5. Interaction testing — play functions, the storybook/test import path (NOT @storybook/test), destructured canvas/userEvent, findBy* over waitFor, addon-vitest for CI, portable stories.
6. 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.
7. Documentation & design system — autodocs vs MDX, MDX referencing stories with <Canvas of={...} />, status tags, design tokens as stories, Figma links via parameters.design.
8. 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.

Quick Reference

1. Setup & Configuration (CRITICAL)

• config-typed-main-config — Type main.ts with satisfies StorybookConfig
• config-pick-the-right-framework-package — Use the framework package that matches your build (@storybook/nextjs-vite for Next.js, etc.)
• config-narrow-stories-glob — Narrow the stories glob to story files only
• config-typed-preview — Type preview.ts with the framework's Preview type
• config-add-addons-via-cli — Install addons with npx storybook add, never by hand
• config-static-dirs-not-bundler-imports — Serve assets via staticDirs, not bundler imports
• config-tokens-css-vars-in-preview — Wire Style Dictionary / Tokens Studio output into preview.ts as CSS variables
• config-story-sort-for-large-libraries — parameters.options.storySort order for design-system sidebars (Foundations → Components → Patterns)

2. Story Authoring — CSF3 (CRITICAL)

• csf-satisfies-meta-not-typed — satisfies Meta<typeof Component>, never : Meta<typeof Component>
• csf-prefer-args-over-render — Default to args; reserve render for compound stories
• csf-set-meta-component-explicitly — Always set meta.component (autodocs/controls/types depend on it)
• csf-name-stories-by-state — Name stories by user-visible state, not by prop value
• csf-tags-autodocs-on-meta — tags: ['autodocs'] belongs on the meta, not per-story
• csf-co-locate-stories-with-component — Co-locate Component.stories.tsx next to Component.tsx
• csf-default-export-is-the-meta — Default export = meta; named exports = stories
• csf-title-hierarchy-for-design-systems — Meta title: 'Components/Inputs/Button' taxonomy (Foundations / Components / Patterns / Examples)

3. Args, ArgTypes & Controls (HIGH)

• args-derive-from-component-props — Let argTypes be inferred; declare only what inference can't see
• args-use-fn-for-callbacks — Use fn() from storybook/test for callback args
• args-explicit-control-for-unions — Declare control + options for unions inference can't reach
• args-no-jsx-in-args — No JSX in args; compose JSX in render
• args-pick-args-vs-parameters-vs-globals — args = component inputs, parameters = addon config, globals = toolbar state

4. Decorators & Composition (HIGH)

• deco-global-providers-in-preview — Theme/QueryClient/Intl providers go in preview.ts
• deco-msw-for-network-mocks — Mock the network layer with MSW; don't stub the SDK
• deco-mock-modules-with-subpath-imports — Mock non-network modules via package.json#imports
• deco-decorator-component-not-call — Render decorators as <Story />, not {story()}
• deco-context-aware-decorators — Read globals and parameters from context for reactive wrappers
• deco-themes-addon-for-multi-brand — Use @storybook/addon-themes withThemeByClassName/withThemeByDataAttribute for multi-brand switching
• deco-rtl-direction-toggle — Toolbar dir toggle that wraps every story with dir="rtl" for bidi regression

5. Interaction Testing (HIGH)

• test-import-from-storybook-test — Import from storybook/test (Storybook 9+), not @storybook/test
• test-await-every-userevent-call — await every userEvent call
• test-use-canvas-from-play-arg — Destructure canvas/userEvent from the play arg
• test-fn-for-spied-callbacks — args: { onSubmit: fn() }, then assert with expect(args.onSubmit).toHaveBeenCalledWith(...)
• test-findby-over-waitfor — Prefer findByRole over waitFor + getByRole
• test-vitest-addon-for-ci — Run plays in CI via @storybook/addon-vitest, not the legacy test-runner
• test-portable-stories-for-rtl — Reuse stories in RTL/Vitest tests via composeStories

6. Accessibility — axe (HIGH)

• axe-set-test-error-globally — parameters.a11y.test = 'error' as a real gate, in preview.ts
• axe-disable-rules-not-stories — Disable specific rules; never test: 'off' on a whole story
• axe-restrict-runonly-to-wcag-aa — Scope runOnly to your WCAG target (typically AA)
• axe-context-for-portals — Set parameters.a11y.context for components that render into portals
• axe-globals-manual-for-intentional-violations — globals.a11y.manual: true for fixtures that intentionally violate

7. Documentation & Design System (MEDIUM-HIGH)

• docs-autodocs-vs-mdx — Autodocs for component pages, MDX for cross-cutting docs
• docs-mdx-references-stories — <Canvas of={Story} /> instead of inline renders
• docs-component-status-tags — Surface lifecycle with status tags + sidebar badges
• docs-design-tokens-as-stories — Document tokens as stories for visual regression
• docs-figma-link-via-design-addon — Link each story to its Figma frame via parameters.design

8. Build, Performance & Deployment (MEDIUM)

• build-prefer-vite-over-webpack — Vite-based framework packages over legacy Webpack
• build-trim-test-bundle — Trim the Vitest-addon test build via main.ts build.test config
• build-deploy-static-build-to-shareable-host — Deploy storybook build to Chromatic/Vercel for every PR
• build-cache-storybook-in-ci — Cache the Vite/Webpack and Playwright layers in CI
• build-storybook-composition-refs — refs in main.ts to compose multi-package design systems into one host Storybook
• build-manager-brand — .storybook/manager.ts with create() for logo, brand link, and sidebar palette
• build-chromatic-modes-multi-theme — Snapshot every story across themes / viewports / direction via Chromatic modes

How to use

• Start with references/_sections.md for the category structure and impact rationale.
• 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.
• Add new rules using assets/templates/_template.md.

Reference files

Related skills

• clean-code-ts-react — Underlying component design quality (naming, function shape, abstraction).
• react-testing-library — RTL queries and patterns when used outside Storybook.
• web-interface-guidelines — Vercel Web Interface Guidelines for the components you're documenting.