Skip to main content
skill CX Codex

storybook · pproenca — Claude Code skill: features and installation

This skill guides Storybook setup and story authoring for TypeScript/React components. Use it for interaction tests, accessibility checks, and component documentation.

MIT 145 installs ★ 227 updated 2026-08-15

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add pproenca/dot-skills --skill storybook -a claude-code
Open on GitHub

What storybook does

The skill covers .storybook/main.ts and .storybook/preview.ts, CSF3 stories, and the use of args, argTypes, and controls. It also explains decorators, providers, MSW network mocks, and documentation with autodocs or MDX.

For interaction checks, it uses play functions with the Vitest addon. Accessibility guidance centers on @storybook/addon-a11y and axe-core. The material also addresses design tokens, Figma links, and publishing through Chromatic or Vercel. Its examples target Storybook 9+ and 10, so older projects may need different patterns.

This skill focuses on Storybook rather than general React advice or Testing Library queries. It recommends adding addons with npx storybook add; choose the framework configuration to match your build setup, such as Vite or Next.js.

What it helps with

  • configure Storybook's main.ts and preview.ts
  • write CSF3 stories for component states
  • add interactions with a play function
  • check accessibility with axe
  • document components with autodocs or MDX

Example prompts for the agent

  • Write CSF3 stories for this React component and set up its args.
  • Configure @storybook/addon-a11y to check this story for accessibility issues.
  • Find out why this component's play function is flaky in CI.

How to install storybook

1Skills CLI (Vercel)

npx skills add pproenca/dot-skills --skill storybook -a claude-code

2Manually: put the files in place

~/.claude/skills/storybook/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/storybook/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about storybook

How do I install storybook in Claude Code?

Run npx skills add pproenca/dot-skills --skill storybook -a claude-code. The skill file is at ~/.claude/skills/storybook/SKILL.md.

What does the storybook skill do?

It helps configure Storybook for TypeScript/React component libraries, author stories, and set up interaction and accessibility checks.

Which Storybook versions does this skill target?

It targets Storybook 9+ and 10, with guidance for CSF3, the storybook/test import, and the Vitest addon.

Source text

SKILL.md · MIT
---
name: storybook
description: 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

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.

| Priority | Category | Impact | Prefix | Rules |
|----------|----------|--------|--------|-------|
| 1 | Setup & Configuration | CRITICAL | `config-` | 8 |
| 2 | Story Authoring (CSF3) | CRITICAL | `csf-` | 8 |
| 3 | Args, ArgTypes & Controls | HIGH | `args-` | 5 |
| 4 | Decorators & Composition | HIGH | `deco-` | 7 |
| 5 | Interaction Testing | HIGH | `test-` | 7 |
| 6 | Accessibility (axe) | HIGH | `axe-` | 5 |
| 7 | Documentation & Design System | MEDIUM-HIGH | `docs-` | 5 |
| 8 | Build, Performance & Deployment | MEDIUM | `build-` | 7 |

## Quick Reference

### 1. Setup & Configuration (CRITICAL)

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

### 2. Story Authoring — CSF3 (CRITICAL)

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

### 3. Args, ArgTypes & Controls (HIGH)

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

### 4. Decorators & Composition (HIGH)

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

### 5. Interaction Testing (HIGH)

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

### 6. Accessibility — axe (HIGH)

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

### 7. Documentation & Design System (MEDIUM-HIGH)

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

### 8. Build, Performance & Deployment (MEDIUM)

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

## How to use

- Start with [references/_sections.md](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`](gotchas.md): failure modes discovered over time; always check before debugging an obscure issue.
- Add new rules using [`assets/templates/_template.md`](assets/templates/_template.md).

## Reference files

| File | Description |
|------|-------------|
| [references/_sections.md](references/_sections.md) | Category definitions and ordering |
| [assets/templates/_template.md](assets/templates/_template.md) | Template for adding new rules |
| [gotchas.md](gotchas.md) | Failure modes accumulated over time |
| [metadata.json](metadata.json) | Version, references, abstract |

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

© pproenca · MIT · pproenca/dot-skills

Similar skills

All skills for Frontend and UI →

storybook by other authors comes first.

storybook Mindrally Enforces Storybook best practices for component libraries, covering file structure, autodocs, controls, and interaction tests. CX Codex +1 970installs storybook-testing OrchestKit The storybook-testing Claude Code skill guides component testing in Storybook 10. It covers story authoring, visual checks, CI setup, and migration from Storybook 9. CX Codex +1 224installs storybook-story-writing TheBushidoCollective storybook-story-writing writes and edits Storybook stories for your components: CSF3 format, every meaningful state, a build that passes. Useful when stories drift and break the build. CX Codex +1 680installs storybook-component-documentation TheBushidoCollective Generates Storybook component documentation via autodocs, MDX pages and JSDoc comments. Useful when creating or updating UI library docs. CX Codex +1 166installs storybook-setup patricio0312rev storybook-setup sets up Storybook for component docs, interactive controls, accessibility checks, and visual regression testing. CX Codex +1 336installs storybook-mcp-integration OrchestKit The storybook-mcp-integration Claude Code skill connects Storybook MCP tools to work with existing components. The agent can find component docs, open story previews, and run story tests. CX Codex +1 166installs writing-react-native-storybook-stories storybookjs writing-react-native-storybook-stories teaches the agent to write and edit React Native stories in CSF: args, argTypes, decorators, addon parameters and portable stories for testing. CX Codex +1 722installs

From the same set139

The whole set →
diataxis diataxis sorts technical docs into four modes: tutorial, how-to, reference, explanation. Tells the agent which one a page needs before it starts writing. CX Codex +1 149installs drizzle-sqlite-scaffold drizzle-sqlite-scaffold generates boilerplate for Drizzle ORM + SQLite: config, client with pragmas, table schemas, CRUD modules and validators. Triggers on phrases like “add a table for X” or “set up the DB”. CX Codex +1 149installs same-results-less-code The same-results-less-code skill helps spot conceptual complexity during code review and refactoring while preserving behavior. It looks beyond the mechanical issues linters catch. CX Codex +1 148installs codebase-comprehension-algorithms codebase-comprehension-algorithms maps an unfamiliar repository into feature domains: which files back a feature, where the architecture actually sits. CX Codex +1 148installs code-map-visualization code-map-visualization tells the agent how to draw a codebase map that is already projected: which attribute goes on position, size or colour, and how to stay inside a 16 ms frame. CX Codex +1 145installs nuqs-scaffolder nuqs-scaffolder turns one JSON spec into four Next.js files for URL-backed filters: a parser map, a server loader, a client component and a Vitest test. CX Codex +1 145installs migrate-js-to-modern-typescript migrate-js-to-modern-typescript guides the file-by-file conversion of a JavaScript codebase to strict TypeScript. Helps configure tsconfig, turn on strict compiler flags, and eliminate any without breaking the build. CX Codex +1 145installs radical-simplification radical-simplification — a skill for untangling hard engineering and product problems by changing the frame, reducing scope, and testing assumptions. Use it when the current approach has stalled. CX Codex +1 144installs

Project sponsors

Companies that keep this analytics open