Blog — VitePress

Visual QA for CSS / Layout Changes

Any change to CSS, layout, or UI components must be validated visually before considering the task complete. Do not just screenshot and eyeball — run the programmatic overflow check at each viewport.

Start the dev server with npx vitepress dev before testing.

Viewports to test

• Mobile S: 320×568 (smallest device still in use — catches overflow)
• Mobile: 375×812 (most common iPhone size)
• Mobile L: 428×926 (large phones — iPhone Pro Max, big Androids)
• Tablet: 768×1024 (iPad — right at the max-width: 768px breakpoint)
• Desktop: 1440×900 (standard laptop)

Validation steps (at each viewport)

1. Resize browser with Playwright (browser_resize).
2. Navigate to the affected page.
3. Wait for content to load, then run this overflow check via browser_evaluate:

   () => {
     const docWidth = document.documentElement.clientWidth;
     const overflows = [];
     document.querySelectorAll('*').forEach(el => {
       if (el.closest('[style*="overflow"]')) return;
       const rect = el.getBoundingClientRect();
       if (rect.right > docWidth + 1) {
         overflows.push({
           tag: el.tagName,
           class: el.className.substring(0, 60),
           rightEdge: Math.round(rect.right),
           viewportWidth: docWidth,
         });
       }
     });
     return {
       pageScrollsHorizontally: document.body.scrollWidth > docWidth,
       overflows,
     };
   }

4. Fail criteria — any of these means the change is not ready:
   • pageScrollsHorizontally is true
   • Any element in overflows that is not inside a scrollable container
   • Visual clipping of text or interactive elements (take a screenshot and inspect)
5. Take a screenshot and verify no visual issues (cut-off text, overlapping elements, excessive whitespace gaps).

Common mobile pitfalls

• Flex children won't shrink below content size without min-width: 0.
• position: relative wrappers inside overflow: auto containers can report bounding rects outside the viewport — check if they're visually clipped before flagging.
• 100vw includes scrollbar width on desktop; prefer 100% for max-width constraints.
• Always check both the initial state and after content loads (API data, images).