Introducing a new way to review your PRs.

Read the announcement

pbakaus / impeccable

The design vocabulary for your coding agent. Steer with polish and bolder, review with critique and audit, catch AI slop before it ships.

View on GitHub

32 documents · Updated Nov 20, 2026

docs / component-fidelity-workflow

Component fidelity review workflow

The component fidelity workflow turns an approved visual composition into a measured build target. It guides an agent from component choice through region specification, asset preparation, component review, first-viewport reproduction, visual comparison, and human review. It complements the broader native capture and component review workflow and connects with component review planning, agent-assisted design workflows, live editing sessions, design context and critique artifacts, skill commands and reference guidance, and AI provider integration.

Fidelity model

The workflow treats fidelity as agreement between an approved comp and a rendered build. A comp is the approved visual reference. A region is a named part of that reference, such as a text block, control, chrome strip, image, illustration, or texture. The agent must account for each visible region instead of relying on a general impression of the page.

The comparison system separates layout, color, material, and horizontal band alignment. This separation helps the agent choose the right kind of correction: a missing plate needs an asset, while a drifted text block needs a layout or type change.

The workflow keeps its progress in .impeccable/…/state.json. The state records the active phase, gate attempts, notes, forced decisions, review results, and the approved comp. build-phase.mjs

Build phases

The build is an ordered path. Each phase establishes evidence needed by the next phase, so the agent does not build a polished lower section on top of an unverified hero.

flowchart LR
    A[Comps] --> B[Spec]
    B --> C[Plates]
    C --> D[Component review]
    D --> E[Hero]
    E --> F[Sections]
    F --> G[Motion]
    G --> H[Responsive]
    H --> I[Review]

The phases have these roles:

PhasePurposeMain evidence
CompsPresent several visual directions and record one approved choice.At least three comp images with prompt sidecars and one approval.
SpecName and measure every important region.spec.json with region boxes, kinds, palettes, and type readings.
PlatesProduce the raster material that code must not redraw.A usable plate for each raster region.
Component reviewLet a person check the plates and the code-drawn plan before page code exists.A reviewed component packet with decisions and inventory confirmation.
HeroReproduce the first viewport at the comp frame.A hero capture that clears the fidelity gate.
SectionsExtend the surface within the approved visual system.A recorded phase transition; this phase has no mechanical gate.
MotionAdd interaction and motion without changing the visual contract.A recorded phase transition; the finish review checks the result.
ResponsiveHold the design at common desktop and mobile sizes.Desktop and mobile captures plus a desktop comparison.
ReviewRecord the final disposition.ship, fix, rebuild, or recapture.

The agent can inspect the current phase with build-phase.mjs status. A failed gate leaves the phase open and reports reasons. A forced transition is recorded and requires a reason that reports a user decision or a tool error. build-phase.mjs, build-phase.mjs

Composition approval

The comp round gives the user a choice before page code exists. Each candidate has a prompt sidecar so the selected direction remains traceable. Exactly one candidate must carry the approval marker before the workflow can create a normal build state.

When a direction already has a decision comp, --decision-comp names that image as option one. It must be used with --direction, not with --comp, and the named file must exist. The workflow keeps that image in place, creates two more compositional options, presents all three to the user, and records approval in the chosen sidecar. A normal comp round creates the candidate set without this option-one input. comp.mjs, build-phase-decision-comp-option-one.json

Starting with an already approved comp skips this phase. A code-led project can also skip the comp-led state machine when its local configuration says that the build path is code-led. build-phase.mjs, build-phase.mjs

References: skill/…/build-phase.mjs• L162-187 skill/…/build-phase.mjs• L893-925 tests/…/comp.mjs• L91-121 tests/…/build-phase-decision-comp-option-one.json• L4-28

Region specification

The spec changes a visual reference into a contract that later stages can measure. The agent first views a labeled 10-by-10 grid, then names salient regions with a kind and a short note. The resulting spec stores normalized and pixel boxes, sampled palette, detail energy, medium, and any plate path.

Regions fall into two broad groups:

  • Raster regions contain painted material. Plates, images, and textures are produced as assets.
  • Semantic regions contain page structure. Text, controls, and chrome are drawn by the page.

The spec also checks that painted material is not mislabeled as code-drawn content, that code regions are not so large that they hide several elements, and that visible ink is not left outside the named regions. It records warnings when a plate box clips artwork. comp-spec.mjs, comp-spec.mjs

References: skill/…/comp-spec.mjs• L6-35 skill/…/comp-spec.mjs• L240-348

Asset plates

A plate is a production raster asset for an illustration, image, or texture in the comp. The workflow uses the region crop as a visual reference but does not ship that crop as the asset. UI text and chrome are removed from the plate reference because the page draws them separately.

The plate gate checks presence, decodability, useful size, and agreement with the reference region. Textures are treated as repeating material and checked for palette and grain. Other plates must preserve the region structure and must not add detail where the comp is calm. A plate must also be referenced by page source before the hero can pass. A separate check-plate candidate check can validate a proposed image with the normal plate gate, but it does not replace the selected asset, record approval, or advance the phase. comp-spec.mjs, build-phase.mjs, build-phase.mjs, build-phase-usage.json

References: comp-spec.mjs• L363-403 build-phase.mjs• L235-315 build-phase.mjs• L340-378 tests/…/comp.mjs• L83-90 tests/…/build-phase-usage.json• L2-3

Component review

Component review is the human checkpoint between measured asset planning and assembled-page review. It checks that each raster region has a shippable plate and that every remaining region has a clear code-drawn plan before the page is built.

Review packet

The review packet is derived from the measured spec, the approved comp, and the plate files. The plan records asset items for raster regions, plan items for other visible regions, and the code regions that the page must draw. The packet is written to .impeccable/…/components.json; it is an output of the spec and should not be edited by hand. The oracle plan covers one plate asset, one non-container chrome plan item, and one text code region. component-review.md, comp.mjs, comp-spec-regions.json

The plan refuses to open while a raster region has no plate. It also normalizes paths inside the project to project-relative forward-slash paths, so a packet keeps the same meaning when the input spec uses an absolute or backslashed path. A changed region classification, box, or plate requires a new spec and a new packet. component-review.md, component-review.md, comp.mjs

References: skill/…/component-review.md• L7 skill/…/component-review.md• L19-26 tests/…/comp.mjs• L95-121

Review capture

After the plan is complete, component capture renders the listed component sources and prepares the review evidence. The review session shows the approved comp beside the captured component or asset, with context available for orientation. The user can approve an item, request a change, split an asset into layers, reclassify a code region, or mark a missing region.

The native review interface is built from ui/…/entry.ts and checked against the served browser bundle. This keeps the review session used by capture and the shared UI source in sync before the review is opened. component-review-bundle.test.js, entry.ts

The review remains pending until the user submits decisions for every item and confirms the inventory. A revision or a changed plate returns the workflow to spec, plate production, and packet creation. Approval moves the build to the assembled hero; it does not replace the hero gate or the later whole-page review. component-review.md, component-review.md

References: skill/…/component-review.md• L8-13 skill/…/component-review.md• L15-34 tests/component-review-bundle.test.js• L1-8 ui/…/entry.ts• L1-57

The component-review path is:

flowchart LR
    A[Approved comp and measured spec] --> B[Component plan]
    B --> C[Native component capture]
    C --> D[Review packet and session]
    D --> E{User decision}
    E -->|Approve| F[Assemble hero]
    E -->|Revise or missing| G[Update regions or plates]
    G --> B

References: skill/…/component-review.md• L5-13 skill/…/component-review.md• L15-34 tests/…/comp.mjs• L90-121

Visual comparison

The comparison flow renders the page, aligns the build capture to the comp frame, and creates evidence for both machine gates and human review. It produces a side-by-side image, a heatmap, region pairs, and a JSON report.

flowchart TD
    C[Approved comp] --> S[Comp spec]
    B[Build capture] --> A[Frame alignment]
    C --> A
    A --> M[Whole-frame metrics]
    A --> R[Named region metrics]
    M --> E[Heatmap and report]
    R --> E
    E --> H[Hero gate and human review]

The build capture may be a full-page image for general comparison. For the hero, the first viewport must use the comp's own dimensions and aspect. A small global shift is used to make region crops comparable, while the side-by-side and heatmap continue to show the capture as it was taken. comp-diff.mjs, comp-diff.mjs, comp-diff.mjs

Image metrics

The image metrics answer different questions about fidelity. Structure checks whether the composition is the same. Color checks palette and color coverage. Detail checks whether material survived. Bands check whether major horizontal sections align.

The overall score combines these measures. Region kind changes the weighting because a plate depends more on material detail, while text depends more on shape and structure. Each region receives one of four review terms:

VerdictMeaning
MatchThe region agrees closely with the comp.
DriftThe region is present but its size, position, or treatment differs.
MissingThe comp has material or content that the build does not show.
ContradictedThe build shows a materially different structure or direction.

The report also exposes palette intersection, added detail, per-region scores, and the worst region crops. These values rank the work; the paired crops remain the evidence a reviewer should inspect before deciding what to change. comp-diff.mjs, comp-diff.mjs, image-metrics.mjs, image-metrics.mjs

References: skill/…/comp-diff.mjs• L81-112 skill/…/comp-diff.mjs• L134-175 skill/…/image-metrics.mjs• L92-113 skill/…/image-metrics.mjs• L185-252

Diff artifacts

The diff output makes a broad mismatch easy to locate and a local mismatch easy to name. side-by-side.png shows the comp and build together. heatmap.png marks pixel differences in red. regions/<id>.png shows each named pair at a readable size. report.json carries the scores, verdicts, palettes, sizes, and artifact paths.

The normal review order is the worst region crops first, then the whole side-by-side image. A missing region points to missing material or placement. A contradicted region points to the spec and its crop. A drifted region is the usual place for spacing and size corrections. comp-diff.mjs, comp-diff.mjs, build-phase.mjs

References: skill/…/comp-diff.mjs• L230-271 skill/…/comp-diff.mjs• L307-353 skill/…/build-phase.mjs• L971-988

Typography matching

The font workflow measures the lettering in the comp before the agent chooses a face. It uses a font fingerprint, which is a size-normalized description of letter shape, width, weight, spacing, and line form. This prevents a familiar font name from replacing the actual visual metrics.

For each text region, measurement records cap height, line count, glyph count, width class, weight class, and other shape signals. Ranking compares those signals with a font catalog or with rendered candidate faces. When a browser is available, candidates are rendered at the comp's cap height. When it is not, the catalog provides a recorded choice with an estimated size that still needs a visual check.

The selected face is stamped into the spec. The spec gate rejects a hand-entered choice that does not come from the font-match flow. The lead text region is the measured display region with the largest cap height. Other text regions still need their own measurements because each region can require a different size and weight. font-match.mjs, font-match.mjs, font-match.mjs, font-fingerprint.mjs

Hero review

The hero gate is the first strict review of the rendered page. It checks that every plate is used, that the first viewport has the comp frame, and that the visual score clears the hero bar. It also applies hard checks for missing or contradicted direction, clipped artwork, invented ink, organic CSS drawings in raster regions, and oversized inline SVG illustrations.

The intended hero build order is:

  1. Generate the scaffold from the spec and bind its measured boxes to semantic page markup.
  2. Place every plate in its named box. Use the artwork's full shape rather than silently cropping it to a narrower box.
  3. Capture the plate-only hero and use build-phase.mjs record hero as a look at plate placement. This does not advance the phase.
  4. Add text, controls, rules, and other semantic regions from the spec.
  5. Capture the complete hero and run the hero gate through build-phase.mjs advance.

The scaffold is a reference for measured positions and type values. It is not the page. The page keeps its own semantic structure while using the scaffold's measurements as the layout contract. build-phase.mjs, build-phase.mjs

Hero checks

Hero checks turn common visual review comments into edit-ready readings. Text checks compare cap height, line count, line pitch, tracking, apparent weight, color, and ink position. Chrome checks compare thin strip heights through their rules or ink extent. Invented-ink checks find build content in calm comp cells, such as an extra kicker, divider, or navigation row.

Asset checks look for plate clipping and for drawings that should have been plates rather than code. Small icons, arrows, chevrons, and sprite references are allowed as code. Larger inline SVG drawings are treated as illustrations and must use a plate. hero-checks.mjs, hero-checks.mjs, hero-checks.mjs

References: skill/…/hero-checks.mjs• L21-108 skill/…/hero-checks.mjs• L111-187 skill/…/hero-checks.mjs• L190-245

The gate gives readings above the main score bar as advisories so the agent can polish without blocking useful progress. Missing direction, clipped plates, invented content, and other hard contradictions still block the phase. If the same worst region remains unchanged for three attempts, the workflow asks for a rebuild of that region instead of another value-only edit. build-phase.mjs, build-phase.mjs

Responsive review

Responsive review checks that fidelity is not limited to the exact comp width. The workflow captures a full desktop page at a common width and a full mobile page at a narrow width. It compares the desktop capture with the comp while allowing the already-approved material to survive normal resampling.

The desktop layout must hold across a useful width range instead of relying on fixed geometry that wraps as soon as the viewport becomes narrower. Text can still fail this stage when it wraps into a different composition. build-phase.mjs

References: skill/…/build-phase.mjs• L742-782

Human review

The numeric gate is a triage tool, not a substitute for judgment. The reviewer opens the side-by-side image and the worst region pairs, then decides whether the remaining differences are acceptable, require a fix, require a rebuild, or require a new capture.

The review record is part of the build state. A ship disposition is refused while any required phase remains open. This prevents a page from being reported as complete while its hero or responsive gate is still unresolved. build-phase.mjs

Change checklist

When these files or sections are changed, remember to consider these:

  • Keep region kinds consistent between comp-spec.mjs, comp-diff.mjs, the component-review plan, and hero checks. A painted region classified as semantic content can bypass the plate and SVG safeguards.
  • Keep the component-review packet derived from the current spec and plate paths. A new raster region must have its plate before the human checkpoint can open.
  • Keep project-relative path normalization stable for review packets. Absolute or backslashed input paths must still identify the same in-project asset.
  • Keep the plate reference crop and plate score aligned. Changes to masking or texture treatment can make a valid plate appear to be missing.
  • Keep font choice stamps compatible with the spec gate. A new choice format must still distinguish a measured ranking from a hand-written guess.
  • Keep candidate plate checks separate from selected-asset approval. A validated candidate must not silently replace the chosen plate or advance the phase.
  • Keep the option-one decision-comp contract aligned with direction selection. A named decision comp must remain an existing first option and must not be accepted with --comp.
  • Keep hero thresholds and advisory rules aligned with the phase state. A score that becomes advisory must not silently remove hard checks for missing content or clipped artwork.
  • Keep capture size rules aligned between hero and responsive review. A full-page capture is valid for responsive review but the hero still needs the comp-sized first viewport.
  • Keep report verdict names stable. The build state and review instructions use match, drift, missing, and contradicted to select the next action.
  • Keep the component-review source and served browser bundle in parity. Changes to ui/…/entry.ts must produce the expected crates/…/component-review.js output.

Important failure modes

TriggerConsequenceGuard
A visible comp element is not named in the region spec.Later gates cannot report its absence.The spec checks for uncovered ink cells before it closes.
A raster region has no plate when component review is planned.The plan and asset review cannot open.The component-review plan lists the missing plate and stops.
A plate is generated from a crop and shipped as the artwork.The page carries comp pixels instead of a production asset.The plate gate checks size and rejects a non-texture plate that matches the raw crop too closely.
A candidate plate passes check-plate but is treated as approved.The selected asset remains unchanged or the review state becomes misleading.Candidate checking validates only a separate file; approval and phase advance remain separate actions.
A plate exists on disk but no page source references it.The intended material never appears in the build.The hero gate scans the artifact and its linked stylesheets for each plate.
A plate box cuts through the comp artwork.Placement with cover-style sizing clips the shape.The spec warns about artwork touching the box edge, and the hero gate checks the placed ink box.
The agent types a font choice into spec.json.The build can use an unmeasured face while appearing configured.The spec gate requires a font-match stamp on the lead choice.
The build adds a divider, kicker, legend, or extra row.The page has invented content even if its average score is high.Hero invented-ink checks compare calm comp cells with build ink.
The agent redraws an illustration or diagram as large inline SVG.A code approximation replaces the approved asset.The hero scan allows small icons but blocks larger SVG drawings.
The same region stays worst across three low-progress attempts.Value edits consume turns without changing the failing material.The hero loop asks for a region rebuild from the crop or spec.
A decision comp is passed with --comp, is missing, or is used without its direction.The comp round cannot preserve a valid option-one choice.The command rejects the combination or missing path before changing state.
The native component-review source changes without rebuilding the served bundle.The review can show stale behavior or fail the expected source-to-bundle contract.component-review-bundle.test.js builds the entry and compares it with crates/…/component-review.js.
The agent records ship with an open phase.The state claims completion against an unfinished gate.finish --disposition ship requires all non-review phases to be closed or skipped.

Key files

FileWhy to read it
skill/…/build-phase.mjsDefines the phase state machine, gates, scaffold, hero readings, responsive review, and finish rules.
skill/…/comp-spec.mjsDefines how an approved comp becomes named regions, measurements, plate references, and prompts.
skill/…/component-review.mdDefines the plan, capture, human decision, and repair loop before hero assembly.
ui/…/entry.tsShows the native review entry point, packet loading, decision submission, and failure state.
tests/component-review-bundle.test.jsProtects parity between the native review source build and the served browser bundle.
skill/…/comp-diff.mjsDefines screenshot alignment, region verdicts, visual artifacts, and the comparison report.
skill/…/image-metrics.mjsDefines the structure, color, detail, and band measures used by comparison.
skill/…/font-match.mjsDefines type measurement, candidate ranking, proof sheets, and recorded font choices.
skill/…/font-fingerprint.mjsExplains the normalized lettering measurements behind font matching.
skill/…/hero-checks.mjsDefines the edit-ready text, chrome, invented-ink, clipping, and SVG checks.
tests/…/comp.mjsShows deterministic coverage for comp approval, candidate plate checks, spec creation, comparison, font measurement, build phases, and component-review planning.
tests/…/build-phase-decision-comp-option-one.jsonShows the option-one decision-comp rules, approval round, and resulting phase state.
tests/…/build-phase-usage.jsonShows the public build-phase command contract, including separate candidate plate validation.
tests/…/comp-spec-regions.jsonShows the measured region contract and the output that feeds plate and component planning.
docs/comp-fidelity-review-2026-08-17.jsonRecords human fidelity review patterns that motivate checks for wrong fonts, missing content, bad placement, clipping, and invented assets.