# Storybook

> >

- **Type:** Skill
- **Install:** `agentstack add skill-mthines-agent-skills-storybook`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [mthines](https://agentstack.voostack.com/s/mthines)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [mthines](https://github.com/mthines)
- **Source:** https://github.com/mthines/agent-skills/tree/main/skills/design/storybook

## Install

```sh
agentstack add skill-mthines-agent-skills-storybook
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Storybook

Scaffold and test Storybook stories — **three artefacts in two files**
per component: a `Default` story and a `Playground` story (both in the
visual regression file) plus an interaction test file under a
`/Tests` namespace.
Works on React (web) and React Native / Expo (native).
Auth — when the running Storybook is gated — is opt-in and per-pathname,
with secrets stored in the OS keychain instead of the repo.

> **This `SKILL.md` is a thin index.**
> Concern-specific rules live in [`rules/*.md`](./rules) and load on
> demand.
> Reference material lives in [`references/*.md`](./references).
> Literal scaffolding lives in [`templates/*.md`](./templates).
> Do not preload every file — load only what the current phase asks for.

---

## When to use

Reach for this skill when any of the following is true:

- A component has no story file yet and needs visual regression coverage.
- An existing `*.stories.tsx` lacks an interaction test counterpart.
- A `Playground` story is missing or out of sync with current props.
- The Storybook target is gated by auth and the agent needs to log in.
- A flaky interaction test needs to be iterated against the running
  Storybook URL.

Do **not** reach for this skill when:

- The task is to build the component itself.
  Scaffold stories **after** the component is implemented and named.
- The repo has no Storybook installation at all.
  Halt and ask the user to install Storybook first — this skill does not
  bootstrap Storybook.
- The component is a hook or non-visual primitive with no rendered
  surface.
  Defer to [`tdd`](../../quality/tdd/SKILL.md).

---

## Arguments and defaults

Parse `$ARGUMENTS` in this order:

| Argument                   | Default                                                                    | Effect                                                                  |
| -------------------------- | -------------------------------------------------------------------------- | ----------------------------------------------------------------------- |
| ``         | Prompt the user                                                            | Source file of the component to scaffold stories for.                   |
| `--platform web\|native`   | Auto-detect (see [`rules/react-native.md`](./rules/react-native.md))       | Web emits `.stories.tsx`; native emits the Expo / RN variant.           |
| `--no-interactions`        | Generate `.test.stories.tsx`                                         | Skip the interaction test file.                                         |
| `--no-playground`          | Include a `Playground` story                                               | Skip the Playground story.                                              |
| `--no-default`             | Include a `Default` story with grouped variants                            | Skip the visual regression Default story (rare — only for test-only).   |
| `--auth `         | None                                                                       | Use the named auth profile when running Playwright against the URL.     |
| `--title `| Inferred from the component path                                           | Override the Storybook `title` for the generated meta.                  |

Sub-commands:

```
/storybook auth list                # List configured auth profiles in this repo.
/storybook auth add        # Register a new profile (writes config + stores secret in OS keychain).
/storybook auth remove     # Remove a profile (deletes config entry + keychain item).
/storybook auth test       # Dry-run the login flow against the configured URL.
```

The full auth contract — config schema, keychain commands per OS, and
the `storageState` reuse loop — lives in [`rules/auth.md`](./rules/auth.md).

---

## Workflow (six phases)

Each phase has a single gate. Do not proceed until it passes.

| Phase | Name                       | Gate                                                                  |
| ----- | -------------------------- | --------------------------------------------------------------------- |
| 0     | Preflight                  | Storybook installed; platform detected; auth profile loaded if asked  |
| 1     | Component inspection       | Component file read; props and variants enumerated                    |
| 2     | Visual regression scaffold | `.stories.tsx` written; variants grouped                        |
| 3     | Playground scaffold        | `Playground` story written with `args` + `argTypes`                   |
| 4     | Interaction test scaffold  | `.test.stories.tsx` written under `/Tests` namespace            |
| 5     | Verification               | Storybook running; Playwright CLI iteration confirms rendering        |

### Phase 0 — Preflight

Run these read-only checks before writing anything:

```bash
# 1. Storybook installed?
jq '.devDependencies | keys[]' package.json | grep -E '@storybook/'

# 2. Storybook config dir present?
ls .storybook/ 2>/dev/null

# 3. Platform — web (Vite / Next) or native (Expo / RN)? Check
#    dependencies, devDependencies, AND peerDependencies — shared
#    component libraries (`packages/ui`) consumed by an Expo app
#    declare `react-native` as a peer.
jq '(.dependencies // {}) + (.devDependencies // {}) + (.peerDependencies // {}) | keys[]' package.json | grep -E '^(react-native|expo|@storybook/react-native)'
```

Decision table:

| State                                                    | Action                                                                        |
| -------------------------------------------------------- | ----------------------------------------------------------------------------- |
| Storybook installed + `.storybook/` present              | Proceed to Phase 1.                                                           |
| Storybook missing                                        | **Halt.** Ask user to install Storybook before invoking this skill again.     |
| `react-native` or `expo` in dependencies                 | Set `--platform native`. Load [`rules/react-native.md`](./rules/react-native.md). |
| Neither present                                          | Set `--platform web`.                                                         |
| `--auth ` passed                                | Load [`rules/auth.md`](./rules/auth.md). Resolve secret before Phase 5.       |

### Phase 1 — Component inspection

Read the component file.
Enumerate, in this order:

1. The component's exported name.
2. Each prop, its TypeScript type, and whether it is optional.
3. Each visible state derivable from props (`isLoading`, `error`,
   `disabled`, `variant`, `size`).
4. Each callback prop that an interaction test will need to spy on
   (`onClick`, `onChange`, `onSubmit`, …).
5. Any context providers the component requires (theme, query client,
   router) — these go into the meta `decorators`.

Output the inventory inline before scaffolding.
The user reads it and corrects misinterpretations before any file is
written.

### Phase 2 — Visual regression scaffold

Write `.stories.tsx` next to the component file.
Full rules and the variant-grouping pattern live in
[`rules/create-stories.md`](./rules/create-stories.md).

The shape, in one diagram:

```text
default export (Meta)
└── title: "/"
└── component: 
└── parameters: { layout: "padded" | "centered" | "fullscreen" }

export const Default: Story = {
  render: () => (
    
  ),
};
```

Use the literal scaffolding in:

- [`templates/component.stories.tsx`](./templates/component.stories.tsx)
  (web)
- [`templates/component.native.stories.tsx`](./templates/component.native.stories.tsx)
  (React Native / Expo)

If the repo already exports a `Stories` / `Stories.Entry` helper
(checked by `Grep "Stories\\.Entry"` against the repo), use it to group
variants into a single snapshot.
Otherwise emit a plain flex/stack wrapper.
The decision tree is in
[`rules/create-stories.md`](./rules/create-stories.md).

### Phase 3 — Playground scaffold

Append a `Playground` story to the same file.
Every prop becomes an `argTypes` control.
Mapping:

| TypeScript prop                          | `argTypes` control                                              |
| ---------------------------------------- | --------------------------------------------------------------- |
| `boolean`                                | `{ control: "boolean" }`                                        |
| `string`                                 | `{ control: "text" }`                                           |
| `number` with inferable min/max          | `{ control: { type: "range", min: , max: , step:  } }` |
| `number` without explicit clamps         | `{ control: "number" }`                                         |
| Union of string literals                 | `{ control: "select", options: [...] }`                         |
| Callback (`onClick`, `onChange`)         | `args: { onClick: fn() }` — imported from `storybook/test`      |
| `ReactNode` / children                   | `{ control: "text" }` with a default string                     |

Full example: see "Playground story" in
[`rules/create-stories.md`](./rules/create-stories.md).

### Phase 4 — Interaction test scaffold

Write `.test.stories.tsx` next to the component file.

**Hard rules** (full reasoning in
[`rules/interaction-tests.md`](./rules/interaction-tests.md)):

- File suffix is `.test.stories.tsx`.
  Do not use `.interactions.stories.tsx`, `.spec.stories.tsx`, or
  anything else.
- Title is `/Tests`.
  One Storybook namespace per file — CSF3 allows exactly one default
  export.
- `tags: ["test"]` is set on the meta so the test runner picks it up.
- `parameters.chromatic = { disableSnapshot: true }` keeps these stories
  out of visual regression.
- All `userEvent` calls are awaited; all `expect` calls are awaited.
- Locator priority: `getByRole` → `getByLabelText` →
  `getByPlaceholderText` → `getByText` → `getByTestId`.
  Never start with `getByTestId`.

Use the literal scaffolding in:

- [`templates/component.test.stories.tsx`](./templates/component.test.stories.tsx)
  (web)
- [`templates/component.native.test.stories.tsx`](./templates/component.native.test.stories.tsx)
  (React Native / Expo — uses `@storybook/react-native` test helpers)

### Phase 5 — Verification

Start Storybook in the background and iterate against the live URL.
Full Playwright CLI loop in
[`rules/playwright-cli.md`](./rules/playwright-cli.md).

Minimum verification, in this order:

1. Story compiles — Storybook prints no error in the terminal.
2. Story renders — Playwright CLI navigates to the story URL and the
   canvas root selector resolves.
3. Default story is reachable from the sidebar at the inferred title.
4. Interaction test passes via the Storybook test runner (e.g.
   `npm run test-storybook`) — if the runner is wired up.

For visual evidence (a screenshot or short clip of the rendered story),
delegate to the [`reviewer`](../../../agents/reviewer.md) agent or the
[`screen-recorder`](../../analysis/screen-recorder/SKILL.md) skill.
Full handoff rules in
[`rules/visual-verification.md`](./rules/visual-verification.md).

If the Storybook URL is gated and `--auth ` was passed, the
Playwright CLI invocation reuses the `storageState.json` produced by
the auth profile's login flow.
The skill never types credentials into the Playwright CLI directly.

---

## Decision flow at a glance

| Signal                                                    | Do                                                                       |
| --------------------------------------------------------- | ------------------------------------------------------------------------ |
| Component has no `.stories.tsx`                           | Run the full workflow (Phases 0–5).                                      |
| Component has `.stories.tsx` but no `.test.stories.tsx`   | Skip to Phase 4. Reuse the existing meta `title` for the `/Tests` peer.  |
| Repo has `react-native` or `expo`                         | Set `--platform native`. Load [`rules/react-native.md`](./rules/react-native.md). |
| Storybook URL is `http://localhost:6006/...` (or similar) | Iterate via Playwright CLI. No auth needed.                              |
| Storybook URL is gated (login form, SSO, basic auth)      | Resolve `--auth ` first. Load [`rules/auth.md`](./rules/auth.md).|
| Visual evidence requested in the PR                       | Delegate to [`reviewer`](../../../agents/reviewer.md) or `screen-recorder`. |
| Component is a hook or non-visual                         | Stop. Defer to [`tdd`](../../quality/tdd/SKILL.md).                                 |
| Storybook isn't installed                                 | Halt. Ask the user to install Storybook before re-running.               |

---

## Composes with

- [`tdd`](../../quality/tdd/SKILL.md) — owns unit / hook tests.
  This skill defers below the visual surface to it.
- [`test-provenance-guard`](../../quality/test-provenance-guard/SKILL.md) —
  run on the generated `.test.stories.tsx` to ensure the test imports
  production component code, not a private shim.
- [`reviewer`](../../../agents/reviewer.md) — runs the visual check pass
  and posts screenshots on the PR (Critical / High motion findings,
  visual diffs).
- [`screen-recorder`](../../analysis/screen-recorder/SKILL.md) — captures short
  videos of multi-frame interactions where a still screenshot cannot
  prove the change (transitions, focus order, hover-revealed UI).
- [`ux`](../ux/SKILL.md) — call after stories are scaffolded to audit
  the rendered states for accessibility and microcopy.
- [`visual-design`](../visual-design/SKILL.md) — call **before**
  scaffolding when the component is new and the visual direction is
  not yet committed (palette, type, signature details). Call **after**
  scaffolding in `review` mode if the rendered variants look generic
  or drift from the chosen direction. Pairs with `ux` — `ux` audits
  the floor, `visual-design` shapes the ceiling.
- [`confidence`](../../quality/confidence/SKILL.md) — gate before declaring the
  scaffold done if the user disputes a generated variant.

---

## Rules

- [`rules/create-stories.md`](./rules/create-stories.md) — visual
  regression `*.stories.tsx` pattern: grouped variants, Playground
  story, layout parameter, static mock data only.
- [`rules/interaction-tests.md`](./rules/interaction-tests.md) —
  `*.test.stories.tsx` hard requirements: `/Tests` namespace, awaited
  `userEvent`, locator ladder, `fn()` spies, `step()` grouping.
- [`rules/react-native.md`](./rules/react-native.md) — Expo / React
  Native flavor: `@storybook/react-native` differences, native
  locators, mobile-only template paths.
- [`rules/auth.md`](./rules/auth.md) — opt-in per-pathname auth: config
  schema, OS-keychain commands, `storageState` reuse, multi-profile
  routing, secret rotation.
- [`rules/playwright-cli.md`](./rules/playwright-cli.md) — iteration
  loop against the running Storybook URL: snapshot mode, `--last-failed`,
  iframe routes, story permalinks, headed vs headless.
- [`rules/visual-verification.md`](./rules/visual-verification.md) —
  delegation rules for the `reviewer` agent and `screen-recorder`
  skill, when each is the right tool.
- [`rules/anti-patterns.md`](./rules/anti-patterns.md) — full list of
  patterns to refuse.

## References

- [`references/platform-detection.md`](./references/platform-detection.md)
  — how the skill decides web vs native, and the Storybook builder
  matrix per framework.
- [`references/flake-cookbook.md`](./references/flake-cookbook.md) —
  copy-paste decorator snippets for the five most common flake
  sources (animations, fonts, dates, random IDs, theme drift).
  Load only when an existing story has flaked or the user asks for
  deterministic snapshots — adding all five preemptively is
  cargo-culting.

## Templates

- [`templates/component.stories.tsx`](./templates/component.stories

…

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [mthines](https://github.com/mthines)
- **Source:** [mthines/agent-skills](https://github.com/mthines/agent-skills)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-mthines-agent-skills-storybook
- Seller: https://agentstack.voostack.com/s/mthines
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.