Storybook Stories skill for Codex

Done well means: each component has one story per meaningful state (not per prop), stories render in isolation without network calls, interactive behavior is asserted in play functions that run in CI, and the docs page tells a consumer how to use the component without reading its source.

Before writing anything

1. Read AGENTS.md, .storybook/main.* and .storybook/preview.*. Note the framework package (e.g. @storybook/react-vite, @storybook/nextjs-vite, @storybook/vue3-vite), the Storybook version in package.json, and global decorators already registered.
2. Look at two existing stories and match their file location, naming and title scheme.
3. Read the component and its tests; list the states that matter (empty, loading, error, long content, disabled, each variant, RTL, dark theme).
4. Storybook 10 is ESM-only: config and story files must be valid ESM, and Node 20.16+, 22.19+ or 24+ is required. Upgrades: npx storybook@latest upgrade (needs network; ask in a sandbox).

Story file template (React; other renderers are analogous)

// src/components/Button/Button.stories.tsx
import type { Meta, StoryObj } from "@storybook/react-vite";
import { expect, fn } from "storybook/test";
import { Button } from "./Button";

const meta = {
  component: Button,
  title: "Primitives/Button",           // omit to derive from the file path
  tags: ["autodocs"],
  args: { children: "Save", onClick: fn() },
  argTypes: {
    variant: { control: "inline-radio", options: ["primary", "secondary", "danger"] },
    onClick: { table: { category: "Events" } },
  },
  parameters: { layout: "centered" },
} satisfies Meta<typeof Button>;

export default meta;
type Story = StoryObj<typeof meta>;

export const Primary: Story = {};
export const Danger: Story = { args: { variant: "danger", children: "Delete project" } };
export const Disabled: Story = { args: { disabled: true } };
export const LongLabel: Story = {
  args: { children: "Save changes and notify every collaborator on this workspace" },
};

export const CallsOnClick: Story = {
  play: async ({ args, canvas, userEvent }) => {
    await userEvent.click(canvas.getByRole("button", { name: /save/i }));
    await expect(args.onClick).toHaveBeenCalledOnce();
  },
};

• satisfies Meta<typeof Button> plus StoryObj<typeof meta> gives type errors when a story misses a required arg.
• Put shared args on meta; stories override only what differs.
• Use fn() for every callback so calls show in the Actions panel and can be asserted.
• Import test utilities from storybook/test (Storybook 9+). Older projects use @storybook/test; switch when upgrading.

Which stories to write

Component kind	Stories
Presentational primitive	Each variant, size extremes, disabled, long text, with icon
Form control	Empty, filled, invalid with message, disabled, required, keyboard entry play test
Data-driven component	Loading, empty, error, typical data, overflow (100+ rows, long strings)
Overlay (dialog, menu)	Opened via play function so the open state is visible and tested
Page or screen	Logged-out, logged-in, permission denied, with mocked network data

Skip stories that only flip one boolean with no visual or behavioral difference; use controls.

Decorators, providers and context

// .storybook/preview.tsx
import type { Preview } from "@storybook/react-vite";
import { ThemeProvider } from "../src/theme";
import "../src/styles/globals.css";

const preview: Preview = {
  decorators: [
    (Story, { globals }) => (
      <ThemeProvider theme={globals.theme ?? "light"}><Story /></ThemeProvider>
    ),
  ],
  globalTypes: {
    theme: { toolbar: { title: "Theme", items: ["light", "dark"], dynamicTitle: true } },
  },
  parameters: { a11y: { test: "error" } },
};
export default preview;

• Global providers (theme, i18n, query client, router) go in preview; story-specific wrappers go on the story’s decorators.
• Create a fresh query client per story to avoid cache leaks between stories.
• Router-dependent components: use the framework’s router parameters (Next.js framework packages expose parameters.nextjs) or a memory router decorator.

Data and module mocking

Dependency	Approach
HTTP calls	MSW with msw-storybook-addon; handlers in parameters.msw.handlers
Imported modules (session, analytics, date)	Storybook module mocking: register with sb.mock() in preview (Storybook 9.1+/10), then set return values in beforeEach
Current date or time	Mock the date module or pass the date as a prop; never let stories depend on Date.now()
Random IDs	Seed or stub them; snapshots and visual tests flake otherwise

// .storybook/preview.ts:  import { sb } from "storybook/test";  sb.mock(import("../src/lib/session.ts"));
// in the story file:
import { mocked } from "storybook/test";
import { getSession } from "../lib/session";

export const Expired: Story = {
  beforeEach: async () => {
    mocked(getSession).mockResolvedValue({ user: null });
  },
};

Interaction and a11y tests in CI

npx storybook add @storybook/addon-vitest     # sets up Vitest browser mode with Playwright
npx vitest --project=storybook                # run all stories as tests

• Every story is a smoke test (it must render without throwing); stories with play also run their assertions. The a11y addon reports axe violations per story; with parameters.a11y.test: "error" they fail the run, "todo" reports only.
• Use await on every userEvent call and findBy* for async UI.
• Query by role and accessible name, as in Testing Library; never by class names.
• Projects not on Vite can still use @storybook/test-runner (Jest + Playwright against a built or running Storybook).
• Visual regression of stories belongs to $visual-regression-testing.

Docs

• tags: ["autodocs"] on meta generates a docs page from args, argTypes and JSDoc comments on the component props. Write the prop JSDoc; it becomes the table description.
• Add a short parameters.docs.description.component for usage guidance (“Use for the one primary action on a screen”).
• Use MDX only for guides that are more than a component page; keep it next to the stories.

Gotchas

• Stories that import the app’s root (App.tsx) pull in the whole app and its side effects. Import the component directly.
• CSS not appearing: global styles must be imported in preview, and Tailwind needs the stories path in its content sources (v3) or @source (v4).
• play runs after render on every visit, including in docs mode; keep it idempotent and fast.
• Story names come from export names; renaming an export breaks links and Chromatic baselines.
• argTypes with control: false hides a prop from controls but not from the docs table; use table: { disable: true } for internal props.

Verification

• npx storybook dev loads with no console errors on the new stories.
• npx vitest --project=storybook (or the test-runner) passes, including play and a11y.
• Each story renders offline (network disabled) and in both themes.
• npx storybook build succeeds; this is what CI and hosting use.

Output

Report the stories added per component, the states covered, play tests and what they assert, mocks introduced, and the command that runs them in CI.