KeiSeiKit-1.0/skills/visual-loop/SKILL.md

---

name: visual-loop description: Scaffold + run continuous visual / a11y / responsive regression checks via Playwright. One-command setup per project (config + spec template + npm script + baseline), then npm run visual-check produces diff report. Composes with /dev-guard frontend-validator and auto-dev-guard hook. argument-hint: [project-root] (defaults to CWD)

/visual-loop — Visual / A11y / Responsive Regression Loop

Polish problem: button moved 4px right after font-weight change, color shifted 2 shades after Tailwind upgrade. Type-check + lint don't catch it. Visual diff does.

When to use

• First time on a project → scaffolds Playwright config + spec template
• Subsequent runs → executes the existing checks, reports diff
• Triggered by /dev-guard 4th agent (frontend-validator) when package.json has visual-check script
• Triggered by auto-dev-guard.sh hook (advisory) when frontend file edited and Playwright present

Phase 0 — Detect state

1. Walk up from $ARG (or CWD) to find project root (package.json, pubspec.yaml).
2. Stack-detect:
   • Next.js → app/ route discovery, next.config.*
   • Vite + React → src/routes/ or routes config
   • Vite + Vue → similar
   • SvelteKit → src/routes/
   • Astro → src/pages/
   • Flutter (web) → lib/main.dart, run via flutter run -d web-server
3. Check if Playwright is set up:
   • playwright.config.{ts,js,mjs,cjs} exists?
   • node_modules/@playwright/test installed?
   • npm script visual-check defined?

Branch:

• All present → skip to Phase 2 (run).
• Missing pieces → Phase 1 (scaffold), then Phase 2.

Phase 1 — Scaffold (one AskUserQuestion batch)

Single click-only confirmation:

AskUserQuestion: Set up visual-loop in <project-name>?
Options:
  1. Yes — install Playwright + browsers, scaffold config + specs, add npm script
  2. Lite — config + specs only (assume Playwright + browsers already installed)
  3. Cancel

On Yes:

cd <project-root>
npm install --save-dev @playwright/test
npx playwright install --with-deps chromium

On Yes or Lite:

Write playwright.config.ts:

import { defineConfig, devices } from "@playwright/test";

export default defineConfig({
  testDir: "./e2e",
  outputDir: "./.playwright/output",
  snapshotDir: "./.playwright/snapshots",
  reporter: process.env.CI ? "github" : "list",
  use: {
    baseURL: process.env.BASE_URL ?? "http://localhost:3000",
    screenshot: "only-on-failure",
    trace: "retain-on-failure",
  },
  projects: [
    { name: "desktop-chrome",  use: { ...devices["Desktop Chrome"]  } },
    { name: "mobile-iphone",   use: { ...devices["iPhone 14"]       } },
    { name: "tablet-ipad",     use: { ...devices["iPad Pro 11"]     } },
  ],
  webServer: {
    command: "npm run dev",
    url: "http://localhost:3000",
    reuseExistingServer: !process.env.CI,
    timeout: 120_000,
  },
});

Write e2e/visual.spec.ts — auto-discovers routes via filesystem walk of app/ (Next.js) or equivalent:

import { test, expect } from "@playwright/test";
import { readdirSync, statSync } from "node:fs";
import { join } from "node:path";

// Discover routes: Next.js app-router style. Adapt for other stacks.
function discoverRoutes(root = "app"): string[] {
  const out: string[] = [];
  const walk = (dir: string, prefix: string) => {
    let entries: string[];
    try { entries = readdirSync(join(process.cwd(), dir)); }
    catch { return; }
    for (const e of entries) {
      const full = join(dir, e);
      const st = statSync(join(process.cwd(), full));
      if (st.isDirectory()) {
        // Skip route groups, dynamic segments for now (need fixture data).
        if (e.startsWith("(") || e.startsWith("[")) continue;
        walk(full, `${prefix}/${e}`);
      } else if (e === "page.tsx" || e === "page.jsx") {
        out.push(prefix || "/");
      }
    }
  };
  walk(root, "");
  return Array.from(new Set(out));
}

const routes = discoverRoutes();

for (const route of routes) {
  test(`visual: ${route}`, async ({ page }) => {
    await page.goto(route);
    await page.waitForLoadState("networkidle");
    await expect(page).toHaveScreenshot(`${route.replace(/\//g, "_") || "root"}.png`, {
      maxDiffPixelRatio: 0.01,
      fullPage: true,
    });
  });
}

Write e2e/a11y.spec.ts:

import { test, expect } from "@playwright/test";
import AxeBuilder from "@axe-core/playwright";

const routes = ["/"]; // extend per project

for (const route of routes) {
  test(`a11y: ${route}`, async ({ page }) => {
    await page.goto(route);
    await page.waitForLoadState("networkidle");
    const results = await new AxeBuilder({ page })
      .withTags(["wcag2a", "wcag2aa", "best-practice"])
      .analyze();
    expect(results.violations).toEqual([]);
  });
}

Patch package.json scripts:

{
  "scripts": {
    "visual-check": "playwright test e2e/visual.spec.ts",
    "a11y-check": "playwright test e2e/a11y.spec.ts",
    "visual-update": "playwright test e2e/visual.spec.ts --update-snapshots"
  }
}

Append to .gitignore:

.playwright/output/
.playwright/test-results/

Snapshot baseline (.playwright/snapshots/) stays in git — that's the baseline against which future diffs run.

Install @axe-core/playwright:

npm install --save-dev @axe-core/playwright

Phase 2 — First run (establish baseline OR diff)

cd <project-root>
npm run visual-check

First time → creates baseline screenshots (no diff yet). Subsequent runs → diff against baseline. Failures = visual regression.

If baseline doesn't exist (first ever run on this snapshot), --update-snapshots runs implicitly. Subsequent failures show diff PNGs in .playwright/output/.

Phase 3 — Triage diff (if any)

If npm run visual-check returned non-zero:

AskUserQuestion: Visual diff in N route(s):
Options:
  1. Approve as new baseline (npm run visual-update)
  2. Review diffs first (open .playwright/output/<route>/diff.png)
  3. Fix the regression in code (no baseline change)
  4. Cancel

Click drives action.

Composition with other skills

• /dev-guard frontend-validator agent: step 5 — if package.json has visual-check script, invoke npm run visual-check. Severity: WARN on diff.
• /dev-ship frontend-final-gate agent (Wave 5): step — full visual+a11y+responsive+Lighthouse pass before merge.
• auto-dev-guard.sh hook: if Playwright present + edit affects routes, spawn background advisory.

Rules

• Click-only. Free-text only for explicit baseline override scenarios.
• Never delete .playwright/snapshots/ without explicit user approval — it's the baseline.
• Don't over-fixture. Phase 1 covers static routes; dynamic routes ([id], route groups) need per-project fixture data — defer to user.
• Bypass: if user runs KEI_DISABLED_HOOKS=auto-dev-guard ... the hook skips visual check.

Final report

=== VISUAL-LOOP REPORT ===
Project:    <name>
Stack:      <Next.js / Vite / ...>
Routes:     N discovered, M tested
Visual:     PASS / N diff(s)
A11y:       PASS / N violation(s)
Responsive: desktop-chrome / mobile-iphone / tablet-ipad — all PASS / FAIL on N

Baseline:   .playwright/snapshots/ (in git)
Diff path:  .playwright/output/ (gitignored)

Out of scope

• Lighthouse perf — separate /perf-audit skill.
• Login-protected routes — caller must script auth fixture.
• E2E user-flow tests — separate from regression baseline.

References

• Playwright docs: https://playwright.dev
• axe-core/playwright: https://github.com/dequelabs/axe-core-npm