visual-comparison

Visual Comparison Subagent

This script is delegated from Phase 5 of the main SKILL.md. Use Playwright MCP for all browser interactions.

---

Viewport → width mapping

Viewport	Playwright width	CSS breakpoint it falls within
Mobile	375 px	base (< 600 px)
Small tablet	768 px	600 px – 899 px
Large tablet	960 px	≥ 900 px
Desktop	1440 px	≥ 1200 px
Widescreen	1800 px	≥ 1680 px

Match these to whichever Figma frames were provided.

Only test viewports for which a Figma frame was provided.

Important: "Small tablet" (768 px) and "Large tablet" (960 px) may have different layouts even though they are both ≥ 600 px — the block's actual side-by-side breakpoint is derived from the Figma design, not the generic grid system. Always test both narrower and wider sides of the tablet range when a 600–899 px Figma frame was provided.

---

Comparison procedure (per breakpoint)

For each breakpoint:

1. Navigate to the Playwright URL (constructed in Phase 5b).
2. Set viewport width to the value from the table above. Set height to a generous value (e.g. 900 px) to avoid scroll clipping.
3. Wait for the block to finish rendering — wait for the block's root element to be visible and for any images inside it to load.
4. Force-refresh the block's CSS to bypass the CDN's max-age cache (EDS serves code with max-age=7200):

   const links = [...document.querySelectorAll('link[rel="stylesheet"]')];
   const blockLink = links.find(l => l.href.includes('blocks/<block-name>'));
   if (blockLink) blockLink.href = blockLink.href.split('?')[0] + '?v=' + Date.now();
   

   Skip this step for localhost mode.
5. Verify DOM structure with browser_evaluate before screenshotting. Check that decorated classes and any expected structural divs (e.g. .foreground, .text-content, .cta-container) are present. If the structure doesn't match what the latest JS should produce, the browser module cache may be stale — close the browser with browser_close, navigate fresh, and re-check before continuing.
6. Broken-image guard: run the following to detect broken images:

   const broken = [...document.querySelectorAll('.<block-name> img')]
     .filter(img => !img.complete || img.naturalWidth === 0)
     .map(img => ({
       src: img.src,
       cssAspectRatio: getComputedStyle(img).aspectRatio,
       intrinsic: `${img.naturalWidth}x${img.naturalHeight}`,
     }));
   

   If any images are broken:
   • Note it in Obstacles Encountered: "Image broken — CSS aspect-ratio cannot be visually verified; confirmed via getComputedStyle."
   • Skip shape, size, and aspect-ratio comparisons for those elements.
   • Do not fail the visual comparison for layout issues caused by the broken placeholder rendering at unexpected dimensions.
7. Screenshot the block's bounding box (not the full page). Use Playwright's element screenshot to capture just the component.
8. Computed-style spot-check: after the screenshot, run:

   const block = document.querySelector('.<block-name>');
   const fg = block.querySelector('.foreground');
   return {
     blockFlexDir:    getComputedStyle(block).flexDirection,
     blockPaddingInline: getComputedStyle(block).paddingInline,
     blockPaddingBlock:  getComputedStyle(block).paddingBlock,
     fgMaxWidth:      fg ? getComputedStyle(fg).maxWidth : null,
   };
   

   Verify flexDirection matches the expected layout (column vs row) for this breakpoint. If it doesn't match, treat as a layout failure regardless of how the screenshot looks — the CSS breakpoint is wrong.