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/:

1. 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.
2. The story index (/index.json, fallback /stories.json): the ground-truth story list with tags. Works on any SB 6.4+ including static builds.
3. 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.
4. Playwright: pixels, keyboard, emulation (reduced motion, forced colors, viewport), screenshots.
5. 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

1. Detect the target's layers (surface/detection is in story-index.md and mcp.md).
2. Enumerate stories from the index; segment by tags (play-fn has interactions, type: docs is excluded).
3. Scope the sample and record the boundary. Sampling rules in reporting/bundle-spec.md.
4. 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/).
5. Probe each planned cell. Payloads and procedures live per axis in attacks/ and value/.
6. Capture evidence deterministically (reduced motion, fonts ready, play complete, animations disabled): surface/screenshots.md.
7. Grade severity as impact times likelihood via the documented matrix in reporting/severity.md, and set confidence; never grade on a gut call.
8. 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/.

#	Axis	Where
1	Text length stress	content-stress.md
2	Data-state coverage (nothing/loading/none/one/some/too-many/error/done)	data-states.md
3	Automated a11y scan (axe per story state)	a11y-scan.md
4	Keyboard interaction	keyboard.md
5	Naughty strings (BLNS Unicode subset)	content-stress.md
6	Zoom, reflow, text spacing	zoom-reflow.md
7	Pseudolocalization and RTL	i18n.md
8	Null data and media failure	data-states.md
9	Dark mode and forced colors	theme.md
10	Interaction-state matrix conformance	data-states.md
11	Pointer targets and focus obscurement	geometry-motion.md
12	Motion and layout stability	geometry-motion.md

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.