A UX-engineering harness for AI-generated UI

mkdir ui-harness && cd ui-harness
npm init -y && npm i playwright && npx playwright install chromium

// BASE=http://localhost:3000 URLS=/,/pricing WIDTHS=1440,390 THEMES=light,dark SCROLL=0 node shots.mjs
import { chromium } from "playwright";
import fs from "node:fs";

const BASE = process.env.BASE ?? "http://localhost:3000";
const URLS = (process.env.URLS ?? "/").split(",");
const WIDTHS = (process.env.WIDTHS ?? "1440,390").split(",").map(Number);
const THEMES = (process.env.THEMES ?? "light,dark").split(",");
const SCROLL = Number(process.env.SCROLL ?? 0);
const THEME_INIT = process.env.THEME_INIT ?? "";
fs.mkdirSync("out", { recursive: true });

const browser = await chromium.launch();
for (const theme of THEMES) {
  for (const width of WIDTHS) {
    const ctx = await browser.newContext({
      viewport: { width, height: width < 600 ? 844 : 900 },
      colorScheme: theme,
      isMobile: width < 600,
      hasTouch: width < 600,
    });
    if (THEME_INIT) await ctx.addInitScript(`const THEME = "${theme}"; ${THEME_INIT}`);
    const page = await ctx.newPage();
    for (const path of URLS) {
      await page.goto(BASE + path, { waitUntil: "load", timeout: 60000 });
      await page.waitForTimeout(1200);
      if (SCROLL) { await page.evaluate((y) => window.scrollTo(0, y), SCROLL); await page.waitForTimeout(500); }
      const name = `${path.replace(/\//g, "_") || "_root"}--${width}--${theme}${SCROLL ? "--" + SCROLL : ""}.png`;
      await page.screenshot({ path: `out/${name}` });
      console.log("wrote", name);
    }
    await ctx.close();
  }
}
await browser.close();

// BASE=http://localhost:3000 URLS=/,/pricing node probe.mjs
import { chromium } from "playwright";

const BASE = process.env.BASE ?? "http://localhost:3000";
const URLS = (process.env.URLS ?? "/").split(",");
const THEME_INIT = process.env.THEME_INIT ?? "";

const browser = await chromium.launch();
let total = 0;
for (const path of URLS) {
  const ctx = await browser.newContext({ viewport: { width: 1440, height: 900 } });
  if (THEME_INIT) await ctx.addInitScript(`const THEME = "light"; ${THEME_INIT}`);
  const page = await ctx.newPage();
  const lines = [];
  page.on("console", (m) => { if (m.type() === "error" || m.type() === "warning") lines.push(`${m.type()}: ${m.text().slice(0, 240)}`); });
  page.on("pageerror", (e) => lines.push(`pageerror: ${e.message.slice(0, 240)}`));
  page.on("response", (r) => { if (r.status() >= 400) lines.push(`${r.status()} ${r.url().slice(0, 160)}`); });
  await page.goto(BASE + path, { waitUntil: "networkidle", timeout: 60000 });
  await page.waitForTimeout(1000);
  console.log(`== ${path}${lines.length ? "" : "  clean"}`);
  for (const l of lines) console.log("  " + l);
  total += lines.length;
  await ctx.close();
}
await browser.close();
console.log(total ? `${total} findings` : "all clean");

// BASE=http://localhost:3000 URL=/tools CLICK='a[href*="/tools/shadow"]' SCROLL=0 node frames.mjs
import { chromium } from "playwright";
import fs from "node:fs";

const BASE = process.env.BASE ?? "http://localhost:3000";
const URL_ = process.env.URL ?? "/";
const CLICK = process.env.CLICK;
const SCROLL = Number(process.env.SCROLL ?? 0);
const OFFSETS = (process.env.OFFSETS ?? "80,200,320,460,620,800,1000").split(",").map(Number);
const THEME_INIT = process.env.THEME_INIT ?? "";
if (!CLICK) throw new Error("CLICK selector required");
fs.mkdirSync("out", { recursive: true });

const browser = await chromium.launch();
const ctx = await browser.newContext({ viewport: { width: 1440, height: 900 } });
if (THEME_INIT) await ctx.addInitScript(`const THEME = "light"; ${THEME_INIT}`);
const page = await ctx.newPage();
const errs = [];
page.on("pageerror", (e) => errs.push(e.message.slice(0, 160)));
await page.goto(BASE + URL_, { waitUntil: "networkidle", timeout: 60000 });
if (SCROLL) { await page.evaluate((y) => window.scrollTo(0, y), SCROLL); await page.waitForTimeout(400); }
const el = page.locator(CLICK).first();
await el.hover();
const t0 = Date.now();
await el.click({ noWaitAfter: true });
for (const t of OFFSETS) {
  while (Date.now() - t0 < t) await page.waitForTimeout(5);
  await page.screenshot({ path: `out/frame-${String(t).padStart(4, "0")}.png` });
}
console.log("frames written to out/, ended at", page.url(), errs.length ? "errors: " + errs.join(" | ") : "no errors");
await browser.close();

---
name: ui-harness
description: >-
  Run the UI verification harness after a change: console probe, tells grep,
  screenshots at two widths and two themes, contrast sweep, and motion
  frames when something animates. Load before reporting any UI change as
  done. Not for making the change; run this after it.
---

# UI harness

A UI change is not done when it compiles. It is done when the five checks
have run and been read. This skill runs them in order and reports what they
said, with the image paths, so the person reads pictures and a short list.

## Setup

The harness lives in `<harness path>` with `shots.mjs`, `probe.mjs`,
`sweep.mjs`, `tells.sh` and `frames.mjs`. `BASE` defaults to
`http://localhost:3000`. `THEME_INIT` is the project's theme snippet; read
it from the rules file. If the folder or the snippet is missing, say so and
stop.

## Order

1. **Probe.** `URLS=<touched routes> node probe.mjs`. Anything but clean is
   fixed first; a hydration error invalidates every later check.
2. **Tells.** `sh tells.sh <changed files or folder>`. Each hit is fixed or
   listed under accepted with a reason.
3. **Shots.** `URLS=<touched routes> node shots.mjs`, then again with
   `SCROLL` for anything below the fold. Open every image. Look at 390 wide
   and dark mode as carefully as 1440 light; that is where the failures are.
4. **Sweep.** `URLS=<touched routes> node sweep.mjs`. Failures are fixed by
   moving lightness only, or listed with a reason.
5. **Frames.** Only if the change animates: `URL=<route> CLICK=<selector>
   node frames.mjs`. Read the strip for a gap or a jump.

Fixing something re-runs the checks from step one.

## Reading, not trusting

- Look at the images. Do not describe a screenshot you have not opened.
- A probe line is a finding even when the page renders. A 404 for a font is
  a finding.
- "0 failures" from the sweep means the pairs it checked pass. Samples that
  are meant to fail (colour demos) are accepted exceptions, not passes.
- If a check could not run (server down, missing script), report it as not
  run. Never as passed.

## Report

- What changed, in one line.
- Per check: clean, or the findings, or not run and why.
- Image paths, grouped by route.
- What you fixed on the way, and what you left for the user to decide.

## Never

- Never report a UI change done without the probe and the shots.
- Never judge a stylesheet change on a dev server that has not been
  restarted since the edit.
- Never fix a finding that changes design intent (a colour, a layout)
  without asking. Mechanical fixes (a missing key, a literal that has a
  token) are fine to make and report.
- Never run the sweep or shots across the whole site for a one-route change.