| name | storybook-codex |
| description | Create, document, compose, update, review, sync, and audit React, Vue, and Svelte Storybook stories with controls, docs pages, docs-tagged story blocks, composition stories, diff-aware updates, play functions, visual diff hooks, design-token globals, provider decorators, and optional Chromatic scaffolding. Use when the task mentions Storybook, stories, `.stories.tsx`, `.stories.ts`, `.stories.svelte`, `.stories.mdx`, `argTypes`, `CSF`, `autodocs`, `parameters.docs.description`, `play()`, addon-a11y, Chromatic, visual regression, story health, story audit, preview decorators, providers, git diff story updates, Storybook component documentation, or syncing stories between frameworks. Do not use for generic UI design, framework-agnostic styling tasks, or non-Storybook component work. |
| triggers | ["stories","storybook",".stories.tsx",".stories.ts",".stories.svelte",".stories.mdx","argTypes","CSF","autodocs","parameters.docs.description","play()","Chromatic","visual regression","story health","preview.tsx","decorators","providers","git diff"] |
Storybook Codex
Create, document, update, review, sync, and audit Storybook work across React, Vue, and Svelte.
Use this skill for Storybook authoring and maintenance across the UI stacks design-system teams actually ship:
- React components and
.stories.tsx
- Vue single-file components and
.stories.ts
- Svelte components and
.stories.svelte when the repo uses native Svelte CSF
.stories.mdx docs pages or docs-tagged CSF stories when autodocs alone is not enough
Default behavior
- Inspect the repo before editing anything.
- Detect the framework, Storybook version, title conventions, preview globals, and existing story style before choosing a format.
- Detect provider trees, token globals, parent-context usage, and existing docs conventions before generating wrapper stories, docs pages, or preview decorators.
- If the task needs deterministic analysis before editing, run
story_blueprint.py.
- If the task is documentation-heavy, run
story_docs.py.
- Prefer updating the local convention over imposing a generic template.
- Keep stories and docs compact, editorial, and reviewable instead of generating prop cartesian products.
- Use
storybook/test for fn, userEvent, within, and expect when the story needs action logging or a play() flow.
Built-in modes
Blueprint mode
Use the blueprint helper when you need deterministic analysis before writing stories.
python3 skills/storybook-codex/scripts/story_blueprint.py path/to/Component.tsx
It can:
- suggest stories by lens
- mine usage signals from the repo
- suggest parent-context composition stories
- detect prop co-occurrence clusters
- detect props that gate UI branches
- suggest interaction stories
- suggest accessibility stories
- propose a
visual-regression-codex capture set
Useful flags:
--repo-root <path> for usage mining--review-story path/to/Component.stories.tsx for a deterministic story critique--watch for active component work
Docs mode
Use docs mode when autodocs is not enough and the component needs purpose, usage guidance, or implementation snippets.
python3 skills/storybook-codex/scripts/story_docs.py path/to/Component.tsx
Prefer:
- a docs-tagged CSF story when the repo keeps everything in
.stories.tsx or .stories.ts
- a
.stories.mdx page when the repo already uses docs blocks or when Svelte docs should stay separate from story syntax
Docs mode should:
- reuse the existing story title when possible and append
/Docs
- mine two or three real usage snippets from the repo before inventing examples
- generate purpose, when-to-use, when-not-to-use, and prop decision guidance
- use
parameters.docs.description for CSF docs output instead of long comments in the story body
Composition mode
Use composition mode when the component only makes sense inside a real parent or sibling layout.
python3 skills/storybook-codex/scripts/story_composition.py path/to/Component.tsx
It finds:
- likely parent components that already render the target component
- sibling components that affect spacing or focus order
- literal props that can become
args
- expression bindings that should move into a render wrapper or fixture state
Diff mode
Use diff mode when a branch changed component props and the story file should keep up.
python3 skills/storybook-codex/scripts/story_diff_update.py . --diff --write
It can:
- detect changed component files from git diff
- auto-add missing exports for new state or decision props
- append managed diff blocks instead of rewriting the whole file
- flag existing stories that still reference removed or renamed props
Audit mode
Use the audit helper when the task is "review this Storybook repo" or "gate this PR."
python3 skills/storybook-codex/scripts/storybook_audit.py path/to/repo --format markdown
It reports a Story Health Score and flags:
- missing lens coverage
- missing interaction coverage
- missing accessibility coverage
- missing visual regression coverage
- legacy story syntax
- components that still have no story file
Token-aware mode
Use the token helper when stories should reflect design tokens or toolbar globals.
python3 skills/storybook-codex/scripts/token_catalog.py path/to/repo
It detects CSS custom properties and Tailwind-style theme tokens, then suggests globalTypes for theme and density controls.
Decorator mode
Use decorator mode when Storybook needs the app's provider tree.
python3 skills/storybook-codex/scripts/storybook_decorators.py path/to/repo --framework react
It detects:
- React provider trees from
App.tsx, main.tsx, or providers.tsx
- Vue
app.use(...) plugin chains from main.ts
- setup constants like
queryClient or pinia
- preview snippets for
.storybook/preview.tsx or .storybook/preview.ts
Sync mode
Use story sync when the same component exists in more than one framework.
python3 skills/storybook-codex/scripts/story_sync.py src/Button.stories.tsx --target vue
Mirror the story structure, then adapt only the framework-specific render details.
Story design lenses
Use these lenses to avoid flat, repetitive story files:
Baseline: the normal default state every component needs.Decision: size, tone, theme, density, variant, or similar choices.State: disabled, loading, selected, open, error, dismissible, compact.Boundary: long content, dense content, empty-ish content, awkward wrapping, or overflow.Action: fn() handlers and play() flows.A11y: keyboard, focus, labeling, and screen-reader-sensitive states.Visual: stable stories worth snapshotting in Chromatic or Playwright.
Do not force every lens into every component. Use the smallest set that makes the component legible and reviewable.
Story rules
- Default to the extension that matches the local framework and repo convention.
- Use object stories with
Meta and StoryObj where the framework expects them.
- For Svelte repos using
@storybook/addon-svelte-csf, prefer native .stories.svelte files with defineMeta and <Story />.
- Do not generate
Template.bind({}), ComponentStory, or other older CSF2 patterns for new work.
- Prefer component-level
args for shared defaults.
- Add named stories for meaningful states and one interaction story when the component has a real event surface.
- Preserve existing titles, foldering, decorators, loaders, play functions, and docs blocks unless they are clearly obsolete.
Visual regression and Chromatic
- Only scaffold Chromatic when the user explicitly asks for it or the repo already shows Chromatic usage.
- If the repo wants local baselines, use the Playwright visual template in
assets/templates/visual-regression.spec.ts.
- Treat
visual-regression-codex as the mode where story writing and screenshot verification happen together.
Component library heuristics
- shadcn/ui: hide
asChild, focus on the local implementation, and keep stories close to the app's real variants.
- Radix UI: write render wrappers for compound primitives and cover
data-state, keyboard, and focus flows.
- Headless UI: use real composed render trees and explicit focus-trap stories.
References
