Reviewing Hi Fi

reviewing-hi-fi — SKILL.md

> Variant: standard · When to use: judging a finished (or amended) hi-fi design-as-code as an acceptance gate — re-rendering it, vision-reviewing the result against the bar, then emitting VERDICT: approve|revise with actionable findings.

Overview

This skill is the review half of a producing/judging hi-fi pair. Loaded by a reviewer who has a finished hi-fi (code + its screens) in hand, it judges one question: is this rendered hi-fi a sound build seed — covering every wireframe-named screen, visually realized to the bar, accessible on the render, and conformant to the design-system? It applies a fixed single-sourced checklist — the same bar authoring-hi-fi produces to — then emits a single machine-parseable verdict plus findings the producer can act on in one pass. It is an acceptance gate — it does not author, fix, or re-render-to-improve; it judges and returns findings.

The artifact is code that renders to pixels. The reviewer's distinctive move: it re-renders the code itself (headless browser, agent-browser/Playwright), captures a fresh screenshot per viewport × state, and vision-reviews that fresh render — it never trusts a handed-in screenshot (which can be stale/cherry-picked) or grades the code by reading alone. This requires a vision-capable runtime; a text-only reviewer is degraded (it can read the code but cannot see the render) — say so, and flag if the artifact itself was produced blind.

Two boundaries: hi-fi owns the rendered visuals + the numeric pixel-WCAG judgment (the wireframe only reserved them); the design-system owns the per-component a11y contract spec — this gate judges whether the rendered composed result achieves it (spec-vs-realized; no double-judge). It judges conformance to the DS + wireframe, never grades them; and it judges a seed, not production code (don't revise for missing tests/real backend).

When to activate

• A finished hi-fi design-as-code needs an accept/revise decision before the human visual gate / the build milestone.
• You are the independent reviewer / gate for a hi-fi a producer just rendered.
• Re-judging a revised hi-fi after a prior revise, or reviewing an amended hi-fi as a scoped delta (see cond. 13).

Do NOT activate when:

• Authoring or repairing a hi-fi → use authoring-hi-fi. This skill never writes or re-renders to improve.
• Judging the screen structure (layout regions, component selection, states-as-structure) → that is the upstream wireframes (reviewing-wireframes).
• Judging the token system / component catalog / per-component a11y contract → that is the design-system (reviewing-design-system); this gate checks the rendered result conforms.
• Re-deciding which screens/transitions exist → that is user-flows.
• Judging final production code (tests, real backend, perf) → this is a seed; the build phase owns that.

Workflow

Step 1: Re-render the code + read the whole hi-fi with fresh, independent eyes

Render the hi-fi code yourself at the target viewports and capture a fresh screenshot per state — do not trust a handed-in screenshot. If you cannot render (no headless browser) or cannot see the render (text-only runtime), say so: the review is degraded and you judge only what the code statically shows (flag it). Read the code + the screens end to end. If the upstream wireframes and/or design-system were provided, skim them so Step 2 can cross-check coverage + conformance.

Step 2: Run the checklist — judge each condition on the RENDER

For each condition decide pass or gap, against the fresh render (not the code text alone). A condition fails only on a real, named deficiency — "I'd have used a different hue/layout" is not a gap (out-of-set subjective taste is excluded). Capture the exact location (which screen / which state / which viewport). Each condition is proportional to the screen's archetype — a thin/static screen legitimately collapses the interactive/stateful/responsive sub-checks; don't manufacture a gap from brevity.

The capability-boundary checklist item (below) applies ONLY when a capability_record was injected into the authoring invocation and is available as review context. When absent, treat it as n/a — do not penalise a document for lacking capability-boundary markers when no boundary was defined.

1. Full coverage vs the wireframes. Every wireframe-named screen + flow-visited state is rendered. Gap when one is un-rendered (cross-check the wireframes; if absent, check the doc's own inventory + note the missing input). Non-collapsing baseline. (On an amend, the pre-existing inventory satisfies whole-artifact coverage — don't re-litigate untouched screens; cond-13 owns delta-introduced coverage regressions.)
2. Fidelity + scope. Hi-fidelity visuals reached (not wireframe-grey / default-browser styling); no invented structure/nav/screen beyond the wireframe; and it is judged as a seed — NOT revised for lacking tests/real-backend/routing, NOT approved if it claims production-readiness it isn't. Non-collapsing baseline.
3. Visual execution + hierarchy. The DS visual language is realized on the render (color/type/spacing/elevation/radius/icons/imagery); the primary element is visually dominant; hierarchy legible. Gap on a flat, undifferentiated, or unstyled screen. Collapse: a one-element screen needs little hierarchy.
4. Polish — objective + named heuristics. Objective: grid-aligned, consistent scale, no clipped/overlapping/orphaned element, on-token, sibling-consistent. Named heuristics (each articulable): balance, whitespace & restraint, spacing rhythm, focal clarity, aesthetic cohesion. Gap only on an objective failure OR a named heuristic failure (state WHICH heuristic + why). Subjective out-of-set taste ("a nicer hue/layout exists") is NOT a gap. Collapse: a trivial screen trivially holds.
5. Token-backed / no DS drift. Every visual value traces to a DS token (Tailwind token-utility / CSS var / shadcn token); no raw #hex/px/bg-blue-500 bypassing a token; no local override of a DS token/component; a missing token/component is surfaced, not inlined. Gap on any off-token raw value or drift. Non-collapsing baseline.
6. Rendered + vision-reviewed (by you). You re-rendered the code, captured a fresh screenshot, and it renders without breakage + matches the wireframe structure + the DS. Gap when the screen fails to render, renders broken, or diverges from the wireframe. A review done off a handed-in image or code-read-only is incomplete. Non-collapsing baseline (the mechanism IS the gate).
7. Content realism. Real, representative content — no lorem/placeholder filler; realistic + edge data (long strings, overflow) exercised. Gap on lorem or only-tidy-data. Non-collapsing baseline.
8. Rendered states + quality. Each flow-visited state is rendered (a screenshot, not a note): empty (reason + guide-to-action), loading (a skeleton mirroring the layout, not a bare spinner), populated, error (plain-language cause + recovery), success, partial. Gap when an applicable state is un-rendered or empty-shell. Collapse: a static screen has only populated.
9. Responsive reflow. Rendered + correct at the target viewports; mobile content-priority + adaptive nav where form-factor matters; touch targets sized. Gap when a responsive surface is shown at one width only or reflows broken. Collapse: a single-form-factor surface (stated reason).
10. Numeric WCAG 2.2 AA on the render. axe-core clean with no rule disabled (necessary, not sufficient — axe can't see focus appearance, keyboard/focus order, contrast over imagery, or reduced-motion; judge those on the render + a manual/AT spot-check) + (judged on the render): text contrast ≥4.5:1 / large+UI ≥3:1 (SC 1.4.3/1.4.11); focus visible (2.4.7) + not-obscured (2.4.11) + appearance ≥2px/3:1 (2.4.13, house rule); target ≥24px (2.5.8); keyboard operable + logical focus order; reduced-motion honored. Gap on a measured failure or a suppressed rule. Fix belongs in the token layer. Baseline: contrast + landmarks + names always; focus/target/motion where interactive/animated. Spec-vs-realized: judge whether the RENDER achieves the threshold, not whether the DS doc states it (that's the design-system gate).
11. DS conformance. The rendered result conforms to the design-system (components are the DS's or faithful to its contract; no contradiction). A finding about the DS's own quality is out-of-lane — surface it, route it to the DS gate. Non-collapsing baseline.
12. Gaps surfaced, not invented. Undefined screen/content, a missing DS token/component, a degraded (no-render) production = explicit assumptions/open-questions. Gap when the doc papers over a gap with an invented token/component or a faked screenshot. An honestly-labelled assumption is not a gap.
13. Delta-scoped review (amended hi-fi only). Review the diff + the re-rendered changed screens, not the whole artifact: scope-confined (untouched screens' code byte-stable + their screenshots not re-captured); ripple-clean (a changed token reached all consuming screens + none hand-edited off-token; no consumer left stale; no wireframe-named screen newly un-rendered; no component-name drift; every changed screen's screenshot re-captured — no stale render); the changed screens re-vision-reviewed (still meet polish + WCAG + DS-conformance on the new render); the doc's own version bump correct for the change class; a breaking removal carries deprecation; changelog matches the diff. Gap on any of these. N/A for a greenfield first build.

1. Capability boundary (n/a when no capability_record): design-system tokens used throughout; no new components outside the design-system; boundary matches the wireframes scope (interior only for per-capability; shell only for system-scope).

Step 3: Decide the verdict

• approve — every applicable condition passes on the render. The hi-fi is a sound build seed: covered, visually realized to the bar, accessible, DS-conformant. Approve even if you can imagine visual improvements; the bar is the conditions, not perfection. A thin screen with proportionally collapsed conditions still approves.
• revise — one or more conditions have a real, named gap (an un-rendered screen, wireframe-grey fidelity, an off-token raw value, a contrast failure on the render, lorem content, a missing rendered state, a named-heuristic failure, a bad delta).

Do not revise to signal effort or request nice-to-haves; do not revise on out-of-set subjective taste (cond. 4) or on the design-system's own quality (cond. 11) or for seed-only-gaps like missing tests (cond. 2). A condition is either met or it isn't.

Step 4: Emit the verdict + actionable findings

Emit the verdict as a single line — the literal text VERDICT: approve or VERDICT: revise, on its own line, with no surrounding fences, quotes, or extra words (the fences here are illustration only):

VERDICT: approve

Then list findings. On revise, every finding is actionable — the failed condition, the exact location (which screen / state / viewport), and how to fix it (with the fix at the token layer where it's a contrast/token issue) — so the producer resolves it in one pass. On approve, findings are optional non-blocking notes.

A good finding names the gap and the fix:

> revise — Numeric WCAG (cond. 10): on the rendered Projects-empty screen, the "New project" button is --muted on white at 2.9:1 (below 4.5:1, SC 1.4.3). Fix: bind the button to the --primary token (don't recolor one button off-token); re-render to confirm ≥4.5:1.

A bad finding is vague: "The contrast could be better somewhere."

Rules

Hard rules (never violate):

• Emit exactly one verdict line, VERDICT: approve or VERDICT: revise — that literal token, on its own line. Downstream tooling parses it.
• Re-render; never trust a handed-in screenshot. Render the code yourself + vision-review the fresh result (cond. 6). A code-read-only or trust-the-image review is incomplete; a degraded (no-render/text-only) run must be flagged.
• Judge, never author. Return findings; do not rewrite or re-render-to-improve. The producer revises.
• Single-sourced bar. Judge against the Step-2 conditions — the same bar the author produces to. No private stricter standard, no invented extra condition.
• No false-revise. A seed meeting every applicable condition is approved, even a thin one. Out-of-set subjective taste is never a gap; seed-only gaps (no tests/backend) are never a gap.
• No false-approve. An un-rendered screen, off-token raw value, contrast failure on the render, lorem content, or invented token/component is a revise.
• Numeric a11y on the render; never accept a disabled rule. Judge contrast/focus/target on the rendered pixels; a suppressed axe rule used to pass is itself a finding.
• Spec-vs-realized, stay in lane. Judge whether the RENDER achieves the WCAG threshold + conforms to the DS — do NOT grade the DS's own contract/quality (that's reviewing-design-system) or the screen structure (that's reviewing-wireframes).
• Seed, not production. Don't revise for missing tests/real-backend/routing — those are the build phase's.
• Judge against the upstreams given. A not-produced upstream is never a revise trigger; a produced-but-ignored upstream (a wireframe screen left un-rendered; a DS token bypassed) is a fair finding.
• Amend = delta review. On an amendment, review the diff + ripple + re-vision-review the delta (cond. 13); don't re-litigate untouched screens.
• Every revise finding is actionable — failed condition + location + concrete fix.

Preferences (override-able):

• Order findings by severity — blocking gaps first (un-rendered screen, contrast failure, off-token drift, lorem), then minor (a single heuristic nit).
• Reference the condition number/name in each finding.
• Keep approve-notes few and clearly non-blocking.
• When a cross-check input (wireframes or design-system) is absent, or a render was degraded, say so once rather than silently assuming.

Gotchas

• Trusting the handed-in screenshot. A supplied image can be stale or cherry-picked — re-render the code yourself (cond. 6); that IS the gate.
• Reviewing the code by reading it. Code that reads fine can render broken — you must render + look (cond. 6).
• Grading the design-system. Revising because a DS token value or component contract seems off is out-of-lane — judge whether the render conforms (cond. 11); route DS-quality findings to the DS gate.
• Double-judging WCAG. The DS states the per-component thresholds; this gate judges whether the RENDER achieves them (spec-vs-realized) — not a re-grade of the DS's stated numbers.
• Revising a seed for prod gaps. No tests / mock data / single-file / CDN are seed allowances, not gaps (cond. 2).
• Revising on taste. "A nicer hue/layout exists" is out-of-set subjective taste — cond. 4 judges the objective subset + the named heuristics (state which one fails). Manufacturing a taste gap is a false-revise.
• Letting lorem pass. Placeholder filler hides overflow/tone/a11y problems — it's a revise (cond. 7).
• Letting an off-token value pass. A raw #hex/px that bypasses the token map is drift (cond. 5) — fix at the token layer.
• Re-reviewing the whole artifact on an amend. Review the diff + ripple + re-vision-review the delta (cond. 13); re-litigating untouched screens is noise.
• Verdict token drift. "Approved", "LGTM", "needs work", or a verdict buried mid-paragraph won't parse. Emit the literal VERDICT: approve|revise on its own line.

Anti-patterns

• Rubber-stamp approve. Skimming the code/screen

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: bm629
• Source: bm629/agent-skills
• License: MIT

Install and usage instructions live in the source repository linked above.