# Storybook alignment

Source: https://saer.app/docs/storybook
Updated: 2026-11-12

**Short answer.** When a project has Storybook stories, the full scan compares them with the code: story values a component no longer declares, declared variants no story shows, reusable components without a story where their neighbours have one, and hand-built UI inside stories. `saer ci` warns when a change edits a component's variants and none of its stories. Storybook is never run, and stories are never written.

## What the scan reports

- Story values a component no longer declares: `variant: "primary"` in a story where the Button has no primary variant. Read from `args`, `argTypes` options and JSX.
- Declared variants no story shows. Never reported for a prop a story maps over, because that story shows every value.
- Reusable components without a story, in folders where most components have one.
- Hand-built UI inside stories: a story that teaches a pattern your components already cover.

The results are in the Storybook section of `.saer/report.md`, and in the `stories` section of `system.json`. Agents see a Storybook summary in `saer_overview`.

## On pull requests

`saer ci` warns when a change edits a component's variant definitions (`cva` or `tv`) and none of its stories, and names any removed value a story still shows. A changed story that passes a variant the component does not declare warns too. Raw values and hand-built UI on a story's changed lines warn as documentation findings: stories teach the pattern to people and agents, but they are documentation, so none of these block by default.

If your `saer.config.json` ignores story files, changed stories are not judged; the check for variants changed without their stories still runs, because it reads the component's change. Rule names start with `stories.`, so `"stories.*": "off"` turns them all off.

## What it reads

Component Story Format 2 and 3, `satisfies Meta`, and Storybook 9 `preview.meta()` factories, as text. Storybook is not run, its addons are not loaded and no story is written.
