---
name: "skill-design-parity"
type: skill
description: 'Review a UI build against its intended design and write a plain-language verdict Aled can act on without reading the code. Use this whenever running the design-parity pass, or when a ticket in In Review carries PR-1SM and has a design reference to compare against — flag divergences in layout and spacing, design tokens, colour and type, missing states, responsive behaviour, and component substitutions. Reads the scope''s declared build mode (code-first, design-first, build-then-refine — convention-storybook) to pick the reference: the built system, the design or blueprint, or Figma at the refinement pass. Folds any Chromatic build into the one verdict. Also carries the Figma structural pass, reviewing a Figma build against convention-figma''s structural bar. A feeder into the single sign-off gate — the Linear ticket, mirrored on the PR, held by Aled — never a gate itself: review only, never merges or advances a ticket. Trigger it to design-QA, check design fidelity, or review a Figma build''s structure.'
license: CC BY-NC-SA 4.0
---

# design-parity

A design-fidelity review pass — the pair of eyes that confirms a built interface matches the design it was meant to implement, made legible to Aled without him reading code or opening every screen himself. Sibling to skill-review-pr: same shape, same gate discipline, a design lens. Formalises the prototype-port regression guard (Linear APP-267). Follows convention-linear, convention-github, convention-storybook, standard-design-system, convention-brand, Pattern A, and the gate policy (Aled is the approver; nothing merges without him).

This is **review only**. It compares build against intent and reports divergences. It never edits the build and never changes ticket state.

## Trigger

Poll for issues in In Review carrying `PR-1SM` where the ticket has a design reference to compare against. A Figma link is one such reference and, on code-first work, usually not the one — read *What parity compares against* before concluding a ticket has none. Stop only when there is genuinely no reference of any kind: no Figma spec or prototype, no published Storybook, no design-system or blueprint the build was meant to implement. In that case note it on the ticket for Aled and stop. Delivery projects only; never the Pipeline team. A ticket whose deliverable is a Figma build rather than a UI build takes the *Figma structural pass* below instead of the checklist.

## Dedup — one parity verdict per PR state

Keyed on the PR head commit SHA, not elapsed time, so the review re-runs after an In Review to Todo bounce where exec pushes new commits.

1. **Fetch the PR's current head commit SHA.**
2. **Scan existing PR comments** for any comment that starts with `[design] HEAD: [sha]` where `[sha]` is the first 7 characters of the current head commit SHA. Use this as the dedup key.
3. **If a match is found:** skip silently — no comment, no state change.
4. **If no match:** proceed with the full review below.

Every verdict comment **must** begin with:

```
[design] HEAD: [sha7]
```

where `[sha7]` is the first 7 characters of the PR head commit SHA. This line is the dedup key.

**Where one leg runs both passes, the parity verdict folds into the `[qa]` verdict as a named section.** *Dedup — one parity verdict per PR state* exists so that one PR state carries one parity verdict; a second comment beside a `[qa]` comment the same leg has just posted is that same duplication reached by another route — two verdict surfaces for one review of one head. So where a single Prism leg runs the QA pass and the parity pass on one PR, it posts **one comment per surface**: the `[qa]` verdict, carrying a `Design parity` section whose first line is the `[design] HEAD: [sha7]` key **verbatim**, then the parity verdict in the usual two modes. Two things make that safe. The key is reproduced byte-identically, because it is the string the next run matches on. And a folded verdict no longer *starts* with the key, so step 2 above matches a comment that **contains** it — the key is what is being looked for, not the comment's first line. Where parity runs on its own leg nothing changes: it posts its own comment beginning with that line. One verdict per surface per PR state, whichever way the passes were dispatched. (Worked case: a Prism leg of 2026-10-21 loaded `skill-review-pr` and this skill in one dispatch brief and posted the parity verdict as a second `[design] HEAD:` comment beside the QA one. The ticket, the PR number and the head SHA are the filing leg's report and are **unverified** here, no repo being readable from the refine surface; that flag covers those three only. APP-2567.)

## Behaviour

Establish the reference first (*What parity compares against*), then read it alongside the implemented interface in the PR diff. Where it helps, read the domain's design system, `standard-design-system`, or `convention-brand` so the comparison is against the right tokens and identity, not a guess. Compare build against intent across the checklist below, then post a plain-language verdict.

**The checklist:**

- **Layout and spacing** — element positions, alignment, padding and margins, grid and gutters against the reference.
- **Design tokens, colour and type** — colours, typefaces, sizes, weights, and line-heights drawn from the design system's tokens rather than ad hoc values; flag hardcoded values that should be tokens, and any token mismatch.
- **Missing states** — hover, focus, active, disabled, empty, error, and loading states present in the reference but absent in the build.
- **Responsive behaviour** — how the interface reflows across breakpoints versus the reference's responsive intent.
- **Component substitutions** — a bespoke or off-system element used where the reference specifies a design-system component, or the wrong variant.

Then:

1. **Post the verdict comment on the Linear ticket** (the canonical record, and the sign-off surface). Begin with `[design] HEAD: [sha7]`.
2. **Post the same verdict comment on the GitHub PR** (the mirror Aled reads beside the diff). Begin with `[design] HEAD: [sha7]`.

Verdict comes in one of two modes:

- **On design** — a plain statement that the build matches the reference, **naming which reference was used**, so Aled can see the review was real and against what. Note anything the reference did not cover or that fell out of scope.
- **Divergences to fix** — the specific gaps, each with: what diverges, where (the screen or component, file and line where it helps), how it differs from the reference, and what would bring it on-design. Specific and actionable, so a bounce is self-contained.

Either mode carries the Chromatic paragraph where a Chromatic build exists (*Where parity sits*). Plain language throughout — Aled acts on it without reading the code.

**Hand off.** Once the verdict is posted, leave the label `agent:PR-1SM` and the state **In Review**. Do **not** switch the label to `agent:R3-LAY` and do **not** advance or merge. The **assignee** turns on whether a human decision is the next step:

- **No human gate** — an unflagged clean pass, with no flag and no Owner call in play — **leave the assignee clear**. On unflagged work Aled's approval is not the next step: a clean-pass agent ticket auto-merges, gated by the human flag rather than universally (Owner decision APP-402), and `skill-review-pr`'s *Hand off* branch is where that model is implemented. An assignee here costs the signal that "assigned to Aled" means his decision is needed now, and the loop's `PR-1SM` sweep skips a ticket that has an assignee, so a clean, merge-ready PR waits for a review that will not come. As in `skill-review-pr`, this governs parity's own writes and is not a field to reset: parity never sets Aled as assignee on an unflagged clean pass, and never clears an assignee it did not set.
- **A human gate in play** — a human-gate flag on the ticket, an operator-verify-only acceptance criterion, divergences the verdict asks Aled to rule on, or an Owner call already pending — **assign Aled**, matching `skill-review-pr`'s flagged branch and the driver's routing table.

**Where the two skills disagreed on this field, parity yields.** Parity's hand-off described the pre-APP-402 manual gate, in which every reviewed ticket went to Aled; `skill-review-pr` implements APP-402. One field cannot carry two meanings, so parity adopts `skill-review-pr`'s flag-based routing rather than keeping a second one — the Owner decision cited, not a ruling taken here. (Worked case: a Prism leg of 2026-10-21 ran both passes on one PR with no human-gate flag and both passes clean, read the two hand-offs as opposite instructions on one field, and adjudicated it live — it followed `skill-review-pr` and cleared the assignee, which is what this entry now says to do. Following parity literally would have stranded a clean, merge-ready PR: the APP-1315 / APP-645 shape. The ticket, the PR number and the head SHA are the filing leg's report and are **unverified** here, no repo being readable from the refine surface; that flag covers those three only. APP-2567.)

## What parity compares against — the reference moves over a project's life

The design system stays aligned across code and Figma, but **which side is the reference is set by the scope's declared build mode**, not by a fixed sequence. `convention-storybook` (*Three modes*) defines the three: **code-first** (the built system is the reference), **design-first** (the design — a Figma file, or a blueprint above both Figma and code — is the reference and code is held to it), and **build-then-refine** (the built system until the refinement pass, then Figma or the sketch, with refinements flowing back to code). The mode is declared on the ticket, its milestone or its phase; it is chosen per project and per feature, so one project may carry all three (Owner ruling, Aled 2026-09-03, APP-660 — superseding the July 80/20 phasing, which assumed one journey per project).

**Code-first — the default, and what an undeclared scope is read as.** The reference is the built system:

- the **published Storybook** — the source of truth for the UI under `convention-storybook`'s build-first inversion;
- the repo's **token layer** and the bar in `standard-design-system`;
- the venture's `convention-brand` instance and `convention-aesthetic` for identity and taste.

On these tickets **a Figma link is not required, and its absence is not a reason to stop**. This is stated explicitly because the alternative failure is silent: a parity pass that treats "no Figma link" as "nothing to compare against" no-ops on every early-phase ticket while reporting itself as run, and nobody notices the pass has quietly stopped happening.

**Design-first — the design or blueprint is the reference.** Where a scope declares design-first, parity compares the build against the declared design and holds the code to it: a Figma link or a blueprint is required on these tickets, and its absence is a stop the verdict names. The blueprint-first trial is the named instance: on the meirionpritchard-com Work section, the A1-231 trial puts a DS spec above both Figma and code, with both legs generated from it (`convention-storybook`, *A blueprint-first trial*). Parity there compares the build against the spec — not against Figma, which is a parallel leg rather than an upstream authority, and not against the shipped build, which is what the trial exists to move away from.

**Build-then-refine — Figma becomes the reference at the refinement pass.** Before the declared refinement pass the scope reads as code-first. From that pass, once the Figma track has **published** components bound to their stories by Storybook Connect links, tickets compare against the linked Figma frame. Two things to hold:

- The prerequisite is a *published* Figma library. A Storybook Connect link against an unpublished file resolves to nothing, and the publish is a manual one-click step no plugin API can perform (`convention-storybook`). A design comparison showing nothing is usually this, not a broken link.
- Chromatic's **Figma design-comparison** surface is where that comparison is rendered — the second of Chromatic's two roles in `convention-storybook`. It is a review surface, never a merge gate; do not read it as one, and do not confuse it with the visual-regression role, whose comparator is the build's own previously accepted snapshot.

**Parity reads the declared mode; it does not decide it.** The mode is written on the ticket, its milestone or its phase (`Mode: …`, per `convention-storybook`); where none is declared, read the scope as code-first, compare against the built system, and say so in the verdict. Naming the reference used in every verdict is what keeps a mode mismatch visible rather than silent.

## Where parity sits — one sign-off gate, and parity feeds it

Four surfaces answer four different questions, and **only one of them is the gate**:

| Surface | Question it answers | Role |
| -- | -- | -- |
| Storybook, published to Chromatic | is the component right on its own? | feeder |
| Chromatic *"UI Tests"* | what changed, and was it intended? | feeder / report |
| Vercel preview | does the real page work in context? | feeder |
| **The Linear ticket, mirrored on the PR** | **is it good to ship?** | **the one gate** |

Prism reads the feeders into a single plain-language verdict; Aled signs off once, on the ticket (`@relay` / `agent:R3-LAY`); Relay merges. The toolset was never the problem — only the wiring, where Chromatic behaved as a second gate (APP-660, 2026-07-23).

What follows for this skill:

- **Parity is a feeder, not a gate.** Its output informs Aled's one sign-off. It never advances, never merges, and never substitutes its verdict for his.
- **Sign-off never happens in Chromatic.** The Chromatic build link goes *into* the verdict for Aled to look at; he approves on the ticket. Parity does not ask him to go and click accept somewhere else.
- **Chromatic is report-only.** Its visual-regression role informs the gate rather than holding it, and its design-comparison role never gated anything. The two roles, their comparators and their prerequisites are set out in `convention-storybook`; the repo wiring that makes report-only true sits in `convention-github`. Read them there rather than re-deriving either here.
- **Fold the baseline review into the verdict.** Where the change produced a Chromatic build, the verdict carries a short paragraph naming **what moved** and **whether it was intended**, with the build link — so baseline review happens once, inside the one sign-off, instead of becoming a separate errand in a second UI.
- **Until the wiring lands, a pending baseline is a real second gate.** On a repo where the *"UI Tests"* check is still required and baselines are not auto-accepted on `main`, that status genuinely holds the merge. Parity does not re-route the ticket — it is review-only and holds its state — but it names the specific baselines and the build link in the verdict, so the leg that meets the pending status has the ask already written. `convention-github` holds that route: **In Review + `human`, assigned to Aled**, escalating by age, never Blocked.
- **A pending baseline is not a parity divergence.** It is an unaccepted snapshot, not evidence the build is off-design. Report it; do not score it in the checklist.

Whether the visual-regression role later graduates from report-only to a required gate is a `convention-github` / `convention-storybook` decision on story coverage, not one parity takes.

## Figma structural pass — reviewing a Figma build against the structural bar

The mirror of the pass above. Where the deliverable under review is a **Figma build** — a component, a family page, a screen, a library — rather than a UI build, parity reviews the file against the structural bar in `convention-figma`, so a build that looks right and is badly made underneath bounces to its builder instead of being hand-reworked by Aled. Review only, as everywhere in this skill: it reads the file and never edits it. Enforcement is review-time only for now — a write-time check that fires on every change is not adopted until this pass has calibrated what "structurally poor" means on our files (Owner ruling, Aled 2026-09-03, APP-614).

**Trigger.** A ticket in In Review carrying `PR-1SM` whose deliverable is a Figma file, page or node (a `P1-XEL` build handed to review), or an explicit request to review a Figma build's structure. **Dedup key:** the verdict comment begins `[design] FIGMA: <node-id> @ <file last-modified timestamp>`; skip silently where a comment with that key already exists.

**How it reads, and the set is exhaustive.** Through the Figma MCP, read-only: `get_metadata` for the node tree, `get_variable_defs` for what is bound, and `get_design_context` or `get_screenshot` for the rendered result. **Those four are the whole read surface for this pass** — not examples of it. Never a write.

**`use_figma` is not a read surface.** It executes Plugin API JavaScript against the live file, and the Plugin API carries calls that read like reads and write. The import-by-key family is the named one: `importComponentSetByKeyAsync` resolves a key by **bringing the set into the file**, and leaves parentless remote copies behind. A "read-only script" is therefore a property of the author's intention rather than of the surface, and this pass does not rest a read-only guarantee on an intention while four genuine read calls are available. Where a structural question cannot be answered from the four — a count across a page, a parentless main, a vector path — the pass **names the question as unanswered in the verdict** instead of reaching for a script. `convention-figma` holds the narrow, named cases where a read-only script is sanctioned outside this pass, and a named exception there is not a licence for an unlisted call here. (Worked case: a Figma structural pass briefed read-only called `importComponentSetByKeyAsync` to resolve a panel slot's preferred-value keys and left four parentless remote copies in the file — reported by the pass itself, nothing undone, no canvas affected, 2026-10-21. One instance. The file key, the node IDs and the call's described behaviour are the filing leg's report and are **unverified** here, no Figma file being readable from the refine surface; that flag covers those three only. APP-2564.)

**The checks** — each reported qualitatively on first draft; numeric thresholds wait until enough reviewed builds exist to calibrate them:

- **Auto-layout coverage** — every container whose children have a structural relationship uses auto-layout; absolute x/y inside such a container is a divergence.
- **Token binding** — fills, strokes, spacing, radius and type are bound to the file's variables or styles wherever the venture's system defines one; a hardcoded value where a token exists is a divergence, named per property.
- **Layer sanity** — node count and depth are proportionate to the rendered result; stacked layers achieving what one styled frame would do are a divergence.
- **Instance reuse** — a primitive drawn where a library component exists is a divergence; the check names the component that should have been instanced.
- **Naming conformance** — names match the convention the file already uses; the lexical scheme itself is the trial instance in `standard-design-system` and is not scored.
- **Containment** — every main component sits inside the doc frame that documents it, on the page for its family (`convention-figma`, *File organisation*); a main loose on the canvas is a divergence.

**The verdict** takes the same two modes as above — *on bar*, or *divergences to fix* — in plain language on the Linear ticket, each divergence naming the node, what it lacks, and what would bring it on bar. Then the same hand-off: assign Aled, leave `agent:PR-1SM` and In Review.

## Guardrails

- **Review only.** Never edits the build, the design, the design system, or a Figma file. It reports divergences for the exec leg to fix on a bounce.
- Does not merge, does not change the ticket's **state** (stays In Review), and does not change the `agent:*` label (stays `PR-1SM`). The one field it may set is the **assignee**, and only where a human decision is the next step — a human-gate flag, an operator-verify-only acceptance criterion, or an Owner call in play. On an unflagged clean pass it leaves the assignee **clear** (`skill-review-pr`, *Hand off*; Owner decision APP-402).
- **Never accepts or rejects a Chromatic baseline.** That is a human judgement on whether a visual change was intended, and it is Aled's — parity reports what moved so he can make it once, on the ticket.
- Approve, merge, and bounce are Aled's: his `@relay` approval signal triggers the merge leg; an In Review to Todo bounce re-triggers exec.
- **A missing Figma link is not a stop on code-first work.** Compare against the built system and name it. A pass that silently no-ops is worse than one that reports a gap.
- **Names the reference in every verdict.** An unnamed reference makes a wrong-phase comparison indistinguishable from a right one.
- Reads the scope's declared build mode; never declares it. An undeclared scope is read as code-first and the verdict says so.
- A parity pass makes design fidelity legible; it does not sign off the design itself. Sign-off is human (Pattern A).
- Scope to delivery repos only. Never touches the Pipeline team's work.

## Setup

- Claude Code Desktop, Schedule, New remote task — or run alongside skill-review-pr in the review lane.
- Connectors: Linear plus GitHub (read for the diff, write for the comments); access to the reference in play — the published Storybook and its Chromatic build, and the named Figma spec or prototype where the declared mode makes it the reference; plus the Figma MCP, read-only calls only, for the Figma structural pass.
- Routine prompt: "Run the design-parity skill."

Owned by **Prism** (`PR-1SM`) — the independent review and quality role.

On finish, run skill-ops-retro capture on this run's friction: **search the Pulse queue first and add the evidence to a same-root note if one exists, otherwise file a new FRICTION note** for the drain pass to assess, in capture step 3's literal shape — team Apps, project os.Claude, `FRICTION:` title, labels `task` + `work:configuration` + `PUL-5E`, Backlog, unassigned — filing the friction, never the run report.
