free-pi-cli 0.6.2 → 0.6.4

package/skills/ux-visual/SKILL.md

@@ -0,0 +1,252 @@
+---
+name: ux-visual
+description: Exhaustive visual and hands-on design review of every page, layout and component, judged against strong UI norms. Screenshots and measures each surface (look_at_image plus DOM audits), tries it like a user, writes up problems, drafts three competing fixes per problem, scores them, implements the winner, and verifies it with tests and fresh screenshots. Use for "review the visual design", "audit the layout", "design critique", "check density and whitespace", "why does this page scroll".
+---
+
+# UX Visual
+
+Review whether every surface looks and behaves like the work of a strong product team,
+from the smallest component up to the whole layout. Then fix what is wrong: draft three
+different fixes, score them, implement the best, and prove it with measurements and new
+screenshots.
+
+Take the view of a demanding senior designer and a first-time user at once. Do not
+excuse a problem as an edge case, a framework default, or something only small screens
+show. If a person would hesitate, squint, scroll for what should be one screen, hunt for
+a control, or misread a label, it is a finding. Also say what is excellent. No invented
+findings.
+
+This skill runs on your default model. Do not switch to a more expensive model. You
+cannot see images directly: judge screenshots with the `look_at_image` tool (a cheap
+vision model), and use DOM measurements for everything measurable.
+
+Everything runs in one agent, in order. There are no helpers to hand work to. Work on one
+page, one problem cluster, one proposal at a time. Write each result to its file at once
+and keep only a one-line summary in context. After a context reset, resume from
+`docs/ux-visual/` (see "Resuming").
+
+`$SKILL_DIR` means the folder that contains this SKILL.md. The geometry audit lives in
+the sibling skill: `$SKILL_DIR/../ux-walker/references/geometry-audit.js`. The two skills
+ship together.
+
+## Options the user may give
+
+url; `--scope <page|route|component>` (default: whole app); `--viewports <list>`
+(default `1440x900,768x1024,390x844`); `--no-implement` (stop after the decisions);
+`--max-fixes N` (default 8 clusters carried through to implementation); `--session <name>`.
+With no arguments, detect the URL and start.
+
+## Output
+
+```
+docs/ux-visual/
+  inventory.md                pages, layouts, groups, components, states
+  pages/<slug>/shots/<viewport>-<state>.png   (inside the project folder)
+  pages/<slug>/audit.json     layout-audit and geometry-audit results
+  pages/<slug>/findings.md    critique for this page
+  problems.md                 clustered, ranked problems
+  proposals/<cluster>/{A,B,C}.md   (+ mock screenshots if made)
+  decisions/<cluster>.md      scores, winner, defense
+  verification/<cluster>.md   after-measurements and screenshots
+  run-history.json            clusters fixed, deferred, rejected, commits
+  report.md                   final report
+```
+
+## Phase 0: Preflight
+
+1. `command -v agent-browser`; if missing use `npx -y agent-browser` throughout. Run
+   `agent-browser install` once if the browser is not installed.
+2. Check the URL with curl. If nothing answers, start the dev server in the background
+   with a log and saved PID, pick a free port, and stop only that PID at the end. Delete the saved browser state file (step 3) at the end too.
+3. Auth: find how the app signs in (test users, seed data, e2e helpers). Sign in once in
+   the session (`S=ux-visual-<domain>`), then `state save "${TMPDIR:-/tmp}/free-pi-ux-browser-state.json"`
+   (outside the project, because it holds cookies; never commit it; delete it at the end of the run).
+   Use test data only. Never act destructively on real data.
+4. Design system: find tokens, the component library, and any enforcement script. Every
+   fix lands in the design system first. Note the rules in `inventory.md`.
+5. Reuse earlier work if present: `docs/ux-paths/catalog.md` (which states to visit),
+   `docs/ux-flow/report.md` (decisions already made; do not reopen them),
+   `docs/ux-visual/run-history.json` (skip clusters fixed earlier unless their surfaces changed).
+6. `mkdir -p docs/ux-visual/pages docs/ux-visual/proposals docs/ux-visual/decisions docs/ux-visual/verification`
+
+## Phase 1: Inventory
+
+Write `docs/ux-visual/inventory.md`: every page or route with how to reach each state
+(empty, loading, populated, long content, error, each role, signed out, transient UI such
+as dialogs, menus, toasts); the layouts and which pages use them; the component groups
+(toolbars, cards, forms, lists); the design-system components and where each renders.
+This is the work list. Nothing is audited that is not listed.
+
+## Phase 2: Inspect, one page at a time
+
+Read `references/visual-heuristics.md` once first. Then for each page in the inventory,
+fully finish it (including its findings.md) before starting the next.
+
+For each viewport x state you reach:
+
+1. **Capture.** `agent-browser --session $S set viewport <w> <h>`, reach the state, wait
+   for a known element (live apps never reach network idle: use `wait --text` or a
+   selector, with a short timeout), then
+   `agent-browser --session $S screenshot docs/ux-visual/pages/<slug>/shots/<viewport>-<state>.png`
+   and a `--full` copy for pages that scroll.
+2. **Measure.** Run both audits and append the JSON to `pages/<slug>/audit.json`, keyed by
+   viewport and state:
+   ```bash
+   agent-browser --session $S eval --stdin < "$SKILL_DIR/references/layout-audit.js"
+   agent-browser --session $S eval --stdin < "$SKILL_DIR/../ux-walker/references/geometry-audit.js"
+   ```
+   `layout-audit.js` reports viewport fit and page scroll, off-screen primary actions,
+   scroll containers, dead space, spacing-scale drift, type sizes, alignment, small
+   targets, low contrast, overlaps and fixed overlays. `geometry-audit.js` reports uneven
+   siblings, spills and wrapped controls. These numbers decide anything measurable.
+3. **Look.** Make `look_at_image` calls for judgment only: hierarchy, clarity, balance,
+   whether the screen looks intentional. **Budget: one call per viewport for the page's
+   main state, plus at most two more per page for other key states (a dialog, an error).
+   No more than 5 per page.** One specific question per call, built from the norms:
+   ```
+   look_at_image(path="docs/ux-visual/pages/settings/shots/1440x900-main.png",
+     question="This is the settings page of a developer tool. (1) What is the single most prominent element, and is it the primary action? (2) Is any information shown twice? (3) Are there large empty areas with no purpose, or crowded clusters? (4) Which labels are unclear? (5) Does anything look misaligned or inconsistent with its neighbors? Name the elements.")
+   ```
+   Never ask twice about the same image. If a look_at_image error says the daily allowance
+   is used up, stop calling it, rely on measurements and the snapshot, and say so in the report.
+4. **Interact like a person.** Hover and click every control, tab through the page (focus
+   order and visible focus), open every menu and dialog, type into every field (long
+   text, emoji), resize between breakpoints, scroll every scroll container, trigger
+   errors (invalid input, `set offline on`). Use `snapshot -i` for refs and `../ux-walker/references/action-patterns.md` for commands. Note each hesitation,
+   layout jump, dead end and slow response. Do not use destructive actions on real data.
+5. **Critique bottom-up, then top-down**, naming the norm violated (IDs in visual-heuristics.md):
+   - Component: is the purpose obvious? the right pattern? all states (hover, focus,
+     active, disabled, loading, empty, error)? clear label? big enough target? aligned?
+   - Group: do the items belong together? one primary action? order matches the task?
+     spacing on the scale? duplicated by another group?
+   - Page: one purpose and focal point? Does it fit the viewport when it should be one
+     screen (app-like surfaces must not page-scroll)? density right for the surface?
+     whitespace purposeful? hierarchy matches importance? anything said twice?
+   - Layout: consistent with other pages that share it? regions on one grid with aligned
+     edges? predictable navigation? reflows rather than overflows at every breakpoint?
+6. **Severity.** P0 blocks or misleads (cannot complete, unreadable, key control off-screen).
+   P1 a person stumbles (scrolling for what should be one page, buried primary action,
+   confusing label, layout jump, inconsistent pattern). P2 visibly below excellent (uneven
+   spacing, wrong density, weak hierarchy, misalignment, repeated information). P3 polish.
+
+Write `pages/<slug>/findings.md`: a one-paragraph verdict per viewport and state with
+screenshot paths; a table (id | level | element | problem | norm | evidence | severity |
+measured, observed or suspected); and an "Excellent as is" list. Every finding cites a
+screenshot path and/or an audit.json metric. A look_at_image answer alone is "observed" or
+"suspected" until a measurement confirms it. Do not edit code in this phase.
+
+Keep one line per page in context: "settings: 1 P0, 3 P1, 5 P2; worst: page scrolls 412px at 1440x900".
+
+## Phase 3: Consolidate
+
+Read the findings files one at a time and build `docs/ux-visual/problems.md`:
+1. Merge the same problem seen on several pages or viewports.
+2. Group by root cause (for example "the room grid does not constrain height" explains five
+   findings). One cluster is one design decision. Prefer fixing a shared component, layout
+   or token over patching pages.
+3. Rank clusters by severity x reach (surfaces and journeys affected) x centrality, divided
+   by effort. P0 first.
+4. Check coverage against inventory.md and list any page or state not audited.
+5. For each cluster: id, title, root cause, finding ids, affected surfaces, evidence,
+   severity, and acceptance criteria that can be measured ("no page scroll at 1440x900 on
+   /room", "all card padding uses the 16px token", "primary action inside the viewport").
+
+Carry the top `--max-fixes` clusters forward. List the rest as deferred.
+
+## Phase 4: Propose (A, B, C, one after another)
+
+For one cluster at a time, write three proposals to `docs/ux-visual/proposals/<cluster>/`,
+one file after the other, each with a different strategy:
+- **A Minimal**: the smallest change to existing components and tokens that meets the criteria.
+- **B Restructure**: rethink layout, grouping or pattern (tabs instead of stacked panels,
+  a docked strip instead of inline cards).
+- **C Convention**: what the best products in this category do. Name the pattern, not brand assets.
+
+Each file: the change, a before/after description, an ASCII wireframe or (optionally) a
+static HTML mock in a scratch folder inside the project that uses the design system's
+tokens and is screenshotted into the proposal folder, the components, tokens and files
+touched, effort, risks, and how it meets each acceptance criterion. Proposals stay inside
+the design system. Write A, B and C before scoring any of them.
+
+## Phase 5: Score and decide
+
+Use `references/solution-rubric.md`.
+
+1. Score A, B and C yourself, one lens at a time (usability, then visual craft, then
+   engineering), writing the scores down for each lens before the next.
+2. If mocks exist, make one `look_at_image` critique call per mock (at most 3 per cluster)
+   as described in the rubric. Verify its claims before using them.
+3. Write `docs/ux-visual/decisions/<cluster>.md` from the template: the chosen solution
+   (possibly with a graft), the score table, the defense (why it beats each other option,
+   norms met, cost, what it rules out), final acceptance criteria and the test plan.
+
+With `--no-implement`, stop after all decisions and go to the report.
+
+## Phase 6: Implement, one cluster at a time
+
+Create a branch `ux-visual/<cluster>` (or work on the current branch if the user prefers).
+
+1. Change the **design system first** (tokens, component CSS, component library, catalog),
+   then pages. No ad-hoc styles. Run the project's design-system check if it has one.
+2. Write a **failing test first** for behavior or layout changes: for example an assertion
+   that `document.scrollingElement.scrollHeight <= innerHeight` on the page, that the
+   primary action's bounding box is inside the viewport, that sibling cards share a
+   height. Run it and see it fail.
+3. Implement the decision as written. Justify any deviation in the verification note.
+4. Run typecheck, lint, unit tests and the affected end-to-end tests. Update tests whose
+   expectations legitimately changed. Never weaken a test to make it pass.
+5. Commit only the changed files with a message naming the cluster. Do not push.
+
+## Phase 7: Verify, per cluster
+
+Repeat the Phase 2 capture and measure steps on every affected surface at every viewport.
+Compare with the "before" numbers in audit.json. Check each acceptance criterion with a
+measurement. Make one `look_at_image` call per key after-screenshot to confirm the
+hierarchy and look are better ("Compare this to a layout with <the earlier problem>: is
+<the problem> gone?"). Check neighboring surfaces for regressions. Write
+`docs/ux-visual/verification/<cluster>.md` with pass or fail per criterion and the
+after-screenshots. On a fail, fix and re-check, at most twice, then record it as
+unresolved with the evidence.
+
+## Phase 8: Report
+
+Update `run-history.json`. Write `docs/ux-visual/report.md` from `templates/report-template.md`:
+before and after per cluster, criteria met, what was deferred and why, remaining P0 and P1, and the "excellent as is" list. For deferred clusters: if `command -v gh` finds
+GitHub CLI and `gh auth status` passes, check for duplicates and run `gh issue create`
+(label `ux-visual` only if it exists). Otherwise write `docs/ux-visual/issues/<cluster>.md`.
+
+Tell the user: surfaces audited and coverage gaps; findings by severity; each implemented
+cluster in one line with the decision, why it won and the verified result; deferred
+clusters; anything still failing; the path to report.md. Say what you did not verify.
+
+## Resuming
+
+If context was cleared, read `run-history.json`, `inventory.md`, `problems.md`, then list
+`pages/*/findings.md`, `proposals/*`, `decisions/*`, `verification/*` to see the last
+completed step. Continue from the next missing file.
+
+## Rules
+
+- **Measure, look, then touch.** Numbers settle evenness, fit and density. The vision
+  model settles hierarchy and clarity, and may be wrong. Interaction finds what neither shows.
+- **Check every level**: component, group, page, layout, and back down. A fine component
+  can be wrong inside its group.
+- **One screen means one screen.** App surfaces (editors, consoles, dashboards) must fit
+  the viewport at 1280x800 or larger, with inner panels scrolling. Content pages may
+  scroll but keep the primary action visible.
+- **Density is a decision**, measured against the norms for the surface type.
+- **Fix at the root, in the design system.** One token or component change beats ten page patches.
+- **Wait for content, not the network.** Live pages never go idle.
+- **A fix is done when measurements and new screenshots show it, tests pass, and nothing regressed.**
+- Keep look_at_image calls within the budgets above. Prefer `layout-audit.js` and `geometry-audit.js` for anything they can measure.
+
+## References
+
+| File | Use |
+|------|-----|
+| references/visual-heuristics.md | The norms to cite (read first) |
+| references/layout-audit.js | Viewport fit, scroll, density, spacing, type, targets, contrast |
+| ../ux-walker/references/geometry-audit.js | Uneven siblings, spills, wrapped controls |
+| ../ux-walker/references/action-patterns.md | agent-browser command patterns |
+| references/solution-rubric.md | Scoring and decision template |
+| templates/report-template.md | Final report layout |

package/skills/ux-visual/references/layout-audit.js

@@ -0,0 +1,145 @@
+// Layout & density audit — run via: agent-browser --session {S} eval "$(cat layout-audit.js)"
+// (or Playwright: page.evaluate(fs.readFileSync(path,'utf8'))). Returns JSON.
+// Measures what eyes misjudge: viewport fit, scroll containers, dead space,
+// spacing-scale drift, alignment, type scale, small targets, low contrast.
+(() => {
+  const vw = innerWidth, vh = innerHeight;
+  const vis = (e) => {
+    const r = e.getBoundingClientRect();
+    if (r.width < 1 || r.height < 1) return false;
+    const cs = getComputedStyle(e);
+    return cs.visibility !== 'hidden' && cs.display !== 'none' && +cs.opacity !== 0;
+  };
+  const sig = (e) => {
+    let s = e.tagName.toLowerCase();
+    if (e.id) s += '#' + e.id;
+    else if (typeof e.className === 'string' && e.className.trim())
+      s += '.' + e.className.trim().split(/\s+/).slice(0, 2).join('.');
+    const t = (e.getAttribute('aria-label') || e.textContent || '').trim().replace(/\s+/g, ' ').slice(0, 30);
+    return t ? `${s} "${t}"` : s;
+  };
+  const all = [...document.querySelectorAll('body *')].filter(vis);
+  const se = document.scrollingElement || document.documentElement;
+
+  // 1. Viewport fit (L1/L2/L6)
+  const viewport = {
+    width: vw, height: vh,
+    pageScrollY: Math.max(0, se.scrollHeight - vh),
+    pageScrollX: Math.max(0, se.scrollWidth - vw),
+  };
+
+  // Primary actions outside the viewport (L2): high-emphasis buttons, submit buttons
+  const primaries = all.filter((e) =>
+    (e.matches('button[type=submit], [data-primary], [class*="--primary"]') && e.matches('button, a, [role=button]')));
+  const offscreenPrimary = primaries
+    .map((e) => ({ el: sig(e), r: e.getBoundingClientRect() }))
+    .filter(({ r }) => r.bottom > vh + 1 || r.right > vw + 1 || r.top < 0)
+    .map(({ el, r }) => ({ el, top: Math.round(r.top), bottom: Math.round(r.bottom) }));
+
+  // 2. Scroll containers (L1/L3): which regions scroll and how much
+  const scrollers = all
+    .filter((e) => {
+      const cs = getComputedStyle(e);
+      return /(auto|scroll)/.test(cs.overflowY) && e.scrollHeight > e.clientHeight + 1;
+    })
+    .slice(0, 20)
+    .map((e) => ({ el: sig(e), clientH: e.clientHeight, scrollH: e.scrollHeight }));
+
+  // 3. Dead space (D2): large visible blocks whose area is mostly empty
+  const deadSpace = [];
+  for (const e of all) {
+    const r = e.getBoundingClientRect();
+    const area = r.width * r.height;
+    if (area < vw * vh * 0.08 || r.width < 200 || r.height < 120) continue;
+    const kids = [...e.querySelectorAll('*')].filter(vis);
+    if (kids.length > 400) continue;
+    // union area of leaf content boxes (text/media/controls), clipped to e
+    let covered = 0;
+    for (const k of kids) {
+      if (k.children.length && !k.matches('button, a, input, textarea, select, img, svg, video, canvas, iframe')) continue;
+      const kr = k.getBoundingClientRect();
+      const w = Math.max(0, Math.min(kr.right, r.right) - Math.max(kr.left, r.left));
+      const h = Math.max(0, Math.min(kr.bottom, r.bottom) - Math.max(kr.top, r.top));
+      covered += w * h;
+    }
+    const fill = Math.min(1, covered / area);
+    if (fill < 0.12) deadSpace.push({ el: sig(e), w: Math.round(r.width), h: Math.round(r.height), fillPct: Math.round(fill * 100), pctOfViewport: Math.round((area / (vw * vh)) * 100) });
+  }
+  deadSpace.sort((a, b) => b.pctOfViewport - a.pctOfViewport);
+
+  // 4. Spacing scale drift (D3): gaps/paddings/margins observed
+  const spacing = {};
+  for (const e of all.slice(0, 3000)) {
+    const cs = getComputedStyle(e);
+    for (const p of ['paddingTop', 'paddingLeft', 'marginTop', 'rowGap', 'columnGap']) {
+      const v = parseFloat(cs[p]);
+      if (v > 0 && v < 200) spacing[Math.round(v)] = (spacing[Math.round(v)] || 0) + 1;
+    }
+  }
+  const values = Object.keys(spacing).map(Number).sort((a, b) => a - b);
+  const offScale = values.filter((v) => v % 4 !== 0 && v > 2);
+  const nearDupes = values.filter((v, i) => i && v - values[i - 1] <= 2 && v > 4).map((v, i) => [values[values.indexOf(v) - 1], v]);
+
+  // 5. Type scale (H3)
+  const sizes = {};
+  for (const e of all) {
+    if (![...e.childNodes].some((n) => n.nodeType === 3 && n.textContent.trim())) continue;
+    const cs = getComputedStyle(e);
+    const key = `${Math.round(parseFloat(cs.fontSize))}px/${cs.fontWeight}`;
+    sizes[key] = (sizes[key] || 0) + 1;
+  }
+  const distinctFontSizes = [...new Set(Object.keys(sizes).map((k) => k.split('/')[0]))];
+
+  // 6. Left-edge alignment within regions (L4/H6): near-miss left edges
+  const edges = all.filter((e) => e.matches('h1,h2,h3,h4,p,label,button,input,section,article,header')).map((e) => Math.round(e.getBoundingClientRect().left));
+  const edgeCounts = {}; edges.forEach((x) => (edgeCounts[x] = (edgeCounts[x] || 0) + 1));
+  const edgeVals = Object.keys(edgeCounts).map(Number).sort((a, b) => a - b);
+  const nearMissEdges = edgeVals.filter((x, i) => i && x - edgeVals[i - 1] > 0 && x - edgeVals[i - 1] <= 3).map((x) => [edgeVals[edgeVals.indexOf(x) - 1], x]);
+
+  // 7. Small targets (I4)
+  const smallTargets = all
+    .filter((e) => e.matches('button, a[href], [role=button], input:not([type=hidden]), select, [tabindex]:not([tabindex="-1"])'))
+    .map((e) => ({ el: sig(e), r: e.getBoundingClientRect() }))
+    .filter(({ r }) => r.width < 24 || r.height < 24)
+    .slice(0, 30)
+    .map(({ el, r }) => ({ el, w: Math.round(r.width), h: Math.round(r.height) }));
+
+  // 8. Low contrast text (A1), approximate: walk up to the first opaque background
+  const rgb = (s) => (s.match(/[\d.]+/g) || []).map(Number);
+  const lum = ([r, g, b]) => { const f = (c) => { c /= 255; return c <= 0.03928 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4; }; return 0.2126 * f(r) + 0.7152 * f(g) + 0.0722 * f(b); };
+  const bgOf = (e) => { for (let n = e; n; n = n.parentElement) { const c = rgb(getComputedStyle(n).backgroundColor); if (c.length >= 3 && (c[3] === undefined || c[3] > 0.9)) return c; } return [255, 255, 255]; };
+  const lowContrast = [];
+  for (const e of all) {
+    if (![...e.childNodes].some((n) => n.nodeType === 3 && n.textContent.trim())) continue;
+    const cs = getComputedStyle(e);
+    const fg = rgb(cs.color); if (fg.length < 3) continue;
+    const L1 = lum(fg), L2 = lum(bgOf(e));
+    const ratio = (Math.max(L1, L2) + 0.05) / (Math.min(L1, L2) + 0.05);
+    const large = parseFloat(cs.fontSize) >= 24 || (parseFloat(cs.fontSize) >= 18.66 && +cs.fontWeight >= 700);
+    if (ratio < (large ? 3 : 4.5)) lowContrast.push({ el: sig(e), ratio: +ratio.toFixed(2) });
+    if (lowContrast.length >= 30) break;
+  }
+
+  // 9. Overlaps between interactive elements (I1/L5)
+  const inter = all.filter((e) => e.matches('button, a[href], input, textarea, select, [role=button]')).slice(0, 300).map((e) => ({ e, r: e.getBoundingClientRect() }));
+  const overlaps = [];
+  for (let i = 0; i < inter.length && overlaps.length < 20; i++)
+    for (let j = i + 1; j < inter.length; j++) {
+      const a = inter[i], b = inter[j];
+      if (a.e.contains(b.e) || b.e.contains(a.e)) continue;
+      const w = Math.min(a.r.right, b.r.right) - Math.max(a.r.left, b.r.left);
+      const h = Math.min(a.r.bottom, b.r.bottom) - Math.max(a.r.top, b.r.top);
+      if (w > 4 && h > 4) { overlaps.push({ a: sig(a.e), b: sig(b.e), w: Math.round(w), h: Math.round(h) }); break; }
+    }
+
+  // 10. Fixed/sticky overlays that may cover content (e.g. third-party badges)
+  const fixedOverlays = all.filter((e) => /fixed|sticky/.test(getComputedStyle(e).position)).slice(0, 15).map((e) => { const r = e.getBoundingClientRect(); return { el: sig(e), x: Math.round(r.left), y: Math.round(r.top), w: Math.round(r.width), h: Math.round(r.height) }; });
+
+  return JSON.stringify({
+    viewport, offscreenPrimary, scrollers, deadSpace: deadSpace.slice(0, 10),
+    spacing: { observed: values, offScale, nearDupes: nearDupes.slice(0, 10) },
+    type: { distinctFontSizes, sizes },
+    alignment: { nearMissEdges: nearMissEdges.slice(0, 15) },
+    smallTargets, lowContrast, overlaps, fixedOverlays,
+  }, null, 1);
+})();

package/skills/ux-visual/references/solution-rubric.md

@@ -0,0 +1,70 @@
+# Solution scoring rubric and decision template
+
+You score the proposals yourself, one lens at a time. Do each lens as a separate pass
+over all three proposals and write the scores down before moving to the next lens, so
+the lenses stay independent.
+
+## Lenses
+- **Usability**: a first-time user doing the core task. Speed, discoverability,
+  error-proneness, clarity of state and labels.
+- **Visual craft**: hierarchy, rhythm, density, alignment, consistency with the design
+  system and the rest of the app.
+- **Engineering**: scope, risk, reuse of existing components and tokens, ease of
+  testing, effect on other surfaces.
+
+## Criteria (score 1 to 5; weight in brackets)
+1. Meets every acceptance criterion of the cluster, measurably [x3]
+2. Simplicity: fewer elements, steps and states for the user [x2]
+3. Consistency: reuses system patterns; one concept, one look [x2]
+4. Usability: task speed, error prevention, accessibility [x2]
+5. Visual quality: hierarchy, density, whitespace, alignment [x2]
+6. Effort and risk (5 = small and safe) [x1]
+
+A proposal that fails criterion 1 is out, unless all fail it. Then name the graft that
+makes the best one pass.
+
+You may graft one concrete element from a runner-up into the winner if it improves the
+winner without breaking its idea.
+
+## Vision critique of mocks (optional)
+
+If a proposal has a mock screenshot, make one `look_at_image` call per mock with a
+critique question, for example: "This is a proposed layout for <purpose>. Name any
+element that is unclear, crowded, misaligned or low contrast. Which element is the
+primary action? What would a first-time user do first?" At most 3 calls per cluster, one
+per mock. Treat the answer as one more opinion, not a vote. A vision model cannot click or
+measure, so verify its claims in the mock with DOM measurements before using them. If it
+rejects your chosen option, the decision document must answer its reasons.
+
+## Decision document (decisions/{cluster}.md)
+
+```markdown
+# {cluster-id}: {title}
+
+## Problem
+{root cause, findings covered, evidence links, acceptance criteria}
+
+## Options considered
+| Option | Idea | Weighted score (Usability / Visual / Engineering) |
+|--------|------|---------------------------------------------------|
+| A Minimal | ... | 34 / 31 / 38 |
+| B Restructure | ... | 41 / 44 / 33 |
+| C Convention | ... | 39 / 40 / 35 |
+
+(The numbers above only show the layout. Use your real scores.)
+
+## Decision
+{the chosen option, plus grafts, stated precisely enough to implement}
+
+## Why this is the best
+- Against A: ...
+- Against C: ...
+- Norms satisfied: L1, L3, H1 ...
+- Costs and what it rules out: ...
+
+## Implementation plan
+{design-system changes first (tokens, CSS, components, catalog), then pages; files}
+
+## Test plan
+{failing-first tests: layout assertions, e2e, unit; viewports; states}
+```

package/skills/ux-visual/references/visual-heuristics.md

@@ -0,0 +1,102 @@
+# Visual & Interaction Heuristics — the norms battery
+
+Read this before inspecting, proposing or judging. Every finding names the norm
+it violates (use the IDs). "It's the default" or "it's an edge case" is never a
+defense.
+
+## L — Layout & viewport fit
+- **L1 One screen for app surfaces.** Tools, editors, rooms, dashboards and
+  consoles fit the viewport at ≥ 1280×800 with no page scroll; long content
+  scrolls inside its panel. Measured: `layout-audit.js → viewport.pageScrollY`.
+- **L2 Primary action always visible.** The main action of a screen (Send, Save,
+  Create) is inside the viewport without scrolling at every target viewport.
+- **L3 Nothing grows the page by accumulation.** Repeated events (notifications,
+  approvals, toasts, logs) must not push layout; they dock, replace, collapse,
+  or scroll inside a container.
+- **L4 One grid.** Regions align to shared edges; outer gutters equal; no
+  full-bleed panel beside inset panels.
+- **L5 Stable layout.** No layout shift when data loads, states change, or
+  hover toolbars appear (reserve space or overlay).
+- **L6 Reflow, not overflow.** No horizontal scroll at any viewport ≥ 320px;
+  components reflow (stack, wrap, collapse to menus) at breakpoints.
+- **L7 Predictable regions.** Navigation where users expect it (top/left), the
+  primary work area largest, secondary info at the side, actions near what they
+  act on.
+
+## D — Density & whitespace
+- **D1 Density fits the surface.** Tools/dashboards: dense (body 13–14px,
+  row height 28–36px, tight groups). Content/reading: comfortable (16px+,
+  line-height 1.5–1.7, measure 45–80ch). Marketing: airy, generous sections.
+- **D2 Whitespace is intentional.** No dead bands (large empty areas that carry
+  no meaning, e.g. a mostly-empty panel reserving 40% of the screen), no cramped
+  clusters. Empty states are compact on tool surfaces.
+- **D3 Spacing scale.** All gaps/paddings come from the design system's scale
+  (4/8-based); measured values off-scale or near-duplicates (e.g. 14 and 16
+  side by side) are findings.
+- **D4 Proximity encodes grouping.** Space within a group < space between
+  groups (Gestalt proximity), consistently.
+- **D5 Information per pixel.** Repeated chrome (avatars, names, timestamps,
+  labels) is collapsed where repetition carries no new information (e.g.
+  grouped chat messages).
+
+## H — Hierarchy & visual design
+- **H1 One focal point and one primary action per view.** Exactly one
+  high-emphasis button per region; others secondary/tertiary.
+- **H2 Weight matches importance.** Size, color, contrast and position follow
+  the task's priority; destructive actions are distinct but not dominant.
+- **H3 Type scale.** A small set of sizes/weights from the system; headings
+  clearly stepped; no more than ~5 distinct sizes on a screen.
+- **H4 Color with purpose.** Accent reserved for primary/active/live states;
+  semantic colors only for their meaning; not one accent smeared everywhere.
+- **H5 Consistency.** Same thing, same look, same place, same name across pages.
+- **H6 Alignment.** Text baselines and left edges align within a group; icons
+  centered with their labels; numeric columns right-aligned.
+
+## C — Clarity & content
+- **C1 Plain labels.** Verbs for actions, nouns for places; no jargon the
+  persona lacks; one concept, one name (no driver/control/lock drift).
+- **C2 No duplication.** The same fact appears once per screen unless a new
+  context needs it.
+- **C3 Status is legible.** System state (working, waiting, error, offline) in
+  one predictable place, in words plus color (never color alone).
+- **C4 Microcopy earns its place.** Hint text that repeats the placeholder or
+  the obvious is removed; truncation shows full text on hover/focus.
+
+## I — Interaction & usability
+- **I1 Affordance.** Clickable things look clickable; non-clickable things
+  don't; links vs buttons used correctly.
+- **I2 Feedback within 100ms**, progress for >1s, completion/failure stated.
+- **I3 Error prevention and recovery.** Destructive actions confirm or undo;
+  errors say what happened and what to do; inputs keep their values on error.
+- **I4 Fitts.** Targets ≥ 24×24px (≥ 44×44 on touch); frequent targets large
+  and near the work; related actions adjacent.
+- **I5 Hick.** Few choices at once; progressive disclosure for advanced
+  options; defaults carry most decisions.
+- **I6 Recognition over recall.** Visible options, remembered preferences,
+  clear current location (active tab/nav).
+- **I7 Keyboard and focus.** Logical tab order, visible focus rings, Escape
+  closes overlays, Enter submits, focus returns after dialogs; hover-only UI
+  reachable by keyboard and touch.
+- **I8 States complete.** Every component has hover, focus, active, disabled
+  (with reason), loading, empty, error, and long-content states designed.
+
+## A — Accessibility baseline
+- **A1 Contrast** ≥ 4.5:1 text, ≥ 3:1 large text and UI boundaries/icons.
+- **A2 Names.** Every control has an accessible name; icon-only buttons have
+  labels/tooltips.
+- **A3 Motion.** Respects `prefers-reduced-motion`; no essential info only in
+  animation.
+- **A4 Zoom.** Usable at 200% zoom without loss of content.
+
+## P — Platform & category conventions
+- **P1 Follow the category's best-in-class patterns** (e.g. chat: grouped
+  messages, composer pinned bottom, inline media; code tools: tabs for views,
+  status bar, command palette; streaming: player-first layout, chat column,
+  channel bar) unless a deliberate improvement is documented.
+- **P2 Familiar controls** for familiar jobs (segmented controls for 2–4
+  exclusive views, tabs for peer views, menus for overflow, toggles for
+  instant settings, checkboxes for deferred settings).
+
+## Severity guide
+P0 blocks/misleads · P1 a human stumbles (L1, L2, L3, I3, C1 failures usually
+land here) · P2 visibly below excellent (D3, H6, D5) · P3 polish.

package/skills/ux-visual/templates/report-template.md

@@ -0,0 +1,29 @@
+# UX Visual Report — {DATE}
+
+## Summary
+| Metric | Value |
+|--------|-------|
+| Surfaces audited | {pages} pages × {states} states × {viewports} viewports |
+| Coverage gaps | {list or "none"} |
+| Findings | P0 {n} · P1 {n} · P2 {n} · P3 {n} |
+| By level | component {n} · group {n} · page {n} · layout {n} |
+| Clusters | {total} found · {implemented} implemented · {deferred} deferred |
+
+## Implemented
+### {cluster-id}: {title}
+- **Problem**: {one line + key metric before, e.g. "page scrolls 412px at 1440x900"}
+- **Decision**: {one line} — chosen over {alternatives} because {reason}
+- **Result**: {metric after, criteria pass/fail}
+- **Before / after**: `pages/{slug}/shots/...png` → `verification/{cluster}/...png`
+- **Tests**: {specs added/updated, results}
+- **Commit**: {sha} on {branch}
+
+## Deferred
+| Cluster | Severity | Why deferred | Issue |
+|---------|----------|--------------|-------|
+
+## Still failing / unverified
+- ...
+
+## Excellent as is
+- {surfaces that passed clean, so re-runs can skip them}