Storybook Pentest
A UI/UX pentester for Storybook. Stories showcase components in isolation, but the variants a team writes are the happy paths. This skill runs two passes against them. The attack pass asks does it break: the edge cases that fail in production (long German compounds, empty lists, RTL, forced colors, a keyboard user in a modal) usually have no story. The value pass asks does it do its job: a component can survive every attack and still be the wrong button, with an unguessable control, a generic error, or a promise its name makes and its behavior does not keep. Both write every confirmed failure into a findings bundle with screenshot evidence, severity, and a reproducible URL, so a human or another agent can fix the product. The depth lives in the OKF bundle in references/; this file is the procedure.
Stance: two questions, and honest confidence
Break and serve are different questions, and the skill answers both. Breakage is mostly objective; fitness for purpose is partly judgment, so the value pass is grounded in named evaluation methods (Nielsen's heuristics, the cognitive walkthrough, Jakob's Law, published content rules) and every value finding cites the method it rests on. Two honesty rails hold throughout. Automated scanning has a measured ceiling (axe-core catches at most about 57 percent of WCAG issues by Deque's own figure; the GDS audit found the best tool caught 40 percent of 142 seeded barriers), so the automated axes give cheap breadth and the simulation and value axes are where the skill earns the word pentest. And every finding carries a confidence: confirmed for objective breakage and rule-cited content, needs-review for the genuine judgment calls, which are surfaced as questions for the human, never asserted as defects. Calibration in a11y-scan.md; the confidence rule in finding.md.
The layered driving surface
Never assume one integration; detect, then use the highest layer available. The detection ladder and per-layer capabilities are in references/surface/:
- Storybook MCP (
/mcp endpoint, SB 9.1.16+, Vite): curated docs, changed-story detection, test execution with a11y. No screenshots, no arg mutation, no raw enumeration.
- The story index (
/index.json, fallback /stories.json): the ground-truth story list with tags. Works on any SB 6.4+ including static builds.
- iframe URLs (
iframe.html?id=X&args=...&globals=...): render any story in any state. URL args are restricted to alphanumerics, space, underscore, dash, so hostile payloads enter via play functions or Playwright, not the URL.
- Playwright: pixels, keyboard, emulation (reduced motion, forced colors, viewport), screenshots.
- CLI runners (
npx vitest --project=storybook, npx test-storybook --url ... --json): the project's own test suites with JSON output.
Commands
Invoke as /storybook-pentest <command> [target].
| Command |
What it does |
sweep |
Pentest the whole Storybook. Enumerate, sample WCAG-EM style (structured sample plus a 10 percent random check plus complete flows), run the planned axes, report. Record what was sampled and what was skipped. |
component <name> |
One component, exhaustive. Every story, every applicable axis. |
group <path> |
A title-prefix scope, for example Design System/Forms. |
axis <name> [scope] |
One axis across a scope, attack or value, for example only a11y, only RTL, or only microcopy. |
value [scope] |
Run only the value pass: contract, walkthrough, heuristics, and microcopy. Does the component do its job, independent of whether it breaks. |
gaps [scope] |
Story-gap audit. Diff existing stories against the required-state matrix (the nine data states plus the interaction states); a missing state is a finding of class untested-surface. Contract gaps (a promised capability with no behavior) come from the value pass. |
report |
Rebuild the findings bundle and retest open findings by their stored repro URLs. A fixed finding that reproduces reopens. |
triage |
Rank open findings by severity times spread (how many components share the root cause) and propose a fix order. |
wire |
Scaffold project-side auto-triggering (CLAUDE.md rule or prompt hook) so design-system changes get pentested without anyone asking. |
The pipeline
detect -> enumerate -> scope -> plan -> probe -> capture -> grade -> report
- Detect the target's layers (surface/detection is in story-index.md and mcp.md).
- Enumerate stories from the index; segment by tags (
play-fn has interactions, type: docs is excluded).
- Scope the sample and record the boundary. Sampling rules in reporting/bundle-spec.md.
- Plan axes per story. Attack axes: every component gets content stress, data states, and the axe scan; interactive add keyboard; text-bearing add i18n; themed add theme; animated or async add motion (attacks/). Value axes: establish the contract first, then walkthrough for interactive components, heuristics for all, microcopy for anything with text (value/).
- Probe each planned cell. Payloads and procedures live per axis in attacks/ and value/.
- Capture evidence deterministically (reduced motion, fonts ready, play complete, animations disabled): surface/screenshots.md.
- Grade severity as impact times likelihood via the documented matrix in reporting/severity.md, and set
confidence; never grade on a gut call.
- Report into the OKF findings bundle in the target repo (reporting/bundle-spec.md, record schema in reporting/finding.md, scaffolds in reporting/templates.md).
The attack axes (does it break)
Twelve technical probes, ranked by bug yield; each has payloads and failure signatures in attacks/.
The value axes (does it do its job)
Four fitness-for-purpose probes, each grounded in a named evaluation method so findings stay inspectable; full procedures in value/.
| Axis |
Asks |
Method |
| Contract |
Does it keep the promises its name, docs, and genre make |
Genre expectations, Jakob's Law, Friedman's checklists |
| Walkthrough |
Could a first-time user actually operate it to the goal |
The four cognitive-walkthrough questions per step |
| Heuristics |
Does it violate a known usability principle |
Nielsen's ten heuristics at component scope |
| Microcopy |
Do its labels, errors, and empty states serve the user |
NN/g and GOV.UK content rules, the placeholder antipattern |
The deliverable
A conformant OKF bundle at ui-pentest/ in the target repo: executive summary, scope, methodology with tool versions and configs, a story-times-axis coverage matrix, one findings concept per component with embedded screenshots, and a per-run diff log. Findings have stable ids and a lifecycle (open, verified, fixed, accepted-risk, false-positive) with reopen-on-rescan, so successive runs diff instead of restarting. Spec in reporting/bundle-spec.md.
Source
Built from the Storybook 9/10 documentation (MCP addon, index, args and globals URLs, Vitest addon, test runner), the defensive-design canon (Shadeed's Defensive CSS, Speelman's Nine States, the Big List of Naughty Strings, the falsehoods corpus, Netflix pseudolocalization), the accessibility literature (axe-core, WCAG 2.2, WCAG-EM, USWDS test scripts, GDS tool audit, Higley on forced colors), the usability-evaluation canon (Nielsen's heuristics and severity scale, the Lewis and Wharton cognitive walkthrough, Jakob's Law, Friedman's component checklists, and NN/g and GOV.UK content rules), and the reporting traditions of axe, Lighthouse, Playwright, Chromatic, OWASP, and DefectDojo. All cited per concept in the bundle.
1---2name: storybook-pentest3description: Pentest Storybook components two ways. Whether they break under stress, and whether they actually do their job well. Test one story, a component group, or the whole Storybook, and write every finding into an OKF bundle with screenshots, severity, and a reproducible URL. The break pass probes extreme and hostile text, empty and overloaded data, accessibility, keyboard use, zoom, reflow, RTL, dark mode and forced colors, and broken media. The value pass judges fitness for purpose against usability heuristics, asking whether the control is clear, the label specific, the error message useful, and the promise its name makes kept. Use when asked to pentest, stress-test, audit, break, or find edge cases or UX issues in a Storybook, design system, or component; when a component misbehaves with long text, empty states, dark mode, RTL, zoom, or keyboard use, or is confusing or does the wrong thing; or when stories need an a11y or usability sweep. Complements react-stinky (code quality) and visual-consistency (polish).4---56# Storybook Pentest78A UI/UX pentester for Storybook. Stories showcase components in isolation, but the variants a team writes are the happy paths. This skill runs two passes against them. The **attack pass** asks does it break: the edge cases that fail in production (long German compounds, empty lists, RTL, forced colors, a keyboard user in a modal) usually have no story. The **value pass** asks does it do its job: a component can survive every attack and still be the wrong button, with an unguessable control, a generic error, or a promise its name makes and its behavior does not keep. Both write every confirmed failure into a findings bundle with screenshot evidence, severity, and a reproducible URL, so a human or another agent can fix the product. The depth lives in the OKF bundle in [references/](./references/index.md); this file is the procedure.910## Stance: two questions, and honest confidence1112Break and serve are different questions, and the skill answers both. Breakage is mostly objective; fitness for purpose is partly judgment, so the value pass is grounded in named evaluation methods (Nielsen's heuristics, the cognitive walkthrough, Jakob's Law, published content rules) and every value finding cites the method it rests on. Two honesty rails hold throughout. Automated scanning has a measured ceiling (axe-core catches at most about 57 percent of WCAG issues by Deque's own figure; the GDS audit found the best tool caught 40 percent of 142 seeded barriers), so the automated axes give cheap breadth and the simulation and value axes are where the skill earns the word pentest. And every finding carries a `confidence`: confirmed for objective breakage and rule-cited content, needs-review for the genuine judgment calls, which are surfaced as questions for the human, never asserted as defects. Calibration in [a11y-scan.md](./references/attacks/a11y-scan.md); the confidence rule in [finding.md](./references/reporting/finding.md).1314## The layered driving surface1516Never assume one integration; detect, then use the highest layer available. The detection ladder and per-layer capabilities are in [references/surface/](./references/surface/index.md):17181. **Storybook MCP** (`/mcp` endpoint, SB 9.1.16+, Vite): curated docs, changed-story detection, test execution with a11y. No screenshots, no arg mutation, no raw enumeration.192. **The story index** (`/index.json`, fallback `/stories.json`): the ground-truth story list with tags. Works on any SB 6.4+ including static builds.203. **iframe URLs** (`iframe.html?id=X&args=...&globals=...`): render any story in any state. URL args are restricted to alphanumerics, space, underscore, dash, so hostile payloads enter via play functions or Playwright, not the URL.214. **Playwright**: pixels, keyboard, emulation (reduced motion, forced colors, viewport), screenshots.225. **CLI runners** (`npx vitest --project=storybook`, `npx test-storybook --url ... --json`): the project's own test suites with JSON output.2324## Commands2526Invoke as `/storybook-pentest <command> [target]`.2728| Command | What it does |29| --- | --- |30| `sweep` | Pentest the whole Storybook. Enumerate, sample WCAG-EM style (structured sample plus a 10 percent random check plus complete flows), run the planned axes, report. Record what was sampled and what was skipped. |31| `component <name>` | One component, exhaustive. Every story, every applicable axis. |32| `group <path>` | A title-prefix scope, for example `Design System/Forms`. |33| `axis <name> [scope]` | One axis across a scope, attack or value, for example only a11y, only RTL, or only microcopy. |34| `value [scope]` | Run only the value pass: contract, walkthrough, heuristics, and microcopy. Does the component do its job, independent of whether it breaks. |35| `gaps [scope]` | Story-gap audit. Diff existing stories against the required-state matrix (the nine data states plus the interaction states); a missing state is a finding of class untested-surface. Contract gaps (a promised capability with no behavior) come from the value pass. |36| `report` | Rebuild the findings bundle and retest open findings by their stored repro URLs. A fixed finding that reproduces reopens. |37| `triage` | Rank open findings by severity times spread (how many components share the root cause) and propose a fix order. |38| `wire` | Scaffold project-side auto-triggering (CLAUDE.md rule or prompt hook) so design-system changes get pentested without anyone asking. |3940## The pipeline4142`detect -> enumerate -> scope -> plan -> probe -> capture -> grade -> report`43441. **Detect** the target's layers ([surface/detection is in story-index.md](./references/surface/story-index.md) and [mcp.md](./references/surface/mcp.md)).452. **Enumerate** stories from the index; segment by tags (`play-fn` has interactions, `type: docs` is excluded).463. **Scope** the sample and record the boundary. Sampling rules in [reporting/bundle-spec.md](./references/reporting/bundle-spec.md).474. **Plan** axes per story. Attack axes: every component gets content stress, data states, and the axe scan; interactive add keyboard; text-bearing add i18n; themed add theme; animated or async add motion ([attacks/](./references/attacks/index.md)). Value axes: establish the [contract](./references/value/contract.md) first, then walkthrough for interactive components, heuristics for all, microcopy for anything with text ([value/](./references/value/index.md)).485. **Probe** each planned cell. Payloads and procedures live per axis in [attacks/](./references/attacks/index.md) and [value/](./references/value/index.md).496. **Capture** evidence deterministically (reduced motion, fonts ready, play complete, animations disabled): [surface/screenshots.md](./references/surface/screenshots.md).507. **Grade** severity as impact times likelihood via the documented matrix in [reporting/severity.md](./references/reporting/severity.md), and set `confidence`; never grade on a gut call.518. **Report** into the OKF findings bundle in the target repo ([reporting/bundle-spec.md](./references/reporting/bundle-spec.md), record schema in [reporting/finding.md](./references/reporting/finding.md), scaffolds in [reporting/templates.md](./references/reporting/templates.md)).5253## The attack axes (does it break)5455Twelve technical probes, ranked by bug yield; each has payloads and failure signatures in [attacks/](./references/attacks/index.md).5657| # | Axis | Where |58| --- | --- | --- |59| 1 | Text length stress | [content-stress.md](./references/attacks/content-stress.md) |60| 2 | Data-state coverage (nothing/loading/none/one/some/too-many/error/done) | [data-states.md](./references/attacks/data-states.md) |61| 3 | Automated a11y scan (axe per story state) | [a11y-scan.md](./references/attacks/a11y-scan.md) |62| 4 | Keyboard interaction | [keyboard.md](./references/attacks/keyboard.md) |63| 5 | Naughty strings (BLNS Unicode subset) | [content-stress.md](./references/attacks/content-stress.md) |64| 6 | Zoom, reflow, text spacing | [zoom-reflow.md](./references/attacks/zoom-reflow.md) |65| 7 | Pseudolocalization and RTL | [i18n.md](./references/attacks/i18n.md) |66| 8 | Null data and media failure | [data-states.md](./references/attacks/data-states.md) |67| 9 | Dark mode and forced colors | [theme.md](./references/attacks/theme.md) |68| 10 | Interaction-state matrix conformance | [data-states.md](./references/attacks/data-states.md) |69| 11 | Pointer targets and focus obscurement | [geometry-motion.md](./references/attacks/geometry-motion.md) |70| 12 | Motion and layout stability | [geometry-motion.md](./references/attacks/geometry-motion.md) |7172## The value axes (does it do its job)7374Four fitness-for-purpose probes, each grounded in a named evaluation method so findings stay inspectable; full procedures in [value/](./references/value/index.md).7576| Axis | Asks | Method |77| --- | --- | --- |78| Contract | Does it keep the promises its name, docs, and genre make | Genre expectations, Jakob's Law, Friedman's checklists |79| Walkthrough | Could a first-time user actually operate it to the goal | The four cognitive-walkthrough questions per step |80| Heuristics | Does it violate a known usability principle | Nielsen's ten heuristics at component scope |81| Microcopy | Do its labels, errors, and empty states serve the user | NN/g and GOV.UK content rules, the placeholder antipattern |8283## The deliverable8485A conformant OKF bundle at `ui-pentest/` in the target repo: executive summary, scope, methodology with tool versions and configs, a story-times-axis coverage matrix, one findings concept per component with embedded screenshots, and a per-run diff log. Findings have stable ids and a lifecycle (open, verified, fixed, accepted-risk, false-positive) with reopen-on-rescan, so successive runs diff instead of restarting. Spec in [reporting/bundle-spec.md](./references/reporting/bundle-spec.md).8687## Source8889Built from the Storybook 9/10 documentation (MCP addon, index, args and globals URLs, Vitest addon, test runner), the defensive-design canon (Shadeed's Defensive CSS, Speelman's Nine States, the Big List of Naughty Strings, the falsehoods corpus, Netflix pseudolocalization), the accessibility literature (axe-core, WCAG 2.2, WCAG-EM, USWDS test scripts, GDS tool audit, Higley on forced colors), the usability-evaluation canon (Nielsen's heuristics and severity scale, the Lewis and Wharton cognitive walkthrough, Jakob's Law, Friedman's component checklists, and NN/g and GOV.UK content rules), and the reporting traditions of axe, Lighthouse, Playwright, Chromatic, OWASP, and DefectDojo. All cited per concept in the bundle.
saschb2b