>>> [!note] Migrated issue <!-- Drupal.org comment --> <!-- Migrated from issue #3588778. --> Reported by: [ajv009](https://www.drupal.org/user/3653917) >>> <h3 id="summary-problem-motivation">Problem/Motivation</h3> <p>The <code>visual-verifier</code> and Ralph Loop comparison agents default to full-page screenshot comparison. This approach fundamentally cannot detect three classes of defect that have produced repeated user complaints across multiple sessions:</p> <ol> <li><strong>Structural ordering</strong> &mdash; which element is above vs below in a card. Screenshots show the visual result, but the visual model compares images holistically; it does not enumerate DOM Z-order. A VideoCard with text-below-image vs reference text-above-image survived multiple ralph-loop iterations undetected. User: <em>"in my screenshot the text is above or anchored to the top of the image, while the one you made the text is below... you did not notice that in all our work so far?"</em></li> <li><strong>CSS property values</strong> &mdash; font-weight 400 vs 600, line-height 1.2 vs 1.62, container max-width 1200px vs 1280px. These are invisible or barely visible in screenshots but are exactly measurable by <code>getComputedStyle</code>. A measured 80px container width error was invisible in screenshots; a subtitle color delta (<code>oklch(0.373 0.034 259.733)</code> vs <code>rgb(37,37,37)</code>) was equally invisible.</li> <li><strong>Mercury theme CSS cascade overrides</strong> &mdash; Mercury's non-layered CSS silently wins over Canvas's Tailwind output. The result may look "close enough" in a screenshot while the underlying CSS is wrong and breaks on resize.</li> </ol> <p>User feedback is unambiguous: <em>"your sweep is bad, the page looks nothing alike, so many many more issues across ALL the pages"</em> and <em>"compare component level not just an overview of page."</em> A later user instruction added: pages should be <em>"as identical as possible to the point that if you take their image hashes maybe they be almost similar with just slight variations."</em></p> <p>The Q3 sessions solved this by using <code>getComputedStyle</code> as the primary tool and screenshots as supplementary, finding 12+ issues per component that screenshots had missed. That pattern was not encoded into the skill and was therefore not carried forward.</p> <h4 id="summary-steps-reproduce">Steps to reproduce</h4> <ol> <li>Run a visual-verifier or Ralph Loop comparison pass on a built site that has known CSS deltas (different font-weight, container max-width, or color tokens).</li> <li>Inspect the agent's tool calls.</li> <li>Observe: only <code>take_screenshot</code> calls are made; no <code>evaluate_script</code> with <code>getComputedStyle</code>; no DOM-order enumeration.</li> <li>Observe: the agent reports the page "looks correct" while the measured CSS deltas are still wrong.</li> </ol> <h3 id="summary-proposed-resolution">Proposed resolution</h3> <p>Encode the three-tier comparison protocol from the Q3 working implementation into <code>.claude/agents/visual-verifier.md</code> and <code>.claude/agents/storybook-qa.md</code>:</p> <p><strong>Tier 1 &mdash; STRUCTURAL (required, run first):</strong></p> <p>For each section/card being compared, enumerate DOM children of the section and list element types in order for both source and target. Verify element order matches (e.g., <code>[div.image, h2.title, p.description, a.button]</code>). A structural mismatch (wrong order) is a CRITICAL finding &mdash; do not proceed to CSS measurement until structural order is confirmed correct or the structural issue is filed.</p> <p><strong>Tier 2 &mdash; CSS PROPERTY MEASUREMENT (required for any suspected mismatch):</strong></p> <p>For key elements in each section, run via <code>mcp__chrome-devtools__evaluate_script</code>:</p> <pre>const el = document.querySelector('.target-element'); const cs = getComputedStyle(el); return { fontSize: cs.fontSize, fontWeight: cs.fontWeight, color: cs.color, padding: cs.padding, margin: cs.margin, lineHeight: cs.lineHeight, textTransform: cs.textTransform, letterSpacing: cs.letterSpacing, maxWidth: cs.maxWidth, gridTemplateColumns: cs.gridTemplateColumns };</pre><p>Run on both source and target. Report exact deltas. Any delta &gt; 10% is a candidate issue.</p> <p><strong>Tier 3 &mdash; SCREENSHOT (supplementary only):</strong></p> <p>Use for overall layout geometry, color rendering, element visibility, responsive breakpoints. Do NOT use as the sole comparison method.</p> <p>Add to the Ralph Loop stop-hook prompt: <em>"Before taking any screenshot, run the Tier 1 structural check and Tier 2 CSS measurement for each component. Report exact measured deltas. Only after measurement: take screenshots for visual confirmation."</em></p> <p>Enforce <code>mcp__chrome-devtools__*</code> as the exclusive browser tool during visual comparison phases (not <code>agent-browser</code> CLI). Always verify on <code>&lt;site&gt;.cms.acquia.site</code> (CMS URL), never the CDN URL <code>&lt;site&gt;.acquia.site</code>.</p> <h3 id="summary-remaining-tasks">Remaining tasks</h3> <ul> <li>Replace or augment the comparison protocol in <code>visual-verifier.md</code> with the three-tier method (structural &rarr; CSS &rarr; screenshot).</li> <li>Mirror the protocol into <code>storybook-qa.md</code> for Storybook-phase comparison.</li> <li>If a separate <code>visual-comparison</code> SKILL.md exists, add the three-tier protocol as the mandatory lead step with the ready-to-paste measurement script.</li> <li>Add the structural-check-first instruction to the Ralph Loop prompt (<code>.claude/ralph-loop.local.md</code> or equivalent).</li> <li>Verify on a live run: at least 5 elements per section are measured via <code>evaluate_script</code> before any screenshot is taken; output includes a table of measured deltas (source vs built) for font-size, color, margin, padding, max-width.</li> <li>Verify a Mercury theme override is correctly identified (a <code>getComputedStyle</code> value that differs from the Tailwind class applied).</li> </ul> <h3 id="summary-ui-changes">User interface changes</h3> <p>None.</p> <h3 id="summary-api-changes">API changes</h3> <p>None &mdash; the tooling (<code>mcp__chrome-devtools__evaluate_script</code>) already exists and is in use.</p> <h3 id="summary-data-model-changes">Data model changes</h3> <p>None.</p> <h3 id="summary-internal-references">Internal references</h3> <ul> <li>Source markdown: <code>RESEARCH-2026-04-28/99-final/ISSUES/Sprint-3-Visual-Fidelity/03-visual-sweep-too-coarse-compare-component-level.md</code> (id: P1-10)</li> <li>Working implementation: <code>RESEARCH-2026-04-28/03-efi-ed-source/Q3-records-5768-to-8651/visual-fidelity-iteration-pattern.md</code></li> <li>User feedback (sweep quality): <code>RESEARCH-2026-04-28/06-jamie-demo-old/95q5i-77cf5bb9-half1/user-feedback.md</code> (L4855)</li> <li>User feedback (escalated prompt): <code>RESEARCH-2026-04-28/06-jamie-demo-old/95q5i-77cf5bb9-half2/user-feedback.md</code> (L7999)</li> <li>Layout-inversion evidence: <code>RESEARCH-2026-04-28/02-edu-site-mockup-ai/dbc7a979/issues-found.md</code> (CRITICAL-2)</li> <li>Pattern: <code>RESEARCH-2026-04-28/07-cross-cutting/what-actually-works.md</code> &sect; P2 (getComputedStyle Measurement Beats Screenshot Comparison)</li> <li>Pattern: <code>RESEARCH-2026-04-28/07-cross-cutting/what-actually-works.md</code> &sect; P18 (Structural DOM-Order Check Before Pixel Comparison)</li> <li>Recommendation source: <code>RESEARCH-2026-04-28/99-final/migrate-site-skill-recommendations.md</code> (<code>.claude/agents/visual-verifier.md</code> three-tier protocol template)</li> </ul> <h3 id="summary-open-questions">Open questions</h3> <ul> <li>Does the current <code>visual-comparison</code> skill exist as a separate skill file or is it embedded in <code>visual-verifier.md</code>? Locate both before editing to avoid duplicate changes.</li> <li>The <code>evaluate_script</code> measurement needs to run on the source site AND the target site in the same session. Document the page-switching protocol used in the Q3 sessions (navigate source &rarr; measure &rarr; navigate target &rarr; measure) in the updated agent instructions.</li> </ul>