sb-stories

sb-stories — one component, its real states

The default Build mode. The component exists in src/components/; you write its visible-states story.

Before authoring (ask yourself)

• Is it actually used? Check components.real[] in .storybook/project-inventory.json. If it's in dead[], remove it — don't write a story. If it's vendor (shadcn ui/), deprioritize.
• Which states change behavior/appearance materially? Refuse Cartesian combinations. Per-primitive minimum tables in references/anti-patterns.md (Button 8, Input 8, Modal 5, Form 6). Read .storybook/component-states.json instead of guessing — if it's missing, generate it first: scripts/extract-states.sh. (Bigger extraction context: references/extraction-workflow.md.) To render all those states on one canvas, use the StateGrid wrapper (variants × states → StateMatrix) from sb-wrappers — don't hand-roll the grid. These are the component-time wrappers; the data wrappers (ProjectInventory / DesignSystemHealth / AppFlowGraph …) come after their own steps.
• Which states does THIS app actually ship? Read .storybook/component-usage.json (sb-inventory's extract-component-usage.sh — generate it if missing). Use props.<prop>.values to prioritize the variants real call sites pass; for anything in declaredButUnused (e.g. variant=danger never used), still author the state for completeness but tag it ['usage:unused'] and note "not used in this app" — don't pad the catalog with states prod never renders.
• You don't author per-component docs by hand — they're composed once. Every component's autodocs page already gains a "Real usage in this app" band: the UsageSection block (wired once into preview.ts docs.page by sb-setup) renders a "Where it's used" map per component — the pages it lands on, what nests it, what it renders, the tokens it pulls — read from the usage graph (component-pages.json). So when you add a story, don't hand-add a usage block; just run refresh-usage.sh so the graph is current and the band populates. To explore the whole graph interactively (any token / component / page → everywhere it's used, clickable), scaffold the UsageExplorer wrapper (sb-wrappers). Details + the docs.page composition live in sb-inventory (§ "Real usage in autodocs") and sb-setup (docs-page composition).
• Factory? YES if 3+ stories share a data shape. Read .storybook/prop-shapes.json (candidates flagged with liveUsages) — if missing, run scripts/extract-prop-shapes.sh first. Then scripts/scaffold-factory.sh <Type> <import-path> and fill the deterministic stub (references/factory-patterns.md); otherwise inline args.
• Title taxonomy? Match storySort.order; if the project has none, pick one via references/directory-structure.md.
• Does a play actually earn its place? Only write one for an interaction, async data, a portal, a CSS-driven state, or accessibility — never a bare toBeVisible() (anti-pattern 34). And the project needs exactly one CssCheck (anti-pattern 33): one story asserting a real getComputedStyle token value, the only proof the shared preview loaded the app's CSS. Both come from npx storybook ai setup's prompt; validate-stories.sh check 13 + the project tally enforce them.
• A "playground" / showcase story is Controls-driven, not click/hover. If a reviewer asks "what is this playground story — can I click or hover it?": a playground is the default story with its Controls panel — you change args (variant, size, state) in the Controls tab and the canvas re-renders. It is NOT canvas interaction; hover/focus/active live in a StateGrid interaction matrix (addon-pseudo-states), and scripted click→assert flows live in a play function. So: Controls = try props · pseudo-states = hover/focus columns · play = a real interaction. Say which one the story is.
• Is the Controls panel wired? A component story must expose a usable Controls panel — it's the reviewer's prop sandbox and powers the autodocs ArgTypes table. The react-vite default (react-docgen) does NOT infer TS unions into selects, so declare argTypes for every enum/union prop (control: 'select'|'inline-radio' + options), group with table.category, hide escape-hatch / non-serializable props (className, refs, icon / callback / data props), and disable controls on render-only showcase stories (parameters: { controls: { disable: true } }). Full pattern + the docgen gotcha: references/without-mcp.md §13. (The panel itself must be visible — sb-setup writes a manager.ts with showPanel: true; sb-audit's audit-controls.sh flags any component story missing this wiring.)