# Design quality review

When `launch.json.designReferences` opts in, review the accepted reference relationships and direction identity invariants against the compiled homepage/interior at both widths. Cite the actual introduction, evidence, density changes, interior organization and action placement. Record identity lost during production as a specific finding; palette/font resemblance alone does not establish preservation. The working set is advisory and bounded; a delivered receipt is not an inspection, and fictional original-study content is not customer evidence.

This is a separate aesthetic gate from deterministic browser, accessibility, content-fidelity, and diversity checks. Strength in diversity or functionality cannot hide a quality fail.

Inspect production-compiled homepage and representative interior captures, not private HTML studies. Studies are sketches. Approving quality approves the exact source that later expansion reuses. Judge whether the central idea is visible in the page, not whether the typeface is unusual. Missing pixels cannot pass. An active-agent receipt is not an independent reviewer transcript.

In `composition-v1`, first inspect the current pages against visitor tasks and record what is visible. Then read storyboard intent and evaluate the declared render observations against the current capture and browser state. Locate satisfied, problematic, and unknown outcomes by route, section, element ID, viewport, and capture. A written author rationale cannot clear a visible problem. Appropriate repetition and a useful mobile stack may pass. Keep factual, functional, and aesthetic judgments separate.

Use anchored ordinal scores: 0 failing, 1 weak, 2 credible baseline, 3 strong, 4 exemplary. Floor: no dimension below 2. Business specificity, composition, and media integration must reach 3. These thresholds are provisional until operator labels exist; do not treat them as a learned preference model.

Dimensions, each with page, viewport, section, and observable evidence:
- business-specificity
- composition
- typography
- media-integration
- brand-coherence
- copy-design-integration
- responsive-craft

Hard fails: fabricated proof, central missing evidence, unreadable content, broken imagery, incoherent customer proposition. Decorative complexity, dark bands, huge type, animation, and section quotas are not universal requirements.

Visual inspection must actually see pixels. A passing visual capability probe records the current probe PNG hash and the observed fill-color token. The runner archives the exact representative-quality adapter log and binds it in a receipt; later logs cannot be substituted. Successful PNG readToolCall/dataBlobId fields invented in the review JSON are not provenance. If inspection is unavailable, mark visualInspection.available false and fail closed. Do not invent image-access approvals. Do not route to an unpaid or paid external model unless the operator configured that reviewer adapter explicitly.

Write `agent/reviews/representative-quality.json`. Repair composition, media, and copy causes, not only cosmetic color. Each candidate gets an initial quality review plus two bounded repair attempts. Persist attempts and reasons. Rejected or blocked on exhaustion; do not rely on a different graph retry ceiling.
`media-v1` additionally records artObservations for content-fit, visual-concept, asset-craft, sequence-coherence, responsive-treatment and explanatory-clarity. Use satisfied/problem/unknown/not-applicable with page, section, viewport, capturePath, captureSha256 and a located observation. Inspect pixels before reading the brief. Cite current inspected PNG captures; do not use imagery count, saturation or novelty as acceptance. Review meaningful captions, image order, crops and mobile diagram labels.


For scroll motion, use the stage-scoped `motion.md` contract. Choose business-specific scenes and quiet intervals; preserve operator policies. Carry motionPlan v2 for every new/reauthored route (historical v1 remains compatible) from direction/storyboard to unique native/component target IDs, then inspect before/during/after normal and reduced scrolling. Temporal claims require live observations or recordings; agent review is not human preference.


Whole-page motion responsibility: for new/reauthored routes use motionPlan v2 and read `motion-page`. Cover every authored route, including expansion/contact; locate opening, development, connected quiet intervals and closing in actual IDs. Keep essential content/actions static and readable. Representative runtime success or two colocated effects is insufficient. Inspect normal desktop/mobile full journeys and reduced/static views; critique distribution, continuity, inert stretches, competition and meaningful differences among routes with located evidence. Return actionable repairs, preserving operator off and historical records. Human preference stays unset.

For sites with typography version 1, load `typography.md`. Establish concrete shared roles before authoring, reuse sizes and weights across routes, retain the 12px rendered floor, and repair browser typography findings before acceptance. Template identity does not waive this policy.