Claude Skill

visual-qa

Use when verifying that a UI renders correctly. Covers visual regression testing, responsive checks across breakpoints, cross-browser verification, and screenshot-based review of an implementation against a design. Trigger on "does this match the figma", "set up screenshot tests"

LLM Mart · 0 points · 2 views 0 listing impressions 0 install-command copies
Download nimadorostkar-claude-skills-collection-skills_frontend_visual-qa-1691932.zip · 2 KB

Install

skills CLI npx skills add https://github.com/nimadorostkar/Claude-Skills-collection/tree/main/skills/frontend/visual-qa
Claude Code claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install nimadorostkar-claude-skills-collection@llmmart
Git git clone https://github.com/nimadorostkar/Claude-Skills-collection.git

The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole nimadorostkar/claude-skills-collection collection as a plugin from our marketplace. Git is the plain clone.

Skill manifest

Visual QA

Purpose

Catch visual defects before users do. Functional tests confirm the button works; they say nothing about the button being invisible, overlapping, or off-screen on a phone.

When to Use

  • Verifying an implementation against a design.
  • Setting up visual regression testing.
  • Checking responsive behavior across breakpoints.
  • Reviewing a UI change that a unit test cannot meaningfully assert on.

Capabilities

  • Visual regression testing with deterministic screenshots.
  • Responsive verification across a defined breakpoint set.
  • Cross-browser and cross-platform rendering checks.
  • Design-to-implementation comparison.
  • Detection of layout shift, overflow, and truncation.

Inputs

  • The design reference, if there is one.
  • The breakpoints and browsers that are in scope.
  • The pages or components under test, and their states.

Outputs

  • Baseline screenshots committed to the repository.
  • A diff report for each change, with the pixel delta.
  • A list of visual defects with viewport and browser.

Workflow

  1. Enumerate the states — Not just the happy one. Empty, loading, error, long content, and the state with a 60-character name in a field designed for eight.
  2. Make screenshots deterministic — Freeze time, seed data, disable animations, and wait for fonts and images. A flaky visual test is worse than no visual test; it will be ignored, then deleted.
  3. Capture at every breakpoint — Mobile (375), tablet (768), desktop (1280), wide (1920). Check the boundaries themselves, where layouts switch.
  4. Diff against the baseline — Review each diff. Approve intentional changes to update the baseline; investigate the rest.
  5. Check the overflow cases — Long words, long lists, missing images, and a 200% browser zoom. These are where layouts break, and where designs rarely go.

Best Practices

  • Animation and time are the two causes of visual-test flakiness. Disable both in the test environment before you do anything else.
  • Screenshot the component, not the whole page, when testing a component. A full-page baseline changes every time anything on the page does.
  • A visual diff threshold that is too tight flags anti-aliasing noise; too loose and it misses a 4px misalignment. Tune it once, on real diffs.
  • Test the states that are hard to reach manually — error, empty, and loading — because those are the ones nobody looks at before shipping.
  • Run visual tests in a container so the fonts and rendering engine are identical to CI. Screenshots taken on macOS will not match those taken on Linux.
  • Review the diff, do not just approve it. A rubber-stamped baseline update defeats the entire mechanism.

Examples

Deterministic Playwright visual test across breakpoints and states:

const VIEWPORTS = [
  { name: "mobile",  width: 375,  height: 812 },
  { name: "tablet",  width: 768,  height: 1024 },
  { name: "desktop", width: 1280, height: 800 },
];

for (const vp of VIEWPORTS) {
  test.describe(`order card @ ${vp.name}`, () => {
    test.use({ viewport: { width: vp.width, height: vp.height } });

    for (const state of ["default", "loading", "error", "long-content"] as const) {
      test(state, async ({ page }) => {
        await page.clock.setFixedTime(new Date("2026-01-15T12:00:00Z")); // freeze time
        await page.goto(`/storybook/order-card?state=${state}`);
        await page.waitForFunction(() => document.fonts.ready);          // fonts settled

        await expect(page.getByTestId("order-card")).toHaveScreenshot(
          `order-card-${state}-${vp.name}.png`,
          { animations: "disabled", maxDiffPixelRatio: 0.01 },
        );
      });
    }
  });
}

Catching overflow that a functional test would pass:

test("long customer name does not overflow the card", async ({ page }) => {
  await page.goto("/orders/ord_1?customer=Bartholomew%20Wintersmith-Kensington");

  const card = page.getByTestId("order-card");
  const overflows = await card.evaluate(
    (el) => el.scrollWidth > el.clientWidth || el.scrollHeight > el.clientHeight,
  );
  expect(overflows).toBe(false);
});

Notes

  • page.clock (Playwright 1.45+) freezes both Date and timers, which is what makes relative timestamps ("2 hours ago") stable in screenshots.
  • Storybook plus a visual-testing runner gives you every component state in isolation, which is far cheaper to screenshot than navigating the real application into each state.
  • Visual tests are not a substitute for accessibility testing. A screenshot cannot tell you the contrast is 2.1:1.
Files (claude-skills-collection)
  • SKILL.md 5.1 KB
    ---
    name: visual-qa
    description: Use when verifying that a UI renders correctly. Covers visual regression testing, responsive checks across breakpoints, cross-browser verification, and screenshot-based review of an implementation against a design. Trigger on "does this match the figma", "set up screenshot tests", "layout breaks on mobile", "looks wrong in safari". Do not use for exploratory behavior testing — see the web-app-testing skill; for design critique, see the ui-review skill.
    metadata:
      category: frontend
      version: 1.0.0
      tags: [visual-testing, regression, screenshots, responsive, qa]
    ---
    
    # Visual QA
    
    ## Purpose
    
    Catch visual defects before users do. Functional tests confirm the button works; they say nothing about the button being invisible, overlapping, or off-screen on a phone.
    
    ## When to Use
    
    - Verifying an implementation against a design.
    - Setting up visual regression testing.
    - Checking responsive behavior across breakpoints.
    - Reviewing a UI change that a unit test cannot meaningfully assert on.
    
    ## Capabilities
    
    - Visual regression testing with deterministic screenshots.
    - Responsive verification across a defined breakpoint set.
    - Cross-browser and cross-platform rendering checks.
    - Design-to-implementation comparison.
    - Detection of layout shift, overflow, and truncation.
    
    ## Inputs
    
    - The design reference, if there is one.
    - The breakpoints and browsers that are in scope.
    - The pages or components under test, and their states.
    
    ## Outputs
    
    - Baseline screenshots committed to the repository.
    - A diff report for each change, with the pixel delta.
    - A list of visual defects with viewport and browser.
    
    ## Workflow
    
    1. **Enumerate the states** — Not just the happy one. Empty, loading, error, long content, and the state with a 60-character name in a field designed for eight.
    2. **Make screenshots deterministic** — Freeze time, seed data, disable animations, and wait for fonts and images. A flaky visual test is worse than no visual test; it will be ignored, then deleted.
    3. **Capture at every breakpoint** — Mobile (375), tablet (768), desktop (1280), wide (1920). Check the boundaries themselves, where layouts switch.
    4. **Diff against the baseline** — Review each diff. Approve intentional changes to update the baseline; investigate the rest.
    5. **Check the overflow cases** — Long words, long lists, missing images, and a 200% browser zoom. These are where layouts break, and where designs rarely go.
    
    ## Best Practices
    
    - Animation and time are the two causes of visual-test flakiness. Disable both in the test environment before you do anything else.
    - Screenshot the component, not the whole page, when testing a component. A full-page baseline changes every time anything on the page does.
    - A visual diff threshold that is too tight flags anti-aliasing noise; too loose and it misses a 4px misalignment. Tune it once, on real diffs.
    - Test the states that are hard to reach manually — error, empty, and loading — because those are the ones nobody looks at before shipping.
    - Run visual tests in a container so the fonts and rendering engine are identical to CI. Screenshots taken on macOS will not match those taken on Linux.
    - Review the diff, do not just approve it. A rubber-stamped baseline update defeats the entire mechanism.
    
    ## Examples
    
    **Deterministic Playwright visual test across breakpoints and states:**
    
    ```typescript
    const VIEWPORTS = [
      { name: "mobile",  width: 375,  height: 812 },
      { name: "tablet",  width: 768,  height: 1024 },
      { name: "desktop", width: 1280, height: 800 },
    ];
    
    for (const vp of VIEWPORTS) {
      test.describe(`order card @ ${vp.name}`, () => {
        test.use({ viewport: { width: vp.width, height: vp.height } });
    
        for (const state of ["default", "loading", "error", "long-content"] as const) {
          test(state, async ({ page }) => {
            await page.clock.setFixedTime(new Date("2026-01-15T12:00:00Z")); // freeze time
            await page.goto(`/storybook/order-card?state=${state}`);
            await page.waitForFunction(() => document.fonts.ready);          // fonts settled
    
            await expect(page.getByTestId("order-card")).toHaveScreenshot(
              `order-card-${state}-${vp.name}.png`,
              { animations: "disabled", maxDiffPixelRatio: 0.01 },
            );
          });
        }
      });
    }
    ```
    
    **Catching overflow that a functional test would pass:**
    
    ```typescript
    test("long customer name does not overflow the card", async ({ page }) => {
      await page.goto("/orders/ord_1?customer=Bartholomew%20Wintersmith-Kensington");
    
      const card = page.getByTestId("order-card");
      const overflows = await card.evaluate(
        (el) => el.scrollWidth > el.clientWidth || el.scrollHeight > el.clientHeight,
      );
      expect(overflows).toBe(false);
    });
    ```
    
    ## Notes
    
    - `page.clock` (Playwright 1.45+) freezes both `Date` and timers, which is what makes relative timestamps ("2 hours ago") stable in screenshots.
    - Storybook plus a visual-testing runner gives you every component state in isolation, which is far cheaper to screenshot than navigating the real application into each state.
    - Visual tests are not a substitute for accessibility testing. A screenshot cannot tell you the contrast is 2.1:1.
    

Comments (0)

Sign in to join the conversation.

No comments yet.

Reviews (0)

No reviews yet.