Menu

Individual skill

storybook

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).

skills/.experimental/storybook/SKILL.md

Read pinned source

Source commit cf93c57cac89d6fc3e4194686000411567f5caf3

What was checked

Matches the observed repository HEAD
Yes
Scanner rules are current
No
Repository scan complete
No
Skill scan complete
Yes
Observed behavior
Not checked yet
Last checked
Nov 5, 2026

These are observations at the recorded commit, not a guarantee of safety. Review the source before running it.

Install this skill

Choose an agent in your Stack or copy a command below. Commands fetch the pinned commit and copy only this skill directory. Existing destinations are refused. Copying a command does not install anything.

An install command is unavailable: current rules, complete repository and skill scans, an eligible behavior level and a permitted license are required.

Repository context

Repository stars (not skill ratings)
222
Repository last updated
Aug 15, 2026
License
MIT

Observed agent integration: codex

Files and excerpt

File metadata and permitted, redacted excerpts come from the recorded scan. Source links are pinned to that commit.

Browse files
Read excerpt

# 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.