---
name: "convention-storybook"
type: convention
license: CC BY-NC-SA 4.0
description: Conventions for Storybook and visual regression in Aled's system — the three build modes (code-first, design-first, build-then-refine) declared per project or per feature and the reference each one names, the build-first harvest-from-build model that code-first follows and the blueprint-first trial that is design-first's instance, the component hierarchy, the story coverage bar, async Server Component handling, design-token wiring, client-facing Chromatic publish, Chromatic's two separate roles (the visual-regression gate and the Figma design comparison), the Storybook Connect design↔code bridge, dual-readable autodocs, the Controls-first story rule, and the per-repo instance shape. Read before standing up or extending Storybook on any repo (meirionpritchard-com, careeros-web), before authoring a story set, before declaring or reading a scope's build mode, before scoping or deciding what Chromatic is there to do on a repo, or before breaking down a Storybook ticket. Grown as the conventions solidify.
---

# convention-storybook

How Storybook is used in Aled's system. Follows the same per-repo tool-convention pattern as `convention-vercel` and `convention-github` — one convention, one instance per repo. Grown here as the conventions solidify.

## Role

Storybook is the **component workshop and the source of truth for the UI**. It documents every built component in isolation, gives design and build a shared reference, and is the base layer visual-regression testing runs against. It is a development tool by default, published to a client-facing URL for review (see *Hosting*).

The decisive point: Aled's sites were **built in code, not designed 1:1 in Figma first**. So the real components live in the codebase, and Storybook documents what is actually built — it is not generated from a Figma design system. This inverts the usual design-first flow. Since 2026-09-03 that inversion is one of **three named build modes** rather than the only model (*Three modes*, next): the sections that follow describe the **code-first** mode in full, because it is the default and the one every shipped build so far has used, and say where the other two modes change the reference.

## Three modes — code-first, design-first, build-then-refine

A build declares one of three modes, and the mode says **which side is the reference** — what parity compares against, what a Storybook ticket audits first, and which way a Figma dependency may legitimately point. The mode is chosen by need and context: per project from its starting point, and per journey, feature or component within a project where the need differs. It is not a fixed sequence a project passes through; one project may carry all three.

| Mode | What it is | The reference |
| -- | -- | -- |
| **Code-first** | Built and iterated in code. May draw on library references, Figma files or screenshots, but is primarily a coding exercise. | The built system — the published Storybook, the repo token layer, `standard-design-system`, the venture's `convention-brand`. *The build-first inversion* below describes this mode. |
| **Design-first** | Exacting requirements for layout, styles and components — a site, an app, or a library element — where accuracy and detail are the point. | The design: a Figma file, or a blueprint that sits above both Figma and code. Code is held to it. The A1-231 blueprint-first trial is this mode's instance. |
| **Build-then-refine** | Build quickly in code, then move to Figma (or paper) to iterate and refine, with refinements flowing back to code — roughly the 80/20: the build is code-first, the visual-refinement pass is cheaper to iterate in Figma. | The built system until the refinement pass; from that pass, Figma (or the sketch), whose result flows back to code. The reference flips at a declared point. |

**The mode is declared, never inferred.** It is written on the ticket, the milestone or the phase that carries the scope — one line, `Mode: code-first` (or `design-first`, or `build-then-refine` with the refinement pass named) — so downstream skills read it rather than guess it. `skill-design-parity` reads the declared mode to pick its reference; a Storybook ticket reads it to know whether its first step is an audit of the build (code-first, or build-then-refine before the flip) or a read of the design (design-first, or build-then-refine after the flip). Where no mode is declared the scope is read as **code-first** and the verdict says so — the silent failure this closes is a parity pass that stops on "no Figma link" while the work was never design-first. (Owner ruling, Aled 2026-09-03, APP-660; supersedes the July phase-gate framing, which assumed one journey per project — real builds mix all three by feature. The a1.OS `playbook.website-build` document gains the matching line — each phase or feature declares its mode — by an A1 delivery ticket, not here.)

The mode governs the *reference*; it does not change the bar. `standard-design-system` holds in every mode, and the design system stays aligned across code and Figma whichever side is currently the reference.

## The build-first inversion (the key principle)

The flow is **harvest-from-build, not Figma-first**:

1. **Audit the built components** — read the repo and inventory what actually exists (the component set, their props, their states).
2. **Document them in Storybook** — write a story file per component; Storybook becomes the source of truth for the UI.
3. **Recreate the equivalents in Figma** — once Storybook documents reality, the Figma library is rebuilt *from* it, as a separate design track (see *Figma*).

So a Storybook ticket's **first step is always an audit of what is built**, never "wait for the Figma design system". Any ticket blocked-by a Figma design-system ticket has the dependency the wrong way round and should be inverted — the Figma work is downstream of Storybook, not upstream of it. This holds for every scope whose declared mode is code-first, and for a build-then-refine scope before its refinement pass; a scope declared design-first reads its design first (*Three modes*), and the blueprint-first trial below is design-first's named instance.

### A blueprint-first trial is running — build-first stays canon until it reports

Build-first above is still the code-first model. A trial of the **opposite ordering** — the design-first mode, in its blueprint-above-both form — is live on one named scope, and canon is deliberately left unamended on *how* design-first is run until it reports. The three-mode definition already establishes *that* design-first exists as a mode; APP-613's verdict informs how it is done, not whether it is available.

**D029** (`log.meirion-decisions`) and epic **A1-231** adopt **blueprint-first** for the meirionpritchard-com **Work section only**: a DS blueprint (`spec.meirion-design-system`) sits above both Figma and code, both legs are generated from that one spec in parallel, and are then bound. The reason was specific rather than general — the shipped build's structure would not survive being read as a design system, so harvesting Figma from it would have inherited the build's structural accidents.

- **Inside that scope, the inversion rule does not apply.** A1-14 (the Figma Work-section library) is a *parallel leg generated from the shared spec*, not a downstream Figma-first dependency, and A1-237 (bind, via Storybook Connect) legitimately waits on it. Do not invert those dependencies.
- **Everywhere else, build-first stands** — careeros-web and any repo with a shipped build to document.
- **The verdict is not taken.** It is A1-231's closing definition-of-done item. As of 2026-08-10 the trial has run most of its length — A1-14 is Done bar the one manual Figma library publish, and A1-237 is still Todo with Aled — but it has not reported. Whether blueprint-first becomes the general precedent (and whether the sequence needs a `playbook-design-system` alongside this convention) is held on **APP-613** until it does. Do not pre-empt it here.

## Repos and instances in scope

One convention, a per-repo instance — like Vercel and Sanity.

| Instance | Repo | Status |
| -- | -- | -- |
| meirionpritchard-com | assoc-one/meirionpritchard-com | **Lead instance** — first build (A1-15). Clean slate; the convention lands here first. Its Work-section design system has since moved to the blueprint-first trial (A1-231); see the trial note above. |
| careeros-web | assoc-one/careeros-web | Has live Storybook work (COS-148 foundation, COS-156 stories, COS-159 Chromatic, COS-167 structure). Reconciles to this convention once it is saved. |

Both are Next.js / React / TypeScript repos, so each instance uses the Next.js framework preset, CSF3, and TypeScript stories.

## Structure and hierarchy

Organise the sidebar as a **layered hierarchy**, deepest primitives first:

`tokens → assets → components → sections → templates`

- **Tokens** — colour, type, spacing, radius, shadow (docs pages, from the real token source; see *Design-token wiring*).
- **Assets** — icons, logos, imagery.
- **Components** — the atomic UI set (button, input, card).
- **Sections** — composed blocks made of components (a hero, a work-list row).
- **Templates** — page-level compositions.

Set this with the story `title` / `component` meta and the folder layout. Story files live **alongside the component** (`Button/Button.stories.tsx`), never in a separate stories tree — the co-located file is development-only and excluded from the production bundle. (COS-167 is the careerOS planning ticket on exactly this hierarchy; it generalises to here.)

## Story authoring standard

- **CSF3, TypeScript.** `Meta`/`StoryObj` typed against the component; `satisfies Meta<typeof X>`; UpperCamelCase named exports for stories. This is the current Storybook standard (v10, CSF3).
- **Autodocs.** Tag stories for autodocs so each component gets a generated docs page from its args and types — the docs bar comes for free rather than being hand-written.
- **Autodocs are written for two readers — human and machine.** Document every prop with TSDoc/JSDoc on the prop interface and a component-level doc comment: it renders as the human props table *and* sits in the type layer the Figma MCP / AI consume. Prose ("when to use", gotchas) goes in `parameters.docs.description`; every prop is described in TSDoc so it lands in both the table and the types. The machine/AI channel is Storybook's generated `index.json` plus typed CSF — derive both from one source, never hand-maintain a separate spec.
- **Args over hardcoding.** Drive state through `args` so Controls work; compose args across composite components (a section reuses its components' story args) so a prop change updates in one place.
- **Controls first: if Controls or the native viewport toolbar can reach a state, that state does not get a story of its own.** Owner decision, 2026-09-24: *"The native viewport selector covers the viewports, and the controls cover off the columns … I don't think we need different stories when the controls manage it perfectly."* A story exists to name a state worth returning to, not to enumerate the state space. Four consequences, and they are the whole rule:
  - **The named anti-pattern is a story per viewport and a story per column count.** Storybook's viewport toolbar already switches width on any story, and a column count is an arg. Pinning stories to viewports (`globals.viewport`, `chromatic.viewports`) to satisfy "desktop, tablet and mobile coverage" multiplies the file without adding one state a reviewer could not already reach — and it multiplies the Chromatic snapshot bill with it (*Gotchas*: cost scales with stories × browsers).
  - **Exhaustive variant-and-output listing belongs in the component's docs page, not in stories.** Autodocs plus the props table is where "here is everything this can do" is legitimately complete (*Autodocs*, above), and the Owner's direction is explicit that documenting the full set there is fine.
  - **Keep a fixed story only for a state Controls cannot express.** On a shared-Controls playground that means independent per-item states within one row, deliberately uneven content lengths, and the empty / no-media placeholder — each needs its own args object precisely because one set of Controls cannot hold two different values at once.
  - **The playground-wrapper question follows from the same rule and is not a second convention.** Put `argTypes` on the **real component** wherever its props are flat enough for Controls to bind them. Add a `…Playground` **wrapper** component only where the real prop is a shape Controls cannot bind into — an array of items, a deeply nested object — and the wrapper's only job is to expose flat args and assemble that shape. The wrapper is a Controls adapter, justified by what Controls cannot reach and by nothing else. (Worked pair: `ImageAssetBlock`, whose real prop is an `assets[]` array and which therefore ships a playground wrapper, against `Split`, whose props are flat and which carries `argTypes` directly — the pair A1-472 could not explain intuitively, which is what this rule closes.)

  **This also shapes how a story ticket's criteria are worded.** A criterion reading *"stories cover desktop, tablet and mobile"* is the transmission path for the anti-pattern: it reads as *a story per viewport* when *reachable in the viewport toolbar* was the intent. Write the criterion as the reachability it means. The AC-authoring half — how a story ticket is framed so it cannot be read the wrong way — belongs to the ticket convention and the exec skill, not here; this row states only the shape a criterion has to take, the same division the *Async Server Components* row already uses.

  **The Owner also asked for an end-of-phase consistency sweep, and that is a ticket, not a canon row.** Once this rule is written, one sweep pass across the existing story set applies it together with structure (hierarchy, co-location, playground-vs-direct `argTypes`) and naming (titles, export names, story names). Filing and sequencing that sweep is the delivery lane's; it is named here so it is not re-derived, and it is explicitly not part of A1-476 or A1-522. (Worked cases, both the anti-pattern: `ImageAssetBlock.stories.tsx` on PR #178 (A1-476) and `VideoAssetBlock.stories.tsx` on PR #181 (A1-522), each carrying 12 viewport × layout stories — desktop / tablet / mobile × full-width / 2-col / 3-col / captions-off — plus a no-media story and a playground. Confirm the story counts and the `globals.viewport` pinning against `assoc-one/meirionpritchard-com` `origin/main` for both files before writing a per-file claim; expected 12 viewport × layout exports in each. APP-1626.)
- **Interaction and states.** Use the `play` function for interactive states (a filled form, an open menu) so the state is captured, not just described.
- **Declared box.** A story renders its part at its declared box standalone. Where a part's width or height resolves only as a flex item inside a host — a handle, a divider, a rail, anything whose size is given to it rather than owned by it — the story supplies that host, or an explicit box standing in for it, so the part is rendered at the size it ships at rather than at whatever the bare canvas collapses it to. A story is accepted **rendered**, not merely present: the acceptance is that someone or something looked at the rendered frame and saw the part at its box, and a story that loads without error while drawing nothing has not met the bar. The nearest existing rule is about **measurement** rather than authoring — it governs reading a value off a rendered story — so a part with no intrinsic size falls between the two, authored correctly by the letter of this section and rendered as nothing. The gap carries on a single Owner-caught instance because the pipeline offers no second chance at it: the visual surface is publish-only, nothing gates a story on what it draws, and the next collapsed part is found the same way or not at all. (Worked case: a drag handle whose width resolved only inside its flex host collapsed to a single dot when storied alone, and was found by the Owner reading the published surface — not by CI and not by a QA pass. The flex-sizing mechanism behind that collapse, the stories involved and the publish-only shape of the visual build are **unverified** here: no repo is readable from the refine surface, so none of the three was re-read, and the rule is written to be worth having even if the mechanism is something adjacent — APP-2383.)

### Async Server Components (RSC)

`@storybook/nextjs-vite` — the framework preset both instances use — has **no React Server Components support**: an `async` function component cannot be mounted in a normal client render, and `next/headers` APIs (`draftMode()`, `headers()`, `cookies()`) throw outside a real Next.js request context. A component that is, or composes, an async Server Component therefore cannot be storied as-is.

- **The standard resolution is the split pattern:** extract a presentational, props-driven client-renderable component carrying all the visual surface; story *that*; leave the thin async data-fetching wrapper unstoried. The wrapper's job is data acquisition, not UI — the coverage bar is met by the presentational component.
- **The split is structural work, scoped at refine — not discovered mid-exec.** The audit step (step 1 of the inversion) should flag components that are or compose async Server Components, so a coverage ticket either includes the split in scope explicitly or excludes those components explicitly. A "just add stories" ticket that hits an unflagged async Server Component stops short: Block or bounce for scoping rather than silently shipping partial coverage or unilaterally refactoring a production component's structure. (Worked case: A1-200, `SiteNav`/`SiteHeader` on meirionpritchard-com, 2026-07-10.)

## Story coverage bar

**Start with the Work-section set, then widen.** The bar is not "every component from day one" — the lead instance proves the pattern on the Work section (the components and sections that make up the work list and case-study surfaces), then extends outward to full coverage. Token and asset docs pages are part of the bar from the start; full component coverage is the destination, reached iteratively. This sequencing also lets Chromatic come in cleanly once there are stories to baseline (see *Visual regression*).

## Design-token wiring

Tokens flow **from the real token source into the stories**, so Storybook reflects the live system rather than a hand-copied palette. Wire the repo's actual token layer (CSS variables / Tailwind theme / token file) into `.storybook/preview` so components render with production tokens, and expose the tokens themselves as docs pages under *tokens*. If a token changes in the codebase, the stories reflect it without a second edit.

## Hosting

**Local by default, publishable to a client-facing URL.** `storybook dev` for development. For client review, **publish to Chromatic** and share an open-access link — the shared reference the client and team point at ("change that colour / tweak that component"). Chromatic over a plain static host because it adds **in-place commenting** on stories (the review conversation) and is the same publish that powers Storybook Connect. Chromatic is the default for client *review* because of the in-place commenting, and a plain static host loses that. **It is not an either/or with a Vercel build, though — where a client-facing domain is wanted the two run together**, Chromatic carrying the review conversation and a Vercel project additionally serving `storybook.<client>.assoc.one` off `main`. See *The Vercel client-domain instance* below.

The publish is the base capability. What Chromatic then *does* with it splits in two — see below.

### The Vercel client-domain instance

A client-facing `storybook.<client>.assoc.one` domain is a **second** publish alongside Chromatic, not a replacement for it, and it is a per-instance row like every other Vercel project (`convention-vercel`, *Projects in scope*, which holds the row itself — not restated here).

**Provisioning.** A Vercel project named `<client>-storybook`, linked to the **site's own repo** rather than a separate one, serving production only. Framework preset **Other** (the API reports `framework: null`) — this is not a Storybook preset and the build settings will not be inferred, so install, build and output must be set by hand to the repo's own Storybook build and its static output directory. Preview deployments are **disabled**: the domain exists to serve `main`, and a preview per PR is Chromatic's job. **Vercel Authentication must be off for production**, or the client cannot open the link. Provisioning is not `exec:human` by default: a surface holding the Vercel connector does it (`convention-vercel`, *Setup — new Vercel project*); granting the Vercel GitHub app access to the repo and confirming the production URL stay the Owner's.

**Policy — the domain is `noindex`.** Decided on A1-574 and it is the default for every instance: a client-internal reference tool has no reason to be indexed. Decide it at provisioning rather than discovering it after the domain is public.

**Verification — and it cannot be done from an agent sandbox.** Two checks close the instance: an unauthenticated request against the domain returning `200`, and `/index.json` returning a real story manifest (the same manifest the story-id routes above read). Sandbox egress blocks the domain, so **both must run from a real network** — an attended session or the Owner's own machine — and a dashboard settings read-back is needed besides, because the Vercel API does not echo the install, build and output values back. That combination is a named lane requirement, not an obstacle to work around: `convention-agent-runtime` (*A ticket can need a capability combination no lane holds*) holds the routing rule, and a ticket scoping one of these instances carries its verification as a last-mile item from the start rather than discovering it at the end. (Worked case: A1-574 on `meirionpritchard-com`, built 2026-09-30 and closed 2026-10-13, the 13-day gap being exactly this — APP-2309, APP-2308. Read live against the Vercel project on 2026-10-13: the project is `meirionpritchard-storybook`, the domain `storybook.meirionpritchard.assoc.one` resolves on it, `framework` is `null`, and both password and SSO protection are disabled — so the auth-off and framework rows are observed. The install, build and output values, the disabled previews and the `noindex` are **unverified** — the API does not return them, and they are written here as the pattern to set, not as a reading of that project.)

### Review links deep-link to the story under review — never the bare Chromatic root

**Pick the surface from what changed.** A component or design-system change is reviewed in its **published Storybook story** on the PR's Chromatic build. A page or flow change is reviewed on the **full-page deploy preview**, where the block is seen in the context of a real page. The default is not "whichever preview link is easiest to find first": a full-page preview handed over for a component review makes the reviewer hunt the component in context, which is the thing Storybook exists to avoid.

**Build the deep link from the story source. Never guess it, and never hand over the root.** The bare Chromatic root (`https://<build>.chromatic.com/`) opens on whatever story is default or was last active, so it lands somewhere unrelated to the review. The recipe:

1. Read the component's own `.stories.tsx` and take its exact `title` (from the default export) and the story **export names**.
2. The story id is kebab-case(`title`) + `--` + kebab-case(export name) — a title of `Blocks/Split` with export `CaptionOff` gives `blocks-split--caption-off`.
3. Link `<chromatic-build-url>/?path=/story/<story-id>`.
4. **One link per changed story** — the stories actually relevant to what changed, not every story in the file, and never the root.

Where the Chromatic build URL itself is read from is `convention-github`'s row (*Chromatic — the "UI Tests" pending-baseline status*), which is the single place that route is stated — do not restate it here, so the two cannot drift. (Worked case: a live review session on A1-472, `meirionpritchard-com`, 2026-09-22 — the first link handed over was the whole site's deploy preview, the second the bare Chromatic root; the Owner's correction was that a block review goes via Storybook, and directly to the story. APP-1653.)

### Driving a built Storybook as the runtime (the verification route for a DS-only component)

A component built deliberately **not wired into any route** — no `Block` union entry, no `renderBlock` case, nothing rendering it in the app — has no app path to drive, so runtime-geometry and runtime-behaviour claims about it are verified against **Storybook as the runtime**. The commands live here; `skill-review-pr` points at them rather than re-deriving the route per run.

1. **Build** the Storybook from the pinned head: `npm run build-storybook`. The built artefact is the subject, not `storybook dev`.
2. **Serve** the `storybook-static` output with its own static server — it needs one of its own; the built Storybook is not driveable straight off the filesystem.
3. **Take the story IDs from `storybook-static/index.json`**, never guess them. They are the same ids the `?path=/story/<id>` review link uses.
4. **Drive `iframe.html?id=<storyId>&args=…`** in the sandbox's own Chromium. `iframe.html` renders one story without the Storybook shell, and `&args=` drives a story's variant states (a caption on or off, a column count) without needing a story per permutation.

5. **Force media to load before measuring anything geometric — a lazy asset measures as absent, and that is a false green.** `loading="lazy"` images inside a story or desk-check iframe are never scrolled into view, so they never load, contribute no intrinsic height, and a layout whose box depends on the asset's own dimensions reads as the **declared** ratio rather than the **rendered** one. Before taking any measurement: scroll each `img` / `video` into view and wait for `complete` / `loadedmetadata`, or drive `loading="eager"` through `&args=`. **Then take the negative control from the measurement itself — measure once unloaded and once loaded.** If the two readings differ, the layout depends on intrinsic size and the loaded reading is the only one that counts; if they agree, the lazy question is moot and you have demonstrated that rather than assumed it. This is cheap, and it is the difference between an instrument that can fail and one that cannot. (Worked case: A1-476, `ImageAssetBlock` on `meirionpritchard-com` PR #178, 2026-09-23 — the desk-check tool read the new 16:9 block at exactly 1.778:1 at 1440, 1024 and 375; a Playwright spec that scrolled each image into view and waited for `complete` measured the same layout at **1.35:1**, a loaded portrait image's own height having stretched the grid's `aspect-ratio` box. The defect was real and was fixed before merge — the instrument used for the review would have passed it. One instance. APP-1734.)
6. **Take the negative control from the same build.** A sibling component in that build which genuinely lacks the property under test gives a demonstrated red at zero cost, which is how the instrument is shown able to fail.

7. **Read a play function's verdict from the addons channel's `playFunctionThrewException`, and from nothing else — `currentRender.phase` and `storyFinished.status` cannot fail.** Where the acceptance criterion is a story's **play function** — an assertion run inside the story, rather than a geometry measured from outside it — driving `iframe.html` directly gives no interactions panel, and the two instruments a leg reaches for first report success on a play that threw: `window.__STORYBOOK_PREVIEW__.currentRender.phase` reads `"finished"` whether the play passed or failed, and the channel's `storyFinished` event reports `status: "success"` in both cases. They appear to reflect the render rather than the assertion. Both are named here so the next leg does not reach for them and call the reading a pass. The route that does work: **before navigation**, `page.addInitScript` subscribing to `window.__STORYBOOK_ADDONS_CHANNEL__` — retrying until the channel exists, since it is not present at document start — and record **`playFunctionThrewException`**. It carries the assertion message, and it is the verdict: fired means failed, absent at story end means passed. A console `AssertionError` is a corroborating second signal, never the primary one. **The negative control is a planted CSS break** — an override injected by the same `addInitScript` before load, breaking the box the play function asserts on — which makes the play throw at no cost and demonstrates the instrument can fail, in the shape step 6 asks for. **Unverified premise, and only this one:** every claim here about what the three instruments report is **reported** from one QA leg on one Storybook version, with no repo readable from the authoring surface. So the rule to carry forward is the method rather than the version-pinned fact — **accept no play function's pass from any instrument until that instrument has been shown to go red on a planted break** — which holds whatever a later version renames or fixes, and which is what would have caught `phase` and `storyFinished` in the first place. (Worked case, **reported**: the A1-759 QA leg, `assoc-one/meirionpritchard-com` PR #252, head `2ebef2c`, 2026-10-21, on Storybook 10.4.6 and chromium-1194 — `phase` read `"finished"` and `storyFinished` read `success` both on a clean run and on a planted break that made the play throw `expected 12 to be 20`, while `playFunctionThrewException` fired only on the break. The builder's PR had stated outright that the play function's own pass/fail was never read. Two turns' cost; one run, one version. APP-2566.)

(Worked case: the A1-462 QA leg, `meirionpritchard-com` PR #161, head `4def498`, 2026-09-22. The ticket was a DS-only component whose acceptance criteria were all runtime claims; this route was decisive, finding a real defect — the video frame leaving its fixed 16:9 whenever a row's columns were uneven — that no static reading surfaced and the PR's own claim denied. `ImageAssetBlock` on the same head carried no `aspect-ratio`, so the same assertion pointed at it went red and proved the instrument could fail. Every step of it was re-derived live, which is what this section closes. APP-1649, APP-1099.)

## Chromatic serves two roles — keep them separate

Chromatic does two different jobs on a repo, and they are easy to conflate because they run on the same publish and the same account. They have different comparators, different reviewers, different prerequisites, and only one of them holds up a merge — so they are scoped, deferred, and decided **separately**.

| | Visual-regression gate | Figma design comparison |
| -- | -- | -- |
| **Compares** | this build's snapshot against its own **previously accepted snapshot** | the rendered story snapshot against the **linked Figma frame** |
| **Answers** | did this PR change pixels that were previously accepted | does the built component match the design |
| **Surface** | the *"UI Tests"* commit status on the PR, plus Chromatic's accept/deny review UI | Chromatic's web app, showing design and code side by side |
| **Needs** | stories and a baseline | the published Storybook plus Storybook Connect links to **published** Figma components |
| **Holds up a merge** | **no, as of 2026-08-13 (APP-854 — gate deferred by Owner)**; formerly yes, via a human acceptance step | no — it is a review surface, never a merge gate |
| **Useful from** | the first baseline onwards | only once linked components exist |

Three consequences worth stating, because they are what the conflation costs:

- **Only the regression gate has an open scope question — and as of 2026-08-13 it is answered "deferred" (APP-854).** The per-PR baseline round-trip it produces is the friction captured on APP-621 — and the options there (narrow it with TurboSnap, batch baseline acceptance at an existing approval touchpoint, or defer the gate) are decisions about *that role only*. The Owner chose **defer**: the regression gate is decoupled from the merge path (assoc-one hit the Chromatic free snapshot cap, and the per-PR acceptance was being waved through blind). The publish and the future design-comparison role are untouched. Its pending *"UI Tests"* status was a human acceptance step, not a CI wait — never poll it. `convention-github` (*Chromatic — the "UI Tests" pending-baseline status*) holds the (now-retired, reinstate-able) route and the reinstate lever, and is the single place that route is stated — do not restate it here, so the two cannot drift.
- **On the lead repo the gate is retired in the workflow, not merely decoupled from the merge path (D042, 2026-08-23, A1-354).** "Deferred" above describes the merge gate; on `assoc-one/meirionpritchard-com` the Chromatic workflow itself no longer runs UI Tests or UI Review and only builds and publishes the Storybook, so on that repo there is no pending baseline for a verdict to report and no feeder to fold into one. Read the deferral as general and the retirement as **per repo, from that repo's own `.github/workflows/chromatic.yml`** — careeros-web is unread and may still run the gate. (Workflow contents and D042's scope **unverified** from the refine surface; that flag covers those two claims only. APP-2123.)
- **The design comparison is gated on the Figma track, not on the regression decision.** It needs published Figma components with Storybook Connect links resolving against them, which is Pixel's design track producing something to link against. It is worth nothing on a first baseline pass, and narrowing or deferring the regression gate does not touch it. (Worked case on meirionpritchard-com: A1-14 generated the Work-section library and is Done bar the manual publish; A1-237 re-points the existing Storybook Connect links from A1-202 at the blueprint names. Until both land, there is no design comparison to have.)
- **So "do we keep Chromatic as a review layer?" has two answers, not one.** Deferring the regression gate leaves the design comparison intact; dropping Chromatic altogether costs both, including the client-facing publish and its commenting (see *Hosting*). Answer the two separately, and say which one a scope decision is about.

The skill-merge-pr side of this — how the merge leg tells the pending baseline status apart from ordinary red or missing CI, and that the design comparison is never a merge gate — is a separate edit to `skill-merge-pr`, not authored here.

## Visual regression — Chromatic (deferred until stories exist)

This is the first of the two roles above. Visual regression runs on **Chromatic**, added **after** the first stories exist, not stood up with the empty convention — an empty baseline is noise. The careerOS decisions (COS-159) are the standard, generalised here:

- **Chromatic free plan**, project per repo.
- **GitHub Action** under `.github/workflows`, running Chromatic on PRs.
- **All-stories baseline** — snapshot the full story set.
- **TurboSnap off** to start. TurboSnap only re-snapshots stories whose dependencies changed (via the build's dependency graph), which is a real saving at scale, but it adds moving parts — full rebuilds on `preview.js`/config/lockfile changes, and rebase/squash edge cases — that are not worth it until the story set is large. Turn it on once snapshot volume justifies it, or if narrowing the baseline round-trip is chosen on APP-621.
- **Chromium-only** to start, to keep snapshot count and cost down; add browsers later if needed.
- **Baselines are CI-rendered and committed back by a workflow — the sandbox is never the arbiter for a screenshot.** A delivery sandbox renders a different page from CI (egress-blocked fonts and content, the framework's dev-tools overlay) and cannot fetch CI's own report artefact, so a baseline written there bakes those differences in and every later CI run fails against it. The mechanism — the `update-snapshots` workflow, the overlay-hiding `stylePath`, the label-versus-dispatch triggers, and the API approval of the bot commit's own runs — is stated once in `convention-github` (*Screenshot baselines are CI-rendered, never sandbox-rendered*) and deliberately not restated here, the same discipline as the Chromatic build URL above. What belongs on this side is only the bar: **a story's baseline is accepted from a CI run, and a screenshot diff is adjudicated by a person — never by the sandbox that produced the change.** (Owner decision 2026-09-24; evidence APP-1717.)

### Credential split (how a Chromatic setup ticket is broken down)

Chromatic needs a project token that only Aled can create, so split the setup the same way as any credential-gated work (the APP-230 pattern, worked on COS-235 / COS-236):

- A **human leaf** — Aled creates the Chromatic project and adds the token to the repo's GitHub secrets. Labelled `human`, assigned to Aled.
- An **agent leaf** — add the GitHub Actions workflow and document the review flow. **Blocked-by** the human leaf, so it only runs once the secret exists.

This keeps the agent work from stalling on a secret it cannot set, and gives Aled a clear, isolated action.

## Figma (separate design track)

Recreating components in Figma is **not part of this convention** — it is a downstream design track that starts *once Storybook is the source of truth*. This convention ends at "the built UI is documented in Storybook". The Figma rebuild (harvest-from-build → recreate) is its own body of work, sequenced after, and owned by the design side (Pixel). Keeping it separate stops the Storybook rollout from being blocked on Figma, which is the whole point of the build-first inversion. (Under the A1-231 trial the two legs run in parallel from one spec instead; that is scoped to the trial, not a change here.) How a design-system Figma file is organised — pages, doc frames, where a main component lives — and the structural bar a Figma build is reviewed against are `convention-figma`'s; this convention ends at the code side.

## Figma design↔code bridge

Three distinct things; do not conflate. The first is a navigation link, and it is also the prerequisite for the design comparison above.

- **Storybook Connect (the link we use)** — free Figma plugin linking a Figma component to its live Storybook story, both directions. Needs the Storybook published to Chromatic (the client publish already does this) and works on **current Figma Pro** — no upgrade. This is the design↔code link, and the links it creates are what the **Figma design comparison** renders against; the plugin is the bridge, Chromatic's web app is the comparison surface.
- **Code Connect (deferred)** — Figma's deeper bridge: a literal code snippet in **Dev Mode** Inspect, powering the Figma MCP. Requires **Org/Enterprise + Full/Dev seat**, not Pro. The CLI is open-source but Dev-Mode display still needs the paid plan. Adopt only when human devs need code in Figma and the library/Figma rebuild justify the Org cost. (De-scoped from A1-237 on exactly this ground, 2026-07-23.)
- **Figma Console MCP (Pro-plan alternative to spike)** — TJ Pitre / Southleft, `github.com/southleft/figma-console-mcp`. An MCP server giving AI full access to the Figma project as JSON plus bidirectional token sync; may not need the Org upgrade. Does **not** give human devs Dev-Mode code snippets. Spike licence/auth before committing to Enterprise if the goal is AI-facing.

## What requires human action

- Creating the Chromatic project and adding its token to GitHub secrets (account-level; the human leaf above).
- Publishing Storybook to Chromatic and sharing the client link (account-level).
- Installing Storybook Connect in Figma and linking stories (design-side, one-off per component) — and **publishing the Figma library** it links against, which is a one-click step in Figma's Assets panel that no plugin API can perform (A1-14, A1-237).
- Any deployed/published Storybook hosting (account-level on the host).
- Accepting or rejecting visual changes in Chromatic's review UI — the regression role's acceptance step, and the reason its status never concludes on its own.

## Rollout

- **meirionpritchard-com (A1-15)** was the lead instance and was executed under build-first: audit what's built, scope the first stories to the Work-section set, defer Chromatic to a later leaf (with the credential split) once stories exist. Its Work-section design system has since moved to the **blueprint-first trial** (D029 / A1-231), so the "invert any blocked-by A1-14 dependency" instruction that once applied to this repo is historical — A1-14 is now a parallel leg from the shared spec. See *A blueprint-first trial is running*.
- **careeros-web** reconciles its existing Storybook tickets (COS-148/156/159/167) to this convention once saved — the hierarchy, coverage bar, and Chromatic decisions here supersede the ad hoc careerOS versions. Build-first applies here unchanged.

## Gotchas

- Story files must be **co-located** with components and excluded from the production build — a stray stories tree in the app bundle ships dev-only code.
- **Don't gate Storybook work on Figma.** The build is the source of truth; a Storybook ticket blocked-by a Figma design-system ticket has the dependency inverted (see *The build-first inversion*) — **except** inside the A1-231 blueprint-first trial on the meirionpritchard-com Work section, where both legs come from one spec and the dependency is deliberate. A scope declared **design-first** (*Three modes*) is the same exception by definition — the design is the reference and the dependency is deliberate. Check the declared mode before inverting anything.
- **Chromatic's two roles are not one thing.** The regression gate compares a build against its own last accepted snapshot; the design comparison compares it against the linked Figma frame. Different prerequisites, different reviewers, and only the first holds up a merge — never let a scope decision about one silently settle the other (see *Chromatic serves two roles*).
- **The pending *"UI Tests"* status is a human acceptance step, not a CI wait** — it never concludes on its own, so polling it burns the window. `convention-github` holds the route it takes.
- **Async Server Components can't be storied as-is** — `@storybook/nextjs-vite` has no RSC support; use the split pattern and scope the split at refine (see *Async Server Components (RSC)*).
- **Storybook Connect ≠ Code Connect.** The plugin (free, Pro) is the link we use, and it is what the design comparison needs; Code Connect (Org/Enterprise) is the Dev-Mode code-snippet feature. Don't cite the plan gate against the plugin.
- **A Storybook Connect link resolves only against a *published* Figma library** — the file existing is not enough, and the publish is a manual one-click step (A1-14). A design comparison that shows nothing is usually this, not a broken link.
- **Chromatic full rebuilds** are triggered by changes to `preview.js`, the Storybook config, the static dir, or an out-of-sync lockfile — keep global decorators lean and the lockfile in sync to avoid re-snapshotting everything (matters more once TurboSnap is on).
- **TurboSnap and rebases/squashes** behave like merges (union of both ancestors' changes), so a squash-merge can re-snapshot more than expected — a reason to leave TurboSnap off until the story set is large enough to need it.
- Chromatic snapshot cost scales with stories × browsers — starting Chromium-only and Work-section-first keeps the free plan viable.
- **A state Controls or the viewport toolbar can reach does not get its own story.** A story per viewport or per column count is the named anti-pattern; exhaustive variant listing belongs in the docs page; a `…Playground` wrapper is justified only where the real prop is a shape Controls cannot bind (APP-1626; see *Story authoring standard*).
- **Lazy media measures as absent.** Before any runtime-geometry measurement in a story or desk-check iframe, force images and video to load and take an unloaded-versus-loaded negative control — a `loading="lazy"` asset contributes no intrinsic height, so the layout reads as the declared ratio rather than the rendered one (APP-1734; see *Driving a built Storybook as the runtime*).
- **A screenshot baseline comes from CI, never from a sandbox** — and a diff is adjudicated by a person. `convention-github` holds the workflow mechanism (APP-1717; see *Visual regression*).
