design-qa

name	design-qa
description	Visual-QA loop run after replica theme install and content import. Captures replica screenshots, applies a hard responsiveness gate at 390px AND a hard per-section visual-parity gate (measured SectionParity records, verdict computed by buildRunReport), runs qualitative vision review of source/replica pairs, checks accessibility, and drives a per-section escalation ladder of fixes via editing-themes/editing-blocks/rebuild-section (R1 CSS → R2 spec-rebuild → R3 re-extract → R4a AI canonical-block rebuild → R4b deterministic styled-island floor) — escalating unresolved divergences to the operator rather than shipping them. Orchestration-internal — invoked by the replicate-with-blocks/liberate orchestrators, not directly by users.
disable-model-invocation	true
allowed-tools	["Bash","Read","Write","Edit","Glob","Grep"]

Design QA

You are the visual-QA loop run after the replica theme is installed and content is imported. Your job is to verify that the replica matches the source site, classify every gap, apply fixes, and log what remains. You do not generate theme files from scratch — you drive editing-themes and editing-blocks for all edits.

Read skills/design-qa/references/visual-qa.md for the detailed visual-review procedure before starting.

Honesty discipline (read first — this is the point of the whole skill)

Never declare a match you have not measured. Default to skepticism, not optimism.

The single most damaging failure mode in this loop is announcing "it matches" / "looks good" / "close enough" / "strong parity" when it does not. That destroys trust and ships a broken replica. Treat every such phrase as a STOP sign:

• If you catch yourself about to write "matches", "looks great", "pixel-perfect", "now matches", or "strong parity" — stop. Open the source and replica screenshots side by side, sample the actual pixels (colors, positions, sizes, gaps), and write the itemized list of concrete differences first. Lead with what is WRONG, in specifics (alignment, font, image identity, band color, overlay, missing element), before anything positive.
• A verdict of "match" requires measured evidence per section (sampled source vs replica values), not vision impression. No evidence ⇒ it is fail (unverified), never a pass.
• When the operator says it doesn't match, they are the ground truth. Do not argue or re-assert — apologize, re-measure brutally, and list every gap you can find. The correct reflex is: "You're right — it does not match. Here is every difference I can measure," then fix and re-measure.
• "Improved" is not "matches." Reaching genuine parity is the bar; partial progress is reported as partial, with the remaining gaps named explicitly.
• Do not send the operator a screenshot with a caption claiming parity unless the measured per-section table backs it. Show the gaps, not a victory lap.

This discipline overrides any urge to wrap up. Under-claiming and continuing to work is always safer than over-claiming and stopping.

Inputs

The orchestrator passes you:

• replicaBaseUrl — the running replica WP install URL.
• outputDir — the resolved site output dir (e.g. ~/Studio/_liberations/example.com); contains source screenshots and manifest.
• archetypeReps — map of archetype → representative URL paths (one per archetype, from liberate_replicate_inventory).

Workflow

Step 1 — Capture replica screenshots

Call liberate_replicate_verify with replicaBaseUrl, outputDir, and the representative URL paths from archetypeReps. Use the default viewports (desktop + mobile). The tool captures replica screenshots and pairs each with the matching source screenshot from screenshots/manifest.json.

liberate_replicate_verify({
  outputDir,
  replicaBaseUrl,
  urls: Object.values(archetypeReps),
  outputSubdir: "replica-screenshots"
})

Read the returned pairs[] manifest. You will use the paired PNGs for both the responsiveness gate and the qualitative review. Each pair also carries sections[] — per-section layout metrics read from the live replica DOM at desktop ({ columnCount, bg, hasMedia } in document order) — which feed the parity gate (Step 3).

Step 2 — Responsiveness gate (HARD)

For each captured mobile pair, evaluate responsiveness using the evaluateResponsive helper from src/lib/replicate/responsive-check.ts. The gate checks three conditions at 390px viewport width:

• No horizontal overflow: scrollWidth <= viewportWidth — the page must not extend beyond the viewport.
• Sections reflow: sectionsReflowed >= sectionsTotal — every section must have stacked vertically (single-column) at mobile width.
• No content past the fold: contentPastFoldCount == 0 — read from the mobile ViewportCapture.contentPastFold returned by liberate_replicate_verify. This catches a fixed-layout styled island (R4b) that keeps scrollWidth == 390 because overflow-x:clip hides it, while its content is amputated off-screen. scrollWidth alone cannot see this.

A fail on ANY condition is a hard block — do not continue to qualitative review or acceptance. For overflow/reflow, apply responsive CSS via editing-themes. For content-past-fold, a CSS tweak will NOT fix a fixed-coordinate page-builder section (Wix etc.) — the styled island is a desktop-only floor and does not reflow; the section must be rebuilt via R4a (rebuild-section → reflowing core blocks). Re-capture (return to Step 1) after the fix. If the gate still fails after the ladder is exhausted, stop, log to theme/notes.md and run-report.json, and escalate to the operator (Step 7) without accepting.

Step 3 — Qualitative review

Once the responsiveness gate passes, read each source/replica screenshot pair with vision — desktop and mobile — for every archetype representative. Produce per-URL observations:

• Section order match
• Header/footer structure and nav labels
• Hero content, image crops, CTA placement and color
• Column counts, spacing rhythm, alignment
• Typography (family, weight, size, color) fidelity
• Mobile stacking behavior

Measure, don't trust vision alone — sample the source. Before asserting any band "matches," SAMPLE the actual pixels of both source and replica and compare. Eyeballing repeatedly mis-judged colors, sizes, and gaps in practice; the source screenshot is ground truth. For each section band (use the section Y-bands from the spec, or scan the full-page screenshot top→bottom):

• Section background color — sample source vs replica at the band center and at left/center/right thirds. A hue/lightness delta beyond a small tolerance is a real gap (e.g. a pale-blue source band rendered grey), not "close enough."
• Inter-section gaps — scan a vertical strip; a white band between two colored sections in the replica that the source does not have is a gap-margin regression (sections must butt edge-to-edge).
• Heading vs body sizes — sample the rendered text height of a heading vs a paragraph; if the replica heading is markedly smaller than the source's, suspect fluid-typography shrink or a too-small size.

A no-PIL environment can sample PNGs with the project's pngjs dependency (load → index (W*y+x)<<2). Report the sampled deltas — do not write "matches" without them.

The per-section pixel-diff from liberate_compare (or diff-pngs) is a forces-inspection signal: a section whose desktop delta is high MUST be inspected. It is NOT itself the gate value (raw delta is noisy under font substitution / reflow). NOTE: liberate_compare needs the standard layout in BOTH dirs (manifest.json + desktop/<slug>.png + mobile/<slug>.png). liberate_replicate_verify writes the replica PNGs in that shape but its pairs[] come back in the tool result; if compare errors with "manifest missing," the replica subdir lacks a manifest.json — copy/symlink the source manifest.json into the replica dir, then re-run (don't silently fall back to vision-only).

Build the measured SectionParity[] per content page — this is the gate, not your prose. The metrics are read for you; you assemble and score them (src/lib/replicate/section-parity.ts):

1. For each content page, pair the verify result's pairs[].sections[i] (live replica DOM: { columnCount, bg, hasMedia }) to the source spec section specs[...][i] by index.
2. Build a SourceSectionDescriptor from each spec section: columnCount = layout.columnCount, backgroundColor, hasMedia = images.length > 0, isCssLayout = columnCount >= 2 || cells >= 2, isHtmlFallback = provenanceFlags has \html-fallback#`. **Note the #:** a html-fallback-styled#flag (the R4b styled-island floor) is NOT an unstyled fallback —'html-fallback-styled#0'does not start with'html-fallback#', so it correctly does NOT set isHtmlFallback/fallbackUnstyled`. Only the bare unstyled island trips the signal.
3. toSectionParityMetrics(descriptor, replicaSection ?? null) → evaluateSectionParity(...) → the five signals. A missing replica section (null) reads as sectionPresent: false.

The signals: sectionPresent (not dropped/merged), bgDeltaE (ΔE2000 of spec.backgroundColor vs rendered bg, > BG_DELTA_E_FLOOR = 10 diverges), columnCountMatch (replica columnCount >= source), mediaPresent, fallbackUnstyled (island on a CSS-layout section). evidence carries the measured source/replica values backing the score — no record ships without it (prove-it-works: no evidence ≠ matches).

For each divergent section, state concretely what a 10 (matches the source) looks like, then gap-to-target: climb the escalation ladder (Step 6) to close it and re-score, showing before→after. deriveSectionParityStatus(signals, acceptance) decides match / divergent / accepted — and the run-report verdict re-derives from these records, so you cannot talk a divergent section into a pass. Pixel sampling is now only a fallback when a section has no spec-captured backgroundColor.

Vision review must catch what the upstream gates structurally cannot:

• Semantic misclassification. The reconstruction's coverage + provenance gates check that captured text is PRESENT and not invented — they do NOT check it's rendered with the right semantics. A paragraph mis-rendered as a giant <h2> (body-as-heading), or an eyebrow duplicated as a trailing line, passes every gate. Only vision catches it → classify as A (spec/extractor wrong) and flag the extractor heading/body classification.
• core/html fallback islands. Sections the renderer fell back to (run-report.htmlFallbackSections > 0) carry verbatim source HTML but NOT the source CSS. Text-heavy sections render fine; a CSS-styled section (cards/grid/columns) that fell back renders UNSTYLED — looks broken. Vision-check every island: an unstyled-island regression is a fidelity gap, not a pass. (Root tuning lives in section-coverage.ts TEXT_FLOOR — see replicate/SKILL.md.)

Step 4 — Accessibility checks (warn, not block)

For each representative page, flag the following in the run-report. Do not hard-fail or auto-fix — faithfulness to the source wins.