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-composition-operations

Component composition operations

Component composition operations turn an approved visual direction into a measured design contract, usable assets, and a checked page build. The runtime links the comp-spec, comp-diff, font-match, and build-phase verbs so component regions stay tied to the approved composition from the first map through final review. This page extends the Rust CLI runtime overview and relates to the native runtime and CLI, design seed generation, and design context and critique.

Runtime purpose

The component and composition runtime treats a visual composition, or comp, as a fixed reference for component-oriented design work. It measures visible regions, separates code-drawn parts from raster assets, guides the build in stages, and reports where the result matches or differs from that reference.

The CLI exposes the runtime as four related verbs:

VerbDesign work it coordinatesMain result
comp-specNames and measures the visible regions in the compA build specification with boxes, kinds, palettes, and asset guidance
font-matchMeasures lettering and ranks faces by rendered shapeType measurements and a recorded face choice
comp-diffCompares a build image with the compScores, region verdicts, and visual comparison artifacts
build-phaseControls the ordered build and its gatesPersistent phase state and a decision record

The runtime keeps image comparison pure where possible. Browser capture and font specimen rendering enter through CLI-provided boundaries, so the same design contract can be checked with or without a browser.

Composition model

Approved composition

The approved composition is the visual reference that all comp-led gates must use. The runtime keeps a copy and a pixel identity for it, then refuses to measure when the editable reference no longer matches. This prevents a changed reference from making existing assets or page code appear correct.

The reference can contain several kinds of regions:

  • Raster regions are painted material such as an illustration, photograph, object, or texture. The page supplies these as assets.
  • Semantic regions are text, controls, or chrome that the page draws with code.
  • Bands are broad layout guides. They help inspect a comp but do not replace a map of its visible elements.

The approved pixels remain separate from generated plates and from the page under review. A changed reference must be restored or explicitly re-measured as a new approved comp before work continues.

References: crates/…/approved_comp.rs• L1-22 crates/…/comp_spec.rs• L28-33 crates/…/build_phase.rs• L326-371

Region specification

The region specification is the shared contract between mapping, asset work, layout work, and comparison. It gives each visible element an identity, a kind, a measured box, and a short note that explains what the comp shows there.

comp-spec can first produce a labeled grid or a rough band draft. The useful specification comes from refining that view into separate elements. It records pixel and normalized geometry, palette and detail readings, raster plate paths, and text content where needed. The map also records its source, so later edits to the region description cannot silently leave old measurements in force.

The map controls later work in three ways:

  • Raster regions become plate prompts, crops, and asset gates.
  • Text regions become type measurement and font-choice work.
  • Code regions become layout targets for the scaffold and region-level comparison.

References: crates/…/comp_spec.rs• L586-811 crates/…/comp_spec.rs• L1111-1119 crates/…/comp_spec.rs• L1246-1344

Component identity

Component identity means that a named region remains the same design subject across the comp, its asset, the page, and the comparison report. Repeated code components can share a review group, but nested elements and unlike region kinds must keep distinct identities so the review can assign a result to the right element.

This identity is more than a label. It links a region to its geometry, source pixels, asset receipt, capture evidence, and failure message. A region that moves at a responsive width can therefore be reported as displaced rather than incorrectly reported as missing.

References: crates/…/review_groups.rs• L1-54 crates/…/displacement.rs• L1-10 crates/…/comp_diff.rs• L203-243

Composition verbs

Specification operations

comp-spec creates the measured design contract from the approved comp. Its operations move from visual inspection to usable region data and then to reference material for asset work.

The main operations are:

  • --grid creates a coordinate view with palette and broad horizontal bands.
  • --regions measures an authored region map and writes the build spec.
  • --auto creates a draft only; it does not stand in for an element map.
  • --inspect-map lets the author inspect crops and masks before accepting the map.
  • --crop creates a reference crop for a region. The crop is not a shipping asset.
  • --plate-prompt turns a raster region into guidance for producing its plate.
  • --print gives a compact view of the measured contract.

The operation is deliberately conservative. It requires meaningful region notes, rejects painted material described as code, checks that visible ink has a named region, and warns when an asset box clips artwork without an explicit bleed decision.

References: crates/…/comp_spec.rs• L1113-1140 crates/…/comp_spec.rs• L1169-1230 crates/…/comp_spec.rs• L1246-1344

Type operations

font-match turns lettering in the comp into type constraints for the page. It measures cap height, width class, weight class, and other shape signals from a text-region crop. It then ranks candidate faces by the distance between the comp lettering and rendered specimens when a browser is available.

The operation records the selected face in the specification. Without a browser, the font catalog supplies the ranking and marks the size as estimated. The result is still a measured choice rather than a face entered by guesswork, so the build scaffold and the spec gate can use the same type decision.

References: crates/…/font_match.rs• L1-7 crates/…/font_match.rs• L42-75 crates/…/font_match.rs• L464-581

Difference operations

comp-diff compares a build capture with the approved comp at whole-image and region level. It aligns the images, measures structure, color, detail, and horizontal bands, then assigns a verdict such as match, drift, missing, or contradicted.

The comparison uses region kind to weight what matters. Painted regions depend more on visual detail, while text and controls depend more on structure and color. The verb writes a report plus side-by-side, heatmap, and region-pair artifacts so the numbers point to visible repair work.

The comparison is a measurement aid, not a substitute for review. Its region crops show which component needs attention, while the build gate decides whether that result can close a phase.

References: crates/…/comp_diff.rs• L19-127 crates/…/comp_diff.rs• L331-420 crates/…/comp_diff.rs• L544-570

Build-phase operations

Build state

build-phase is the workflow coordinator. It stores the current phase, gate results, attempts, notes, forced decisions, asset receipts, and final disposition in project runtime state. This lets later commands know what the user approved and which evidence still applies.

The normal phase order is:

  1. comps selects one approved visual direction.
  2. spec measures its visible regions and type.
  3. plates produces and checks raster assets.
  4. hero builds and checks the first viewport.
  5. sections adds the remaining page sections.
  6. motion adds the signature interaction and motion.
  7. responsive checks common desktop and mobile views.
  8. review records the final disposition.

Each phase opens only after the prior phase closes. A failed gate keeps the phase open and reports the edits or decisions needed to continue.

References: crates/…/build_phase.rs• L28-35 crates/…/build_phase.rs• L139-170 crates/…/build_phase.rs• L2802-2904

Asset operations

The plates phase turns raster regions into production assets without changing the approved comp. A crop provides visual reference, a prompt states the intended subject and treatment, and the selected plate is checked against the region before the page depends on it.

The asset gate checks presence, decodability, scale, provenance, visual similarity, and the treatment of transparency. It also checks that a plate is actually used by the page. A candidate check can assess a separate file without changing the selected asset or build state.

The plan and asset review must be accepted before page work proceeds when the spec contains decisions that need a human. A forced plate result is bound to the exact asset, region, reference, and comp state that it waived.

References: crates/…/build_phase.rs• L502-699 crates/…/build_phase.rs• L716-739 crates/…/build_phase.rs• L2727-2750 crates/…/build_phase.rs• L3355-3389

Scaffold operation

build-phase scaffold creates a reference layout from the measured spec. It expresses region boxes as custom properties and includes measured type values where available. The page team binds those values to its own semantic markup instead of shipping the reference page.

The scaffold gives the build a stable starting point for composition. It does not decide the page structure for the engineer, and it does not make overlapping regions independent. The page must still render the correct pixels and preserve the relationships described by the spec.

References: crates/…/build_phase.rs• L977-1095 crates/…/build_phase.rs• L3500-3515

Hero operation

The hero phase checks the first viewport at the comp's intended dimensions. It combines whole-image comparison with region readings for text, chrome, plates, invented detail, and clipping. The goal is to establish the composition before the build grows beyond it.

The phase also connects the page capture to any accepted human review. A valid accepted viewport can turn some later differences into advisories, but it does not waive material failures such as missing assets or content that the page never renders. The runtime keeps the capture evidence tied to the source bytes while it evaluates the gate.

References: crates/…/build_phase.rs• L1528-1582 crates/…/build_phase.rs• L1696-1741 crates/…/build_phase.rs• L1743-1810

Responsive operation

The responsive phase checks whether the approved first viewport survives common desktop and mobile conditions. It compares the desktop first viewport with the comp and checks the mobile page as a full view. It also searches for regions that moved out of place so layout growth is not mistaken for deletion.

The phase reports a displaced region when its pixels can be found within the allowed search area but no longer sit in its comp box. After repeated failed attempts, the runtime stops treating the issue as routine iteration and asks for a user decision when the accepted desktop or first-viewport result conflicts with the comp.

References: crates/…/build_phase.rs• L2380-2398 crates/…/build_phase.rs• L2419-2469 crates/…/build_phase.rs• L2471-2547

Completion operation

build-phase completion answers whether a build can continue or whether a recorded ship decision still covers the current files. It checks phase closure, session ownership, the artifact, and the input files bound by the final capture or local input signature.

The result distinguishes an unfinished build from a build changed after finish. A later edit to the artifact or any bound input therefore requires a new final check instead of relying on an old approval.

References: crates/…/completion.rs• L54-95 crates/…/completion.rs• L98-160 crates/…/build_phase.rs• L2909-2933

Operation flow

The runtime moves from a visual reference to a checked page through a gated sequence. The diagram shows how the shared region contract links asset creation, page composition, comparison, and final completion.

flowchart LR
    A[Approved comp] --> B[comp-spec]
    B --> C[Measured region spec]
    C --> D[font-match]
    C --> E[Raster plate work]
    D --> F[build-phase scaffold]
    E --> F
    F --> G[Hero page]
    G --> H[comp-diff and hero gate]
    H --> I[Sections and motion]
    I --> J[Responsive captures]
    J --> K[Responsive gate]
    K --> L[Final review and completion]

When a gate fails, the state remains at the current phase. The engineer uses the report and the worst region crops to change the page or asset, captures again, and repeats the gate. A force can record a user-authorized downgrade, but it cannot make an unreadable reference or an invalid runtime state acceptable.

References: crates/…/build_phase.rs• L2697-2724 crates/…/build_phase.rs• L2802-2904 crates/…/completion.rs• L142-160

Change checklist

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

  • Keep the region kinds and verdict rules aligned between comp-spec, comp-diff, and the phase gates. A new kind can otherwise be measured but never gated correctly.
  • Preserve the approved-comp identity contract when changing spec creation, crop generation, comparison, or restore behavior. Every measurement must refer to the same approved pixels.
  • Update scaffold and responsive guidance together when region geometry or type fields change. They consume the same measured boxes and type choices.
  • Keep plate receipts bound to the comp, region, reference policy, and asset hashes. A receipt that omits one of these can survive a stale asset change.
  • Keep capture input evidence and completion fingerprints consistent with the files that the native capture actually binds.

Important failure modes

TriggerConsequenceGuard
The approved comp pixels changeAll comp-led measurements stop before producing new evidenceKept reference copy and pixel hash in approved-comp.json
The region map changes after measurementThe old spec cannot close the build phaseRegion-source hash check and required re-measurement
A raster region has no valid plate or the plate is only a comp cropThe plates phase stays open and the asset cannot be treated as production workPlate presence, decode, size, provenance, and visual gates
The page does not reference a measured plateThe hero gate reports the asset as unusedSource scan for page and linked stylesheets
A component moves below the desktop first viewportResponsive work reports displacement or missing contentBounded region search plus desktop and mobile capture gates
A final artifact or bound input changes after shipCompletion reports changed-after-finishArtifact, capture-input, and local input hashes
A force reason does not quote a user downgradeThe failed phase remains openForce authorization check

Key files

FileWhy to read it
crates/…/main.rsShows how the CLI exposes the four composition verbs and supplies browser-bound services.
crates/…/lib.rsGives the public runtime boundary and the separation between pure operations and injected services.
crates/…/comp_spec.rsDefines the measured region contract and the path from grid to spec, crop, and prompt.
crates/…/comp_diff.rsDefines whole-image and region comparison, verdicts, and review artifacts.
crates/…/build_phase.rsCoordinates phase state, gates, scaffold output, capture checks, and final transitions.
crates/…/font_match.rsExplains how lettering measurements become a recorded type choice.
crates/…/approved_comp.rsDefines the fixed-reference rule that protects every later measurement.
crates/…/displacement.rsShows how responsive checks distinguish moved regions from missing regions.
crates/…/completion.rsDefines final completion status and the evidence used to detect later changes.
crates/…/entry_capture.rsDefines the capture boundary used when hero and responsive gates evaluate native page renders.