From c9ea5b093ef329fac1c08d0660b359c735d449c3 Mon Sep 17 00:00:00 2001
From: drepkovsky <dominik.repkovsky@gmail.com>
Date: Sat, 13 Jun 2026 23:17:56 +0200
Subject: [PATCH 1/2] Add agent-board-design-qa skill

Measure-don't-perceive design QA for implemented web UIs: a portable DOM geometry scanner (overflow, truncation, collapse, sibling overlap, near-miss misalignment, tap-target, input-font) injected through whatever browser/preview capability the harness already exposes, plus a layered method (token conformance, axe-core, reference diff, vision-judge-last). Pairs with agent-board-design-review (which reviews the mockup).

Wired into skills.ts, skills-audit.ts (drift audit), workspace.ts (BUNDLED_SKILLS + materialization) and the router; installable via 'agent-board skills install'.

Scanner hardened by dogfooding on the agent-board web viewer: read viewport from documentElement.clientWidth with a zero guard, report only the outermost overflowing element, skip SVG internals, and ignore native <select> content-overflow.
---
 docs/internal/design-qa-skill.md | 173 +++++++++++++++++++++++++++++++
 src/skills-audit.ts              |   4 +
 src/skills.ts                    | 150 +++++++++++++++++++++++++++
 src/workspace.ts                 |   8 ++
 test/cli.test.ts                 |   1 +
 5 files changed, 336 insertions(+)
 create mode 100644 docs/internal/design-qa-skill.md

diff --git a/docs/internal/design-qa-skill.md b/docs/internal/design-qa-skill.md
new file mode 100644
index 0000000..c9a7e35
--- /dev/null
+++ b/docs/internal/design-qa-skill.md
@@ -0,0 +1,173 @@
+# DRAFT — `agent-board-design-qa` skill
+
+> Internal RFC / review artifact. `docs/internal/` is not shipped to npm
+> (`files: ["src","docs/*.md"]` is non-recursive) and is excluded from the skill
+> drift audit. This file is the human-readable source of truth for the skill
+> text; it is ported into `src/skills.ts` by a one-shot script (extracting the
+> `SKILL_START`/`AGENTS_START` marker blocks), then registered in
+> `src/skills-audit.ts` and materialized in `src/workspace.ts`.
+>
+> Design contract (decided with the user):
+> - Phase 1 lives as an agent-board skill; the stable measurement primitive is
+>   extracted into qprobe later, after dogfooding.
+> - Reuse whatever browser/preview capability the harness already exposes
+>   (Claude Code `preview_*`, Codex, qprobe, Playwright). This skill is the
+>   missing *framework*, not new browser infrastructure.
+> - HOW (method/thresholds) is shared; WHAT (tokens/breakpoints/components) is
+>   read per-repo on the spot; MEASURE is a dumb reused capability.
+> - A reference is just an image in — no baked-in Figma engine.
+
+## SKILL.md
+
+<!-- SKILL_START -->
+---
+name: agent-board-design-qa
+description: "QA the IMPLEMENTED, running web UI by MEASURING it, not eyeballing screenshots: catch wrapped text, off-center button labels, misalignment, off-token shadows/spacing, low contrast, and — when a reference exists — pixel-fidelity drift. Reuses the harness's own preview/browser tools and adds the missing framework. Use after implementing or changing UI, for pixel-perfect / 1:1 work, or when asked whether a design 'looks right'. Pairs with agent-board-design-review (which reviews the mockup). Triggers: design qa, visual qa, pixel-perfect, 1:1, does this look right, polish the UI, fix the layout, text wrapping, misalignment, off-center, contrast, design tokens, visual check."
+---
+
+# Agent Board · Design QA
+
+Use this skill to QA the IMPLEMENTED, running web UI — the design analog of running the tests, not reading them. You MEASURE the rendered page and fix in code; the screenshot is your proof, never your judge. This is the post-implementation gate that pairs with `agent-board-design-review` (which critiques the mockup before code).
+
+## Measure, don't perceive
+
+A screenshot that "looks fine" is the trap. Vision models downsample every image to a fixed budget, so a 2px misalignment, a silently truncated label, an off-token shadow, or a slightly off-center button vanish before the model ever sees them — frontier models score under 50% on fine-grained visual perception versus ~96% for humans. So do not judge quality by looking. Derive findings from the DOM and CSSOM, where the numbers are exact, and reserve the screenshot for evidence and for the small residual that genuinely resists measurement.
+
+Split of responsibility:
+
+- HOW (this skill): the method, the thresholds, the layer order, the finding format. Portable across repos.
+- WHAT (the repo): the design system — spacing scale, color/radius/shadow tokens, breakpoints, component library. Read it from THIS repo every run; generic thresholds are only the floor.
+- MEASURE (a dumb capability): open the page, eval JS, screenshot. Reused from your harness — never rebuilt here.
+
+## Capability contract (works on any harness)
+
+This skill needs three capabilities from whatever harness you are on — Claude Code, Codex, qprobe, raw Playwright. Bind each to the tool yours exposes; do not build new browser infrastructure:
+
+1. Eval JS in the page — Claude Code `preview_eval`, qprobe `qprobe browser eval`, Playwright `page.evaluate`.
+2. Screenshot — `preview_screenshot`, `qprobe browser screenshot`.
+3. Set the viewport — `preview_resize`, `qprobe browser resize`.
+
+If none is available, wiring one up is the first step; the rest of the loop assumes these three.
+
+## Loop
+
+1. Target. Read the task and its spec: `agent-board show <task-id>`, then `agent-board spec cat <spec-id>`. Note the required screens, states, and breakpoints. If a visual reference exists (a mockup via `agent-board web`, a Figma export, or a screenshot), keep its image for step 7 — the reference is just an image; where it comes from is your call.
+2. Read this repo's design system. Find the token source (Tailwind/theme config, CSS custom properties, the component library) and extract the spacing scale, the color/radius/shadow tokens, and the real breakpoints. These are the WHAT you measure against.
+3. Render at the repo's real breakpoints (its own `sm`/`md`/`lg`, not invented numbers). Set the viewport, load the page, let it settle.
+4. Measure (deterministic, no vision). Inject the scan below via your eval capability, at each breakpoint. It returns located, measured findings: horizontal overflow, clipped/overflowing content, silently truncated text, collapsed (zero-height) content, sibling overlap, near-miss misalignment, tiny tap targets, sub-16px input fonts.
+5. Token conformance. Snapshot computed styles (color, background-color, border-color, box-shadow, border-radius, gap, padding, margin) across the visible tree and flag any value not in the repo's token set — off-token colors, off-grid spacing, magic-number shadows/radii. This is where an "ugly shadow" usually lives: a one-off blur nobody chose.
+6. Contrast and a11y heuristics. Inject axe-core from a CDN and run it; surface color-contrast, accessible-name, and target-size violations. Low contrast is a real "looks cheap" signal, not just an a11y nit.
+7. Reference diff — only when a reference image exists. Screenshot the page at the reference's viewport and diff it: a perceptual pixel diff (pixelmatch / odiff / Playwright `toHaveScreenshot`, YIQ + anti-aliasing on, threshold ~0.2) for drift, plus an onion-skin overlay (reference at 50% opacity over the screenshot) for alignment — misalignment shows up as ghosting. This is the 1:1 layer.
+8. Vision LAST, residual only. For what truly resists measurement — an ugly shadow that passed the token check, optical (not mathematical) alignment, overall balance — screenshot a CROP of that region (never the full page; crops keep the detail the downsampler destroys) and judge it against a short, explicit rubric. The verdict is advisory: it may add a finding, never overturn a measured one.
+9. Fix in code, then re-run from step 3 until the measured layers are clean. You are fixing real located defects, not chasing a vibe. Attach the final screenshot as proof.
+10. Record on the board. Blocking defects become tasks: `agent-board new "<fix>" --status ready`. Reusable traps become knowledge: `agent-board knowledge add "<gotcha>" --kind gotcha --category design`. Tie them to the spec with `agent-board link <task-id> --spec <spec-id>`.
+
+## The scan (the one portable primitive)
+
+A dumb measurer: it returns numbers, it does not judge. Inject it with your eval capability at each breakpoint; it returns an array of findings. Tune the magic numbers (spacing base, min tap target) to the repo's tokens in step 2, and scope `document.body` to a container on large pages.
+
+```js
+(function () {
+  var vw = document.documentElement.clientWidth || window.innerWidth;
+  if (!vw) return [{ layer: "meta", severity: "warn", selector: "html", viewport: 0, prop: "viewport", measured: "0", expected: "> 0", message: "viewport width is 0 - page not laid out yet; retry after load" }];
+  var out = [];
+  function sel(el) {
+    if (el.id) return "#" + el.id;
+    var parts = [], n = el, depth = 0;
+    while (n && n.nodeType === 1 && depth < 4) {
+      var p = n.tagName.toLowerCase();
+      if (n.classList && n.classList.length) p += "." + Array.prototype.slice.call(n.classList, 0, 2).join(".");
+      parts.unshift(p);
+      n = n.parentElement; depth++;
+    }
+    return parts.join(" > ");
+  }
+  function visible(el) {
+    var r = el.getBoundingClientRect(), s = getComputedStyle(el);
+    return r.width > 0 && r.height > 0 && s.visibility !== "hidden" && s.display !== "none" && parseFloat(s.opacity) > 0 && !el.ownerSVGElement;
+  }
+  function add(layer, sev, el, prop, measured, expected, msg) {
+    out.push({ layer: layer, severity: sev, selector: sel(el), viewport: vw, prop: prop, measured: measured, expected: expected, message: msg });
+  }
+  var all = Array.prototype.slice.call(document.body.querySelectorAll("*")).filter(visible);
+  for (var i = 0; i < all.length; i++) {
+    var el = all[i], r = el.getBoundingClientRect(), s = getComputedStyle(el);
+    var tag = el.tagName.toLowerCase();
+    var parentOver = el.parentElement && el.parentElement.getBoundingClientRect().right > vw + 2;
+    if (r.right > vw + 2 && !parentOver) add("geometry", "blocking", el, "right", Math.round(r.right) + "px", "<= " + vw + "px", "extends " + Math.round(r.right - vw) + "px past the viewport (horizontal overflow)");
+    if (el.scrollWidth > el.clientWidth + 1 && s.overflowX !== "auto" && s.overflowX !== "scroll" && tag !== "select") add("geometry", "warn", el, "scrollWidth", el.scrollWidth + "px", "<= " + el.clientWidth + "px", "content overflows its box by " + (el.scrollWidth - el.clientWidth) + "px");
+    if (s.textOverflow === "ellipsis" && el.scrollWidth > el.clientWidth + 1 && !el.title && !el.getAttribute("aria-label")) add("geometry", "warn", el, "text", "truncated", "title or aria-label", "ellipsis-truncated text with no title/aria-label");
+    if (el.children.length === 0 && (el.textContent || "").trim().length > 0 && r.height < 1) add("geometry", "warn", el, "height", Math.round(r.height) + "px", "> 0", "has text but renders at zero height (collapsed)");
+    var interactive = (tag === "a" || tag === "button" || tag === "select" || tag === "textarea") || el.getAttribute("role") === "button" || (tag === "input" && el.type !== "hidden");
+    if (interactive && (r.width < 44 || r.height < 44)) add("a11y", "warn", el, "size", Math.round(r.width) + "x" + Math.round(r.height), ">= 44x44", "tap target smaller than 44x44");
+    if ((tag === "input" || tag === "textarea" || tag === "select") && parseFloat(s.fontSize) < 16) add("a11y", "polish", el, "fontSize", s.fontSize, ">= 16px", "input font under 16px (causes mobile zoom-on-focus)");
+  }
+  var parents = all.filter(function (p) { return p.children.length > 1; });
+  for (var j = 0; j < parents.length; j++) {
+    var kids = Array.prototype.filter.call(parents[j].children, visible);
+    if (kids.length < 2) continue;
+    var lefts = kids.map(function (k) { return Math.round(k.getBoundingClientRect().left); });
+    var counts = {};
+    lefts.forEach(function (v) { counts[v] = (counts[v] || 0) + 1; });
+    var dom = null, best = 0;
+    for (var key in counts) { if (counts[key] > best) { best = counts[key]; dom = parseInt(key, 10); } }
+    if (dom !== null && best >= 2) {
+      for (var a = 0; a < kids.length; a++) {
+        var d = lefts[a] - dom;
+        if (d !== 0 && Math.abs(d) <= 4) add("geometry", "warn", kids[a], "left", lefts[a] + "px", dom + "px", "left edge off by " + d + "px from its siblings (near-miss misalignment)");
+      }
+    }
+    for (var x = 0; x < kids.length; x++) {
+      for (var y = x + 1; y < kids.length; y++) {
+        var ra = kids[x].getBoundingClientRect(), rb = kids[y].getBoundingClientRect();
+        var ox = Math.min(ra.right, rb.right) - Math.max(ra.left, rb.left);
+        var oy = Math.min(ra.bottom, rb.bottom) - Math.max(ra.top, rb.top);
+        if (ox > 2 && oy > 2) add("geometry", "warn", kids[y], "overlap", Math.round(ox) + "x" + Math.round(oy) + "px", "no overlap", "overlaps a sibling by " + Math.round(ox) + "x" + Math.round(oy) + "px");
+      }
+    }
+  }
+  return out.slice(0, 200);
+})()
+```
+
+Hardening (learned from dogfooding the scanner on a real board UI): read the viewport from document.documentElement.clientWidth and bail if it is 0 (the eval context may not be laid out yet, which otherwise flags every element as overflowing); report only the OUTERMOST overflowing element, not every descendant of it; skip elements inside an svg (ownerSVGElement), whose internal paths/shapes are geometry not layout and produce pure noise; ignore native select content-overflow (it clips option text by design). Detect overlap by pairwise rect intersection of siblings, NOT by comparing a parent's area to the sum of its children's areas — the area method is unsound and gives false positives.
+
+## Finding format
+
+Every layer — scan, tokens, a11y, diff, vision — emits the same shape so findings sort and act uniformly:
+
+`{ layer, severity, selector, viewport, prop, measured, expected, message, fix }`
+
+- `layer`: geometry | tokens | a11y | diff | vision
+- `severity`: blocking | warn | polish
+- `selector`: a click-to-find CSS path
+- `measured` / `expected`: the numbers (e.g. measured "blur 17px", expected "one of 0/1/2/4/8/16")
+- `fix`: the concrete code change
+
+## Output
+
+A verdict per breakpoint, then an ordered list of findings (blocking first, polish last). Each names the selector, the viewport, the measured value, the rule it breaks, and a fix. Close with residual risk and the layers you did not run (no reference, vision skipped, etc.).
+
+## Don't
+
+- Don't eyeball a screenshot and call it reviewed — that is the exact failure this skill exists to fix.
+- Don't assert exact pixels or colors from a downsampled screenshot; read them from the DOM/CSSOM.
+- Don't invent thresholds the repo's tokens already define; the token set is the truth, generic numbers are the floor.
+- Don't let the vision judge overturn a measured finding; it is advisory, runs on crops, and runs last.
+- Don't build new browser infrastructure; bind to the harness's preview/browser tools.
+- Don't bake in a Figma engine; a reference is just an image in.
+<!-- SKILL_END -->
+
+## AGENTS.md
+
+<!-- AGENTS_START -->
+# Agent Board Design QA Rules
+
+- QA the IMPLEMENTED running UI by MEASURING it; never judge quality from a screenshot — vision misses 2px misalignment, silent truncation, and off-token shadows.
+- Reuse the harness's own browser tools (Claude Code `preview_*`, qprobe `browser`, Playwright); do not build new browser infrastructure.
+- HOW is this skill (method, thresholds, layer order); WHAT is the repo (tokens, breakpoints, components) — read the design system every run and measure against it.
+- Layer order: DOM geometry scan -> token conformance -> axe-core contrast/a11y -> reference pixel-diff + overlay (only when a reference image exists) -> vision judge LAST, on crops, advisory only.
+- A reference is just an image in (Figma export/MCP or a mockup screenshot); no baked-in Figma engine.
+- Fix in code and re-run until the measured layers are clean; the screenshot is proof, not the judge.
+- Record blocking defects as tasks (`agent-board new`) and reusable traps as knowledge (`agent-board knowledge add --kind gotcha --category design`); link findings to the spec.
+<!-- AGENTS_END -->
diff --git a/src/skills-audit.ts b/src/skills-audit.ts
index 7ae56ca..7026c35 100644
--- a/src/skills-audit.ts
+++ b/src/skills-audit.ts
@@ -6,6 +6,8 @@ import {
 	bootstrapSkillAgents,
 	bootstrapSkillReadme,
 	configSkillReadme,
+	designQaSkillAgents,
+	designQaSkillReadme,
 	designReviewSkillAgents,
 	designReviewSkillReadme,
 	designWireframeSkillAgents,
@@ -74,6 +76,8 @@ const SKILL_DOCS: ReadonlyArray<{ source: string; text: string }> = [
 	{ source: "agent-board-design-wireframe/AGENTS.md", text: designWireframeSkillAgents },
 	{ source: "agent-board-design-review/SKILL.md", text: designReviewSkillReadme },
 	{ source: "agent-board-design-review/AGENTS.md", text: designReviewSkillAgents },
+	{ source: "agent-board-design-qa/SKILL.md", text: designQaSkillReadme },
+	{ source: "agent-board-design-qa/AGENTS.md", text: designQaSkillAgents },
 	{ source: "references/config.md", text: configSkillReadme },
 	{ source: "references/organization.md", text: organizationReference },
 	{ source: "references/task-workflow.md", text: taskWorkflowReference },
diff --git a/src/skills.ts b/src/skills.ts
index 62e1491..21229b0 100644
--- a/src/skills.ts
+++ b/src/skills.ts
@@ -20,6 +20,7 @@ Use when controlling agent-board work. This is the router/controller skill: choo
 - Unknown repo, feasibility, current docs, or facts likely to change -> \`agent-board-research\`.
 - Turning intent into specs, tasks, dependencies, and verify blocks -> \`agent-board-spec\`.
 - Frontend/product implementation with screens or UX -> \`agent-board-design-wireframe\`, then \`agent-board-design-review\`, before implementation.
+- Visual QA of the IMPLEMENTED running UI (pixel-perfect / 1:1, layout / contrast / spacing defects) -> \`agent-board-design-qa\`.
 - User-facing behavior, TDD, use cases, e2e scenarios, regression protection, or safe workflow -> \`agent-board-safe-workflow\`.
 - Multi-agent execution, review waves, or closed loops -> \`agent-board-flow\`.
 - One concrete implementation task -> \`agent-board-implement\` (legacy alias: \`agent-board-worker\`).
@@ -871,3 +872,152 @@ export const designReviewSkillAgents = `# Agent Board Design Review Rules
 - Critique spec coverage, flow integrity, visual-system consistency, honesty of placeholders, and platform fit.
 - Record concrete, spec-linked follow-ups (\`agent-board new\`, \`agent-board knowledge add\`); blocking gaps before polish.
 `;
+
+export const designQaSkillReadme = `---
+name: agent-board-design-qa
+description: "QA the IMPLEMENTED, running web UI by MEASURING it, not eyeballing screenshots: catch wrapped text, off-center button labels, misalignment, off-token shadows/spacing, low contrast, and — when a reference exists — pixel-fidelity drift. Reuses the harness's own preview/browser tools and adds the missing framework. Use after implementing or changing UI, for pixel-perfect / 1:1 work, or when asked whether a design 'looks right'. Pairs with agent-board-design-review (which reviews the mockup). Triggers: design qa, visual qa, pixel-perfect, 1:1, does this look right, polish the UI, fix the layout, text wrapping, misalignment, off-center, contrast, design tokens, visual check."
+---
+
+# Agent Board · Design QA
+
+Use this skill to QA the IMPLEMENTED, running web UI — the design analog of running the tests, not reading them. You MEASURE the rendered page and fix in code; the screenshot is your proof, never your judge. This is the post-implementation gate that pairs with \`agent-board-design-review\` (which critiques the mockup before code).
+
+## Measure, don't perceive
+
+A screenshot that "looks fine" is the trap. Vision models downsample every image to a fixed budget, so a 2px misalignment, a silently truncated label, an off-token shadow, or a slightly off-center button vanish before the model ever sees them — frontier models score under 50% on fine-grained visual perception versus ~96% for humans. So do not judge quality by looking. Derive findings from the DOM and CSSOM, where the numbers are exact, and reserve the screenshot for evidence and for the small residual that genuinely resists measurement.
+
+Split of responsibility:
+
+- HOW (this skill): the method, the thresholds, the layer order, the finding format. Portable across repos.
+- WHAT (the repo): the design system — spacing scale, color/radius/shadow tokens, breakpoints, component library. Read it from THIS repo every run; generic thresholds are only the floor.
+- MEASURE (a dumb capability): open the page, eval JS, screenshot. Reused from your harness — never rebuilt here.
+
+## Capability contract (works on any harness)
+
+This skill needs three capabilities from whatever harness you are on — Claude Code, Codex, qprobe, raw Playwright. Bind each to the tool yours exposes; do not build new browser infrastructure:
+
+1. Eval JS in the page — Claude Code \`preview_eval\`, qprobe \`qprobe browser eval\`, Playwright \`page.evaluate\`.
+2. Screenshot — \`preview_screenshot\`, \`qprobe browser screenshot\`.
+3. Set the viewport — \`preview_resize\`, \`qprobe browser resize\`.
+
+If none is available, wiring one up is the first step; the rest of the loop assumes these three.
+
+## Loop
+
+1. Target. Read the task and its spec: \`agent-board show <task-id>\`, then \`agent-board spec cat <spec-id>\`. Note the required screens, states, and breakpoints. If a visual reference exists (a mockup via \`agent-board web\`, a Figma export, or a screenshot), keep its image for step 7 — the reference is just an image; where it comes from is your call.
+2. Read this repo's design system. Find the token source (Tailwind/theme config, CSS custom properties, the component library) and extract the spacing scale, the color/radius/shadow tokens, and the real breakpoints. These are the WHAT you measure against.
+3. Render at the repo's real breakpoints (its own \`sm\`/\`md\`/\`lg\`, not invented numbers). Set the viewport, load the page, let it settle.
+4. Measure (deterministic, no vision). Inject the scan below via your eval capability, at each breakpoint. It returns located, measured findings: horizontal overflow, clipped/overflowing content, silently truncated text, collapsed (zero-height) content, sibling overlap, near-miss misalignment, tiny tap targets, sub-16px input fonts.
+5. Token conformance. Snapshot computed styles (color, background-color, border-color, box-shadow, border-radius, gap, padding, margin) across the visible tree and flag any value not in the repo's token set — off-token colors, off-grid spacing, magic-number shadows/radii. This is where an "ugly shadow" usually lives: a one-off blur nobody chose.
+6. Contrast and a11y heuristics. Inject axe-core from a CDN and run it; surface color-contrast, accessible-name, and target-size violations. Low contrast is a real "looks cheap" signal, not just an a11y nit.
+7. Reference diff — only when a reference image exists. Screenshot the page at the reference's viewport and diff it: a perceptual pixel diff (pixelmatch / odiff / Playwright \`toHaveScreenshot\`, YIQ + anti-aliasing on, threshold ~0.2) for drift, plus an onion-skin overlay (reference at 50% opacity over the screenshot) for alignment — misalignment shows up as ghosting. This is the 1:1 layer.
+8. Vision LAST, residual only. For what truly resists measurement — an ugly shadow that passed the token check, optical (not mathematical) alignment, overall balance — screenshot a CROP of that region (never the full page; crops keep the detail the downsampler destroys) and judge it against a short, explicit rubric. The verdict is advisory: it may add a finding, never overturn a measured one.
+9. Fix in code, then re-run from step 3 until the measured layers are clean. You are fixing real located defects, not chasing a vibe. Attach the final screenshot as proof.
+10. Record on the board. Blocking defects become tasks: \`agent-board new "<fix>" --status ready\`. Reusable traps become knowledge: \`agent-board knowledge add "<gotcha>" --kind gotcha --category design\`. Tie them to the spec with \`agent-board link <task-id> --spec <spec-id>\`.
+
+## The scan (the one portable primitive)
+
+A dumb measurer: it returns numbers, it does not judge. Inject it with your eval capability at each breakpoint; it returns an array of findings. Tune the magic numbers (spacing base, min tap target) to the repo's tokens in step 2, and scope \`document.body\` to a container on large pages.
+
+\`\`\`js
+(function () {
+  var vw = document.documentElement.clientWidth || window.innerWidth;
+  if (!vw) return [{ layer: "meta", severity: "warn", selector: "html", viewport: 0, prop: "viewport", measured: "0", expected: "> 0", message: "viewport width is 0 - page not laid out yet; retry after load" }];
+  var out = [];
+  function sel(el) {
+    if (el.id) return "#" + el.id;
+    var parts = [], n = el, depth = 0;
+    while (n && n.nodeType === 1 && depth < 4) {
+      var p = n.tagName.toLowerCase();
+      if (n.classList && n.classList.length) p += "." + Array.prototype.slice.call(n.classList, 0, 2).join(".");
+      parts.unshift(p);
+      n = n.parentElement; depth++;
+    }
+    return parts.join(" > ");
+  }
+  function visible(el) {
+    var r = el.getBoundingClientRect(), s = getComputedStyle(el);
+    return r.width > 0 && r.height > 0 && s.visibility !== "hidden" && s.display !== "none" && parseFloat(s.opacity) > 0 && !el.ownerSVGElement;
+  }
+  function add(layer, sev, el, prop, measured, expected, msg) {
+    out.push({ layer: layer, severity: sev, selector: sel(el), viewport: vw, prop: prop, measured: measured, expected: expected, message: msg });
+  }
+  var all = Array.prototype.slice.call(document.body.querySelectorAll("*")).filter(visible);
+  for (var i = 0; i < all.length; i++) {
+    var el = all[i], r = el.getBoundingClientRect(), s = getComputedStyle(el);
+    var tag = el.tagName.toLowerCase();
+    var parentOver = el.parentElement && el.parentElement.getBoundingClientRect().right > vw + 2;
+    if (r.right > vw + 2 && !parentOver) add("geometry", "blocking", el, "right", Math.round(r.right) + "px", "<= " + vw + "px", "extends " + Math.round(r.right - vw) + "px past the viewport (horizontal overflow)");
+    if (el.scrollWidth > el.clientWidth + 1 && s.overflowX !== "auto" && s.overflowX !== "scroll" && tag !== "select") add("geometry", "warn", el, "scrollWidth", el.scrollWidth + "px", "<= " + el.clientWidth + "px", "content overflows its box by " + (el.scrollWidth - el.clientWidth) + "px");
+    if (s.textOverflow === "ellipsis" && el.scrollWidth > el.clientWidth + 1 && !el.title && !el.getAttribute("aria-label")) add("geometry", "warn", el, "text", "truncated", "title or aria-label", "ellipsis-truncated text with no title/aria-label");
+    if (el.children.length === 0 && (el.textContent || "").trim().length > 0 && r.height < 1) add("geometry", "warn", el, "height", Math.round(r.height) + "px", "> 0", "has text but renders at zero height (collapsed)");
+    var interactive = (tag === "a" || tag === "button" || tag === "select" || tag === "textarea") || el.getAttribute("role") === "button" || (tag === "input" && el.type !== "hidden");
+    if (interactive && (r.width < 44 || r.height < 44)) add("a11y", "warn", el, "size", Math.round(r.width) + "x" + Math.round(r.height), ">= 44x44", "tap target smaller than 44x44");
+    if ((tag === "input" || tag === "textarea" || tag === "select") && parseFloat(s.fontSize) < 16) add("a11y", "polish", el, "fontSize", s.fontSize, ">= 16px", "input font under 16px (causes mobile zoom-on-focus)");
+  }
+  var parents = all.filter(function (p) { return p.children.length > 1; });
+  for (var j = 0; j < parents.length; j++) {
+    var kids = Array.prototype.filter.call(parents[j].children, visible);
+    if (kids.length < 2) continue;
+    var lefts = kids.map(function (k) { return Math.round(k.getBoundingClientRect().left); });
+    var counts = {};
+    lefts.forEach(function (v) { counts[v] = (counts[v] || 0) + 1; });
+    var dom = null, best = 0;
+    for (var key in counts) { if (counts[key] > best) { best = counts[key]; dom = parseInt(key, 10); } }
+    if (dom !== null && best >= 2) {
+      for (var a = 0; a < kids.length; a++) {
+        var d = lefts[a] - dom;
+        if (d !== 0 && Math.abs(d) <= 4) add("geometry", "warn", kids[a], "left", lefts[a] + "px", dom + "px", "left edge off by " + d + "px from its siblings (near-miss misalignment)");
+      }
+    }
+    for (var x = 0; x < kids.length; x++) {
+      for (var y = x + 1; y < kids.length; y++) {
+        var ra = kids[x].getBoundingClientRect(), rb = kids[y].getBoundingClientRect();
+        var ox = Math.min(ra.right, rb.right) - Math.max(ra.left, rb.left);
+        var oy = Math.min(ra.bottom, rb.bottom) - Math.max(ra.top, rb.top);
+        if (ox > 2 && oy > 2) add("geometry", "warn", kids[y], "overlap", Math.round(ox) + "x" + Math.round(oy) + "px", "no overlap", "overlaps a sibling by " + Math.round(ox) + "x" + Math.round(oy) + "px");
+      }
+    }
+  }
+  return out.slice(0, 200);
+})()
+\`\`\`
+
+Hardening (learned from dogfooding the scanner on a real board UI): read the viewport from document.documentElement.clientWidth and bail if it is 0 (the eval context may not be laid out yet, which otherwise flags every element as overflowing); report only the OUTERMOST overflowing element, not every descendant of it; skip elements inside an svg (ownerSVGElement), whose internal paths/shapes are geometry not layout and produce pure noise; ignore native select content-overflow (it clips option text by design). Detect overlap by pairwise rect intersection of siblings, NOT by comparing a parent's area to the sum of its children's areas — the area method is unsound and gives false positives.
+
+## Finding format
+
+Every layer — scan, tokens, a11y, diff, vision — emits the same shape so findings sort and act uniformly:
+
+\`{ layer, severity, selector, viewport, prop, measured, expected, message, fix }\`
+
+- \`layer\`: geometry | tokens | a11y | diff | vision
+- \`severity\`: blocking | warn | polish
+- \`selector\`: a click-to-find CSS path
+- \`measured\` / \`expected\`: the numbers (e.g. measured "blur 17px", expected "one of 0/1/2/4/8/16")
+- \`fix\`: the concrete code change
+
+## Output
+
+A verdict per breakpoint, then an ordered list of findings (blocking first, polish last). Each names the selector, the viewport, the measured value, the rule it breaks, and a fix. Close with residual risk and the layers you did not run (no reference, vision skipped, etc.).
+
+## Don't
+
+- Don't eyeball a screenshot and call it reviewed — that is the exact failure this skill exists to fix.
+- Don't assert exact pixels or colors from a downsampled screenshot; read them from the DOM/CSSOM.
+- Don't invent thresholds the repo's tokens already define; the token set is the truth, generic numbers are the floor.
+- Don't let the vision judge overturn a measured finding; it is advisory, runs on crops, and runs last.
+- Don't build new browser infrastructure; bind to the harness's preview/browser tools.
+- Don't bake in a Figma engine; a reference is just an image in.
+`;
+
+export const designQaSkillAgents = `# Agent Board Design QA Rules
+
+- QA the IMPLEMENTED running UI by MEASURING it; never judge quality from a screenshot — vision misses 2px misalignment, silent truncation, and off-token shadows.
+- Reuse the harness's own browser tools (Claude Code \`preview_*\`, qprobe \`browser\`, Playwright); do not build new browser infrastructure.
+- HOW is this skill (method, thresholds, layer order); WHAT is the repo (tokens, breakpoints, components) — read the design system every run and measure against it.
+- Layer order: DOM geometry scan -> token conformance -> axe-core contrast/a11y -> reference pixel-diff + overlay (only when a reference image exists) -> vision judge LAST, on crops, advisory only.
+- A reference is just an image in (Figma export/MCP or a mockup screenshot); no baked-in Figma engine.
+- Fix in code and re-run until the measured layers are clean; the screenshot is proof, not the judge.
+- Record blocking defects as tasks (\`agent-board new\`) and reusable traps as knowledge (\`agent-board knowledge add --kind gotcha --category design\`); link findings to the spec.
+`;
diff --git a/src/workspace.ts b/src/workspace.ts
index c650d9f..99444e7 100644
--- a/src/workspace.ts
+++ b/src/workspace.ts
@@ -10,6 +10,8 @@ import {
 	bootstrapSkillAgents,
 	bootstrapSkillReadme,
 	configSkillReadme,
+	designQaSkillAgents,
+	designQaSkillReadme,
 	designReviewSkillAgents,
 	designReviewSkillReadme,
 	designWireframeSkillAgents,
@@ -56,6 +58,7 @@ const LOCAL_GITIGNORE = [
 export const BUNDLED_SKILLS = [
 	"agent-board",
 	"agent-board-bootstrap",
+	"agent-board-design-qa",
 	"agent-board-design-review",
 	"agent-board-design-wireframe",
 	"agent-board-flow",
@@ -727,6 +730,11 @@ async function installBundledSkills(root: string): Promise<void> {
 	await ensureDir(designReviewRoot);
 	await writeBundledSkill(join(designReviewRoot, "SKILL.md"), designReviewSkillReadme);
 	await writeBundledSkill(join(designReviewRoot, "AGENTS.md"), designReviewSkillAgents);
+
+	const designQaRoot = join(root, "skills", "agent-board-design-qa");
+	await ensureDir(designQaRoot);
+	await writeBundledSkill(join(designQaRoot, "SKILL.md"), designQaSkillReadme);
+	await writeBundledSkill(join(designQaRoot, "AGENTS.md"), designQaSkillAgents);
 }
 
 async function readProjectConfig(projectPath: string): Promise<ProjectConfig> {
diff --git a/test/cli.test.ts b/test/cli.test.ts
index 9e9c442..f311251 100644
--- a/test/cli.test.ts
+++ b/test/cli.test.ts
@@ -25,6 +25,7 @@ describe("cli", () => {
 		expect((await readdir(join(home, "skills"))).sort()).toEqual([
 			"agent-board",
 			"agent-board-bootstrap",
+			"agent-board-design-qa",
 			"agent-board-design-review",
 			"agent-board-design-wireframe",
 			"agent-board-flow",

From e14f319ed67e997708c1ab6e531875706bb31ee5 Mon Sep 17 00:00:00 2001
From: drepkovsky <dominik.repkovsky@gmail.com>
Date: Sun, 14 Jun 2026 12:58:01 +0200
Subject: [PATCH 2/2] Document agent-board-design-qa (README, CHANGELOG, skill
 list, concepts tree)

README: add agent-board-design-qa to the three skills-install path lists, bump the bundled count to thirteen, add a description bullet, and update the design pair -> trio note. CHANGELOG: Unreleased entry. configSkillReadme path list and docs/concepts.md skills tree: add the new skill.
---
 CHANGELOG.md     |  2 ++
 README.md        | 11 ++++++-----
 docs/concepts.md |  1 +
 src/skills.ts    |  2 +-
 4 files changed, 10 insertions(+), 6 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 1ee0352..d000ce5 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -4,6 +4,8 @@ Notable changes to `@questpie/agent-board` (CLI binaries: `agent-board`, `agent`
 
 ## Unreleased
 
+- **Design QA skill**: `agent-board-design-qa` QAs the implemented, running web UI by measuring it instead of eyeballing a screenshot. A portable DOM geometry scan (overflow, silent truncation, collapse, sibling overlap, near-miss misalignment, small tap targets, sub-16px input fonts) runs through whatever browser/preview capability the harness already exposes (Claude Code `preview_*`, Codex, qprobe, Playwright), layered with design-token conformance, axe-core contrast, an optional reference pixel-diff + overlay, and a vision judge reserved for the residual. `agent-board skills install` links it alongside the existing twelve. Pairs with `agent-board-design-review` (which reviews the mockup).
+
 ## 0.5.0 — 2026-06-11
 
 - **Design skills**: two new bundled skills — `agent-board-design-wireframe` authors an HTML-mockup wireframe (zero-build React-UMD + Babel, a window-globals design kit, a Figma-like canvas of device-sized artboards), and `agent-board-design-review` gives a read-only, spec-linked critique of one. `agent-board skills install` links both into the Claude/agents/Cursor runtimes alongside the existing three, so the same agent that holds the specs can prototype UI as HTML mockups.
diff --git a/README.md b/README.md
index ba8079b..5e7ea92 100644
--- a/README.md
+++ b/README.md
@@ -44,9 +44,9 @@ agent-board skills install
 `agent-board skills install` links the bundled skills into supported local runtimes:
 
 ```txt
-~/.claude/skills/{agent-board,agent-board-bootstrap,agent-board-research,agent-board-spec,agent-board-safe-workflow,agent-board-flow,agent-board-implement,agent-board-worker,agent-board-grill,agent-board-maintenance,agent-board-design-wireframe,agent-board-design-review}
-~/.agents/skills/{agent-board,agent-board-bootstrap,agent-board-research,agent-board-spec,agent-board-safe-workflow,agent-board-flow,agent-board-implement,agent-board-worker,agent-board-grill,agent-board-maintenance,agent-board-design-wireframe,agent-board-design-review}
-~/.cursor/skills/{agent-board,agent-board-bootstrap,agent-board-research,agent-board-spec,agent-board-safe-workflow,agent-board-flow,agent-board-implement,agent-board-worker,agent-board-grill,agent-board-maintenance,agent-board-design-wireframe,agent-board-design-review}
+~/.claude/skills/{agent-board,agent-board-bootstrap,agent-board-research,agent-board-spec,agent-board-safe-workflow,agent-board-flow,agent-board-implement,agent-board-worker,agent-board-grill,agent-board-maintenance,agent-board-design-wireframe,agent-board-design-review,agent-board-design-qa}
+~/.agents/skills/{agent-board,agent-board-bootstrap,agent-board-research,agent-board-spec,agent-board-safe-workflow,agent-board-flow,agent-board-implement,agent-board-worker,agent-board-grill,agent-board-maintenance,agent-board-design-wireframe,agent-board-design-review,agent-board-design-qa}
+~/.cursor/skills/{agent-board,agent-board-bootstrap,agent-board-research,agent-board-spec,agent-board-safe-workflow,agent-board-flow,agent-board-implement,agent-board-worker,agent-board-grill,agent-board-maintenance,agent-board-design-wireframe,agent-board-design-review,agent-board-design-qa}
 ```
 
 Check links, and that the bundled skill docs still match the CLI:
@@ -112,7 +112,7 @@ use cases -> scenario matrix -> failing test/replay -> implementation -> full re
 
 ## Skills
 
-Twelve skills are bundled:
+Thirteen skills are bundled:
 
 - `agent-board`: thin router/orchestrator. Chooses the right workflow, creates goals/specs/tasks, delegates, reviews evidence, and controls flow waves.
 - `agent-board-bootstrap`: guided project or feature bootstrap interview with current-docs research and explicit tradeoffs.
@@ -126,8 +126,9 @@ Twelve skills are bundled:
 - `agent-board-maintenance`: read-only board hygiene. Reports stale claims/runs, broken links, archive candidates, and consolidation candidates before cleanup.
 - `agent-board-design-wireframe`: authors an HTML-mockup wireframe (design board) — zero-build React-UMD + Babel, a window-globals design kit, and a Figma-like canvas of device-sized artboards. Import with `agent-board wireframe import`, then preview through `agent-board web`.
 - `agent-board-design-review`: read-only critique of a wireframe against its spec — screenshot and inspect each artboard, then file concrete, spec-linked findings.
+- `agent-board-design-qa`: measures the IMPLEMENTED, running UI instead of eyeballing a screenshot — a portable DOM geometry scan (overflow, truncation, misalignment, tap targets), design-token and contrast checks, an optional reference pixel-diff, and a vision judge only for the residual. Runs through whatever browser/preview tools the harness already exposes.
 
-The split keeps hot skill context small: the router does not carry bootstrap, worker, or hygiene detail; implement workers do not choose the roadmap; and the design pair separates authoring a mockup from reviewing it.
+The split keeps hot skill context small: the router does not carry bootstrap, worker, or hygiene detail; implement workers do not choose the roadmap; and the design trio separates authoring a mockup (wireframe), critiquing it (review), and measuring the built UI (design-qa).
 
 ## Optional Flows
 
diff --git a/docs/concepts.md b/docs/concepts.md
index c9fc73c..2037b16 100644
--- a/docs/concepts.md
+++ b/docs/concepts.md
@@ -23,6 +23,7 @@
     agent-board-maintenance/
     agent-board-design-wireframe/
     agent-board-design-review/
+    agent-board-design-qa/
   projects/<project>/
     project.json
     flows/
diff --git a/src/skills.ts b/src/skills.ts
index 21229b0..5bfe272 100644
--- a/src/skills.ts
+++ b/src/skills.ts
@@ -504,7 +504,7 @@ Layout:
 - Flow scripts: \`<board>/flows/*.mjs\`; run artifacts: \`<board>/goals/<goal-slug>/flows/runs/<run-id>/\`.
 - Home boards prefix the above paths with \`projects/<project-slug>/\`.
 - Specs, knowledge, and wireframes: overlay layers at global, project, and goal scope. In a local board, global and project scope collapse (single project).
-- Skills are always global: \`~/.agent-board/skills/{agent-board,agent-board-bootstrap,agent-board-research,agent-board-spec,agent-board-safe-workflow,agent-board-flow,agent-board-implement,agent-board-worker,agent-board-grill,agent-board-maintenance,agent-board-design-wireframe,agent-board-design-review}\`, linked into \`~/.claude/skills\`, \`~/.agents/skills\`, and \`~/.cursor/skills\` by \`agent-board skills install\`. Local boards never copy skills into the repo.
+- Skills are always global: \`~/.agent-board/skills/{agent-board,agent-board-bootstrap,agent-board-research,agent-board-spec,agent-board-safe-workflow,agent-board-flow,agent-board-implement,agent-board-worker,agent-board-grill,agent-board-maintenance,agent-board-design-wireframe,agent-board-design-review,agent-board-design-qa}\`, linked into \`~/.claude/skills\`, \`~/.agents/skills\`, and \`~/.cursor/skills\` by \`agent-board skills install\`. Local boards never copy skills into the repo.
 
 Why: home keeps board state out of source control and lets many projects/agents share one index; local lets a single project version its board (goals, tasks, specs) alongside the code.