@bacnh85/pi-ux 0.4.4 → 0.4.6

package/CHANGELOG.md

@@ -1,5 +1,63 @@
 # Changelog
 
+## 0.4.6 (2026-09-06)
+
+### Added
+
+- **Step 4 — Render & Inspect** in the ux-design skill: a vision verify loop
+  for multimodal models (GLM-5.3, Claude, Gemini). Reference-first
+  capture with `web_screenshot` (now returned inline as an image block by
+  pi-web 0.6.2), inspect your own rendered build at a daemon-reachable address
+  (LAN IP / host.docker.internal; localhost only for a native same-host daemon), visibility
+  baseline (judge at 1×–3×, never sub-visible precision), deterministic
+  `ux_audit` stays the blocking gate. The single biggest quality lever for
+  flash-tier models: eyes on output beat rules in a prompt. Inspired by
+  zcode-plugins video2code. Slop-audit gate renumbered to Step 5; text-only
+  fallback unchanged. Live-tested end-to-end; hardened with SSRF-blocked
+  daemon fallbacks (local headless chrome capture read back inline — fast,
+  offline; LAN IP or cloudflared tunnel only when the remote daemon must
+  render the page).
+- `ux_audit`: pairs declared `min: 3` **without** size/weight are now
+  treated as non-text graphics (APCA Lc ≥ 30, per the documented gate
+  table) instead of the body-text Lc ≥ 75 floor. Found auditing a real
+  dashboard chart (accent-70% column on white: Lc 57.5 / WCAG 3.07:1 —
+  legal for graphics, wrongly failed as body copy). Text pairs with
+  size/weight are unchanged.
+- **Taste layer** (from anthropics/skills `frontend-design`): the ux-design
+  skill now carries the five named cliché clusters (cream/terracotta "Claude
+  look", acid-on-black, broadsheet kit, SaaS-card kit, template chrome),
+  taste rules (typography-as-personality, one-orchestrated-motion, design
+  writing, spend boldness in one place), the generic-default check before
+  building, variant-branching as files (`.ux/drafts/`), BEFORE-state capture
+  when redesigning, and design-DNA extraction from reference sites into
+  DESIGN.md.
+- `ux_audit` taste tells: flags **tracked-out uppercase eyebrows**
+  (uppercase + ≤13px + letter-spacing ≥0.08em in one rule) and **tinted
+  near-black backgrounds** (`#0B0B0B`/`#111` standing in for black; pure
+  `#000` allowed). The States gate now also fails CSS with
+  transitions/animations but no `prefers-reduced-motion` fallback.
+- New **`ux-capture`** skill: the render-and-inspect capture playbook
+  (local headless-Chrome vs daemon-rendered `web_screenshot`, daemon
+  addressing, SSRF blocks, tunnel last resort) split out of the always-
+  injected ux-design body to keep per-turn prompt overhead down.
+- **`ux_audit` auto-extracts contrast pairs** from rules that declare both
+  colour and background when no pairs are supplied (rgb-normalised dedupe,
+  24-pair cap) — closing the #1 silent gap where unchecked pairs meant
+  unchecked contrast. Fragment input now prints a hint to audit the complete
+  stylesheet instead of silently blocking on missing selectors.
+- **Data-viz rules + scale-to-task** in the ux-design skill: chart
+  fill-on-track contrast, categorical ramp limits, secondary-series opacity,
+  tabular numerics, empty-chart states, dense-table patterns; one-line brief
+  + single draft is now legitimate for small internal tools.
+  (Feedback implemented from a field review by a glm-5.3-flash agent that
+  designed with pi-ux under A2A peer review.)
+
+## 0.4.5 (2026-08-29)
+
+### Added
+
+- `/ux` argument completion offers runtime modes plus `status|default`.
+
 ## 0.4.4
 
 - Patch version bump for release sync and package documentation update.

package/README.md

@@ -49,7 +49,10 @@ The injected skill enforces **Constraint-First Design Generation**:
 1. **5-field brief per screen** — user job, inventory, token constraints, required states, one reference.
 2. **Generate fast, converge early** — text-only models inside the locked system; 2-loop convergence trigger.
 3. **Normalise** the draft back into tokens/elevation/spacing.
-4. **Slop-audit gate** — run `ux_audit` (measurable): APCA contrast, token coverage, state coverage, slop tells.
+4. **Render & Inspect** (multimodal models) — reference-first capture, then screenshot your own build and LOOK. Default: local headless-Chrome capture read back inline (offline, no daemon); alternative: `web_screenshot` (pi-web 0.6.2+, PNG returned inline) at a daemon-reachable address (LAN IP / host.docker.internal — SSRF-protected daemons block private ranges; cloudflared tunnel as last resort). Judge at viewer resolution (1×–3×); never chase sub-visible precision. Skip when text-only — the deterministic gates are the whole loop.
+5. **Slop-audit gate** — run `ux_audit` (measurable): APCA contrast, token coverage, state coverage, slop tells, tracked-eyebrow/near-black taste tells, reduced-motion coverage.
+
+Taste rules ship in the skill: named cliché clusters (the cream/terracotta "Claude look", acid-on-black, broadsheet kit, SaaS-card kit, template chrome), typography-as-personality, one-orchestrated-motion, design-writing rules, and the generic-default check ("would I produce this plan for any similar brief?").
 
 ## The `ux_audit` tool
 
@@ -63,8 +66,8 @@ ux_audit css="..." pairs=[{fg:"#111",bg:"#fff",label:"body",weight:400,size:16,m
 |------|----------------|
 | **Contrast (APCA)** | Perceptual APCA Lc per fg/bg pair (Lc ≥75 body, ≥45 large-bold, ≥30 non-text). hex or `oklch()`. Optional `weight`/`size` set the threshold. WCAG 2.x ratio shown as a compliance sidecar. |
 | **Tokens** | Hardcoded hex outside `:root` token defs; `box-shadow` not built from `var(--…)` tokens |
-| **States** | Interactive selectors (`button`/`a`/`input`/…/`[role=button]`) missing `:focus-visible` or `:disabled` |
-| **Slop tells** | Named AI signatures: glassmorphism (`backdrop-filter`), gradient orbs, neon glow, the shadcn default-card reflex (`rounded-2xl`+`shadow-lg`+`p-6`), 1px gray card borders |
+| **States** | Interactive selectors (`button`/`a`/`input`/…/`[role=button]`) missing `:focus-visible` or `:disabled`; any transition/animation missing a `prefers-reduced-motion` fallback |
+| **Slop tells** | Named AI signatures: glassmorphism (`backdrop-filter`), gradient orbs, neon glow, the shadcn default-card reflex (`rounded-2xl`+`shadow-lg`+`p-6`), 1px gray card borders, tracked-out eyebrows, tinted near-black backgrounds |
 
 Returns pass/fail per gate + a formatted report. In `strict` mode this is the gate that blocks handoff.
 
@@ -90,6 +93,7 @@ The skill tells the agent which model to use for each step. The gate is mechanic
 
 - **`ux-design`** — the Constraint-First method + deterministic-first model routing (auto-injected by the hook when active).
 - **`ux-presets`** — reference design-system presets for Step 0: a lintable DESIGN.md starter, the shadcn/Material/Radix reuse table, and a CSS-only `:root` fallback. Reference only — no bundled CSS.
+- **`ux-capture`** — the Step 4 render-and-inspect capture playbook: local headless-Chrome capture read inline vs daemon-rendered `web_screenshot`, LAN IP/host.docker.internal addressing, SSRF-blocked daemons, cloudflared tunnel as last resort.
 
 ## Configuration
 

package/extensions/index.js

@@ -79,7 +79,7 @@ function auditParametersSchema() {
             fg: { type: "string", description: "Foreground colour, e.g. '#111111' or 'oklch(60% 0.18 250)'." },
             bg: { type: "string", description: "Background colour, e.g. '#ffffff'." },
             label: { type: "string", description: "Human label for this text style (e.g. 'body')." },
-            min: { type: "number", description: "WCAG compliance floor (4.5 body, 3.0 large/UI). Shown as a sidecar; the primary gate is APCA. Defaults to 4.5." },
+            min: { type: "number", description: "WCAG compliance floor (4.5 body, 3.0 large/UI). Shown as a sidecar; the primary gate is APCA. Defaults to 4.5. Pairs with min 3 and NO size/weight are treated as non-text graphics (APCA Lc 30 per the gate table)." },
             weight: { type: "number", description: "Font weight (400/500/700). With size, sets the APCA threshold. Defaults to 400." },
             size: { type: "number", description: "Font size in px. With weight, sets the APCA threshold. Defaults to 16." },
           },
@@ -112,6 +112,7 @@ function formatAuditResult(result) {
   lines.push(s.pass ? "✓ States" : "✗ States");
   for (const m of s.missingFocusVisible) lines.push(`  ✗ ${m}`);
   for (const m of s.missingDisabled) lines.push(`  ✗ ${m}`);
+  for (const m of s.missingReducedMotion || []) lines.push(`  ✗ ${m}`);
 
   const st = result.gates.slopTells;
   lines.push(st.pass ? "✓ Slop tells" : "✗ Slop tells");
@@ -156,12 +157,13 @@ export default function uxExtension(pi) {
     name: "ux_audit",
     label: "UX Slop Audit",
     description:
-      "Run deterministic slop-audit gates on CSS: APCA contrast (perceptual; WCAG sidecar), off-system token values (hardcoded hex / ad-hoc shadows), missing interaction states (:focus-visible / :disabled), and named AI slop tells (glassmorphism, gradient orbs, neon glow, default-card). No model needed — all gates are computable. In strict mode, block handoff until this passes.",
+      "Run deterministic slop-audit gates on CSS: APCA contrast (perceptual; WCAG sidecar), off-system token values (hardcoded hex / ad-hoc shadows), missing interaction states (:focus-visible / :disabled + prefers-reduced-motion), and named AI slop tells (glassmorphism, gradient orbs, neon glow, default-card, tracked-out eyebrows, tinted near-black). No model needed — all gates are computable. In strict mode, block handoff until this fails to pass. AUDIT THE COMPLETE STYLESHEET, not fragments. If no contrast pairs are supplied, they are auto-extracted from rules that declare both colour and background.",
     promptSnippet: "Run deterministic UX slop-audit (APCA contrast + tokens + states + slop tells)",
     promptGuidelines: [
       "Contrast, token-coverage, and slop-tells are computable, not judgement — use this tool instead of eyeballing or calling a vision model.",
-      "Pass fg/bg colour pairs (hex or oklch()) + optional weight/size to set the APCA threshold; the WCAG ratio is shown as a compliance sidecar.",
-      "Pass the CSS string to scan for hardcoded hex, ad-hoc box-shadow, and named AI tells (glassmorphism, gradient orbs, neon glow, the shadcn default-card reflex, 1px gray borders).",
+      "Pass fg/bg colour pairs (hex or oklch()) + optional weight/size to set the APCA threshold; the WCAG ratio is shown as a compliance sidecar. Omit pairs and they are auto-extracted from colour+background rules — but hand-picking catches text-on-inherited-backgrounds that auto-extraction misses.",
+      "Audit the COMPLETE stylesheet — fragment input falsely fails the States gate (no interactive selectors present) and misses off-system values elsewhere.",
+      "Pass the CSS string to scan for hardcoded hex, ad-hoc box-shadow, and named AI tells (glassmorphism, gradient orbs, neon glow, the shadcn default-card reflex, 1px gray borders, tracked-out eyebrows, tinted near-black). Transition/animation CSS must ship a prefers-reduced-motion fallback.",
       "State coverage flags interactive elements (button/a/input/...) missing :focus-visible or :disabled rules.",
     ],
     parameters: auditParametersSchema(),
@@ -178,6 +180,12 @@ export default function uxExtension(pi) {
 
   pi.registerCommand("ux", {
     description: `Anti-slop UI/UX discipline. Modes: ${RUNTIME_MODES.join("|")}. Commands: status, default <mode>`,
+    getArgumentCompletions: (prefix) => {
+      const q = String(prefix || "").trim().toLowerCase();
+      const vocab = [...RUNTIME_MODES, "status", "default"];
+      const items = vocab.filter((k) => k.startsWith(q)).map((k) => ({ value: k, label: k }));
+      return items.length > 0 ? items : null;
+    },
     handler: async (args, ctx) => {
       const parsed = parseUxCommand(args, configuredDefaultMode);
 

package/hooks/ux-audit.js

@@ -109,7 +109,10 @@ function apcaContrastLc(textColor, bgColor) {
 
 // APCA threshold for a text/bg pair by font weight + size (px).
 // Spec guidance: Lc 75 body, 60 for 400@18px+, 45 large/bold, 30 non-text.
-function apcaThreshold(weight, size) {
+// Non-text pairs (min: 3 = WCAG "large/UI" floor, no size/weight given) are
+// graphics, not copy — they gate at Lc 30 per the gate table.
+function apcaThreshold(weight, size, isNonText = false) {
+  if (isNonText) return 30;
   const w = typeof weight === 'number' ? weight : 400;
   const s = typeof size === 'number' ? size : 16;
   const bold = w >= 700;
@@ -202,7 +205,16 @@ function scanOffSystem(css, tokens) {
 // ponytail: presence check, not a CSS parser. Stateful /g regexes with
 // .test() flake across calls, so use plain includes().
 function scanStates(css) {
-  const findings = { missingFocusVisible: [], missingDisabled: [] };
+  css = css.replace(/\/\*[\s\S]*?\*\//g, ' '); // dead code must not fail the gate
+  const findings = { missingFocusVisible: [], missingDisabled: [], missingReducedMotion: [] };
+
+  // Motion needs a reduced-motion fallback regardless of interactive elements
+  // (a hero fade-in on a page with no buttons still needs one).
+  // ponytail: deliberately excludes transition-behavior — inert alone.
+  const hasMotion = /transition(?:-(?:property|duration|delay|timing-function))?\s*:|animation(?:-(?:name|duration|delay|timing-function|iteration-count|direction|fill-mode|play-state))?\s*:|@keyframes|scroll-behavior\s*:\s*smooth/i.test(css);
+  if (hasMotion && !css.includes('prefers-reduced-motion')) {
+    findings.missingReducedMotion.push('motion (transition/animation) with no prefers-reduced-motion fallback');
+  }
 
   const hasInteractive =
     /\b(?:button|a|input|select|textarea)\b/i.test(css) || /\[role\s*=\s*"?button"?\]/i.test(css);
@@ -220,6 +232,7 @@ function scanStates(css) {
 // catches and the conservative pattern that must all match.
 
 function scanSlopTells(css) {
+  css = css.replace(/\/\*[\s\S]*?\*\//g, ' '); // dead code must not fail the gate
   const tells = [];
   const lower = css.toLowerCase();
 
@@ -295,23 +308,125 @@ function scanSlopTells(css) {
     tells.push('1px gray card border (border-zinc/gray default or near-gray 1px solid) — the most reliable AI tell');
   }
 
+  // 6. Eyebrow labels — tracked-out ALL-CAPS micro-labels above headings are
+  //    template chrome (anthropics/skills frontend-design). Conservative: only
+  //    flag when text-transform: uppercase, font-size ≤13px AND wide tracking
+  //    (letter-spacing ≥ 0.08em) co-occur in the same block — the "tracked-out"
+  //    part is the slop signature; plain uppercase labels with normal tracking
+  //    are a legitimate table/label style.
+  const ruleRe = /([^{}]+)\{([^}]*)\}/g;
+  let rm2;
+  while ((rm2 = ruleRe.exec(css)) !== null) {
+    const decls = rm2[2].toLowerCase();
+    if (!/text-transform\s*:\s*uppercase/.test(decls)) continue;
+    const fs = decls.match(/font-size\s*:\s*([0-9.]+)(px|rem|em|pt)/);
+    if (!fs) continue;
+    const px = parseFloat(fs[1]) * { px: 1, rem: 16, em: 16, pt: 16 / 12 }[fs[2]];
+    if (px > 13) continue;
+    const ls = decls.match(/letter-spacing\s*:\s*([0-9.]+)(px|rem|em)/);
+    // Threshold is documented in em (≥0.08em) and em scales with the element's
+    // OWN font-size — so normalise every unit to em before comparing.
+    const lsEm = ls
+      ? parseFloat(ls[1]) * (ls[2] === 'em' ? 1 : ls[2] === 'rem' ? 16 / px : 1 / px)
+      : 0;
+    if (lsEm >= 0.08) {
+      tells.push('eyebrow label (tracked-out uppercase at ≤13px, letter-spacing ≥0.08em) — template chrome; try sentence-case micro-labels or weight/colour instead');
+      break;
+    }
+  }
+
+  // 7. Tinted near-black backgrounds — #0B0B0B/#111 standing in for black is
+  //    template chrome. Flag background hex where every channel ≤ 0x14 and the
+  //    channel spread ≤ 3 (a near-neutral tint, not a real colour); pure #000
+  //    is a deliberate choice and stays allowed. colour: declarations are
+  //    exempt — near-black copy text is fine.
+  const bgRe = /background(?:-color)?\s*:\s*[^;}]*#([0-9a-f]{3,4}|[0-9a-f]{6}|[0-9a-f]{8})(?![0-9a-f])/gi;
+  let bm;
+  while ((bm = bgRe.exec(css)) !== null) {
+    const rgb = parseHex('#' + bm[1]);
+    if (!rgb) continue;
+    const max = Math.max(rgb[0], rgb[1], rgb[2]);
+    const spread = max - Math.min(rgb[0], rgb[1], rgb[2]);
+    if (max > 0 && max <= 0x14 && spread <= 3) {
+      tells.push('tinted near-black background (#0B0B0B/#111 standing in for black) — template chrome tell');
+      break;
+    }
+  }
+
   return { tells };
 }
 
+// Contrast pairs auto-extracted from rules that declare both a colour and a
+// background. Var() references resolve through the :root token map. Blocks
+// without an explicit background are skipped — no inherited-bg guessing.
+function extractContrastPairs(css) {
+  const nameToValue = new Map();
+  const rootBlock = /:root\b[^{]*\{([^}]*)\}/g;
+  let rootMatch;
+  while ((rootMatch = rootBlock.exec(css)) !== null) {
+    const declRe = /--([a-zA-Z0-9-]+)\s*:\s*([^;]+);/g;
+    let decl;
+    while ((decl = declRe.exec(rootMatch[1])) !== null) {
+      nameToValue.set('--' + decl[1].trim(), decl[2].trim());
+    }
+  }
+  const resolve = (value) => {
+    let v = value.trim();
+    const varMatch = v.match(/^var\((--[^,)]+)(?:,\s*([^)]*))?\)$/);
+    if (varMatch) v = nameToValue.get(varMatch[1]) || (varMatch[2] || '').trim();
+    return /^#(?:[0-9a-f]{3,4}|[0-9a-f]{6}|[0-9a-f]{8})$|^(?:rgb|hsl)a?\(/i.test(v) ? v : null;
+  };
+
+  const pairs = [];
+  const seen = new Set();
+  const ruleRe = /([^{}]+)\{([^}]*)\}/g;
+  let rm;
+  while ((rm = ruleRe.exec(css)) !== null && pairs.length < 24) {
+    const decls = rm[2];
+    const colorMatch = decls.match(/(?:^|;)\s*color\s*:\s*([^;]+)/);
+    const bgMatch = decls.match(/(?:^|;)\s*(?:background|background-color)\s*:\s*([^;]+)/);
+    if (!colorMatch || !bgMatch) continue;
+    const fg = resolve(colorMatch[1]);
+    const bg = resolve(bgMatch[1].split(' ')[0]);
+    if (!fg || !bg || fg.toLowerCase() === bg.toLowerCase()) continue;
+    // Normalise to rgb triples so #FFFFFF and #fff dedupe to one pair.
+    const keyOf = (c) => { const p = parseColor(c); return p ? `${p[0]},${p[1]},${p[2]}` : c.toLowerCase(); };
+    const key = keyOf(fg) + '|' + keyOf(bg);
+    if (seen.has(key)) continue;
+    seen.add(key);
+    const selector = rm[1].trim().replace(/\s+/g, ' ').slice(0, 40);
+    pairs.push({ fg, bg, label: `auto: ${selector}` });
+  }
+  return pairs;
+}
+
 // --- aggregate gate -------------------------------------------------------
 
 function audit({ css = '', pairs = [] }) {
   const safeCss = typeof css === 'string' ? css : '';
-  const safePairs = Array.isArray(pairs) ? pairs : [];
+  let safePairs = Array.isArray(pairs) ? pairs : [];
   const tokens = extractTokens(safeCss);
   const off = scanOffSystem(safeCss, tokens);
   const states = scanStates(safeCss);
   const tells = scanSlopTells(safeCss);
 
+  // Silent-gap fix: contrast is only checked for hand-supplied pairs, which
+  // callers routinely forget. When none are provided, extract pairs from rules
+  // that declare BOTH a colour and a background (resolved via :root tokens).
+  // Conservative: no inherited-background guessing.
+  let autoPairs = false;
+  if (safePairs.length === 0) {
+    safePairs = extractContrastPairs(safeCss);
+    autoPairs = safePairs.length > 0;
+  }
+
   const contrastResults = safePairs.map((p) => {
     const lc = apcaContrastLc(p.fg, p.bg);
     const ratio = contrastRatio(p.fg, p.bg);
-    const apcaMin = apcaThreshold(p.weight, p.size);
+    // min: 3 with no size/weight signals a non-text graphic (WCAG 3:1 floor);
+    // anything carrying size/weight is copy and uses the text thresholds.
+    const isNonText = p.min === 3 && p.size === undefined && p.weight === undefined;
+    const apcaMin = apcaThreshold(p.weight, p.size, isNonText);
     // pass follows APCA (primary). A pair passes if APCA is present and meets
     // its threshold; if APCA is null (unparseable colour), fail on WCAG.
     let pass;
@@ -332,15 +447,17 @@ function audit({ css = '', pairs = [] }) {
   const contrastPass = contrastResults.every((r) => r.pass);
 
   return {
+    autoPairs,
     gates: {
       contrast: { pass: contrastPass, results: contrastResults },
       tokens: { pass: off.hardcodedHex.length === 0 && off.adhocShadow.length === 0, ...off },
-      states: { pass: states.missingFocusVisible.length === 0 && states.missingDisabled.length === 0, ...states },
+      states: { pass: states.missingFocusVisible.length === 0 && states.missingDisabled.length === 0 && states.missingReducedMotion.length === 0, ...states },
       slopTells: { pass: tells.tells.length === 0, ...tells },
     },
     pass: contrastPass
       && off.hardcodedHex.length === 0 && off.adhocShadow.length === 0
       && states.missingFocusVisible.length === 0 && states.missingDisabled.length === 0
+      && states.missingReducedMotion.length === 0
       && tells.tells.length === 0,
   };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bacnh85/pi-ux",
-  "version": "0.4.4",
+  "version": "0.4.6",
   "description": "Anti-slop UI/UX design discipline for your Pi agent — anchors a lintable DESIGN.md, runs deterministic slop-audit gates (APCA contrast + tokens + states + slop tells), works with text-only models, ships reference design-system presets.",
   "keywords": [
     "pi-package",

package/skills/ux-capture/SKILL.md

@@ -0,0 +1,29 @@
+---
+name: ux-capture
+description: >
+  Capture playbook for the pi-ux render-and-inspect loop: screenshotting a UI
+  you just built via local headless Chrome vs web_screenshot, daemon
+  reachability (localhost vs LAN IP vs host.docker.internal), SSRF-protected
+  daemons, and cloudflared tunnels. Load when setting up render inspection or
+  when a UI screenshot capture fails.
+---
+
+# UX Capture Playbook
+
+Judge captures at viewer resolution (1×–3×); never chase sub-visible precision.
+
+## Default — local capture (offline, no daemon)
+
+Headless Chrome writes the PNG; the `read` tool shows it inline (multimodal models see it).
+
+- Linux: `google-chrome --headless --screenshot=/tmp/shot.png --window-size=1280,800 http://localhost:PORT` (or `chromium`)
+- macOS: `"/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" --headless --screenshot=/tmp/shot.png --window-size=1280,800 http://localhost:PORT`
+
+## Alternative — web_screenshot (daemon-rendered, pi-web 0.6.2+)
+
+The screenshot URL is navigated by the DAEMON's browser, so addresses must resolve on the daemon host:
+
+- Reachable: your machine's LAN IP, or `host.docker.internal` for a Dockerized daemon.
+- Plain localhost/file:// only for a daemon you *know* runs natively on this machine — `web_status` can't tell you (a Dockerized daemon on a published port also shows 127.0.0.1 + healthy but cannot see your localhost).
+- SSRF-protected daemons (common) block private/localhost URLs outright — failures say "URL blocked (SSRF protection)".
+- Last resort: a temporary public tunnel (`cloudflared tunnel --url http://localhost:PORT`) when the remote daemon must render the page; quick tunnels are often flaky. If all capture paths fail, fall back to the deterministic `ux_audit` gates only.

package/skills/ux-design/SKILL.md

@@ -6,8 +6,9 @@ description: >
   detail, as little design as possible) so output is a defensible system, not
   statistical-default slop (purple glow, shadow-as-texture, missing states).
   Covers the Constraint-First method: own the system via a lintable DESIGN.md,
-  write a 5-field brief, generate inside constraints, normalise, pass a
-  measurable slop-audit gate. Works deterministically with text-only models
+  write a 5-field brief, generate inside constraints, normalise, render-and-inspect
+  with vision (multimodal models see their own output), pass a measurable slop-audit
+  gate. Works deterministically with text-only models
   (DeepSeek-v4, GLM-5.2, Kimi K3); agy/Gemini/Claude is optional polish, never
   the review gate. Use when designing or building any UI — web, mobile, or
   desktop. Active via /ux lite|strict|off.
@@ -28,7 +29,7 @@ is anchored by a repo-root **DESIGN.md** that every generation reads.
 - **Accent:** ONLY the defined accent token. No purple/indigo gradients. No glow unless explicitly requested. (Glow is the #1 AI-slop signature.)
 - **Type:** modular scale only (e.g. 1.25 ratio). No custom font sizes.
 - **Spacing:** 8px grid via tokens. No magic pixel values.
-- **States:** every interactive element declares `default`, `hover`, `focus-visible`, `active`, `disabled` + `error`/`empty`/`loading` where relevant.
+- **States:** every interactive element declares `default`, `hover`, `focus-visible`, `active`, `disabled` + `error`/`empty`/`loading` where relevant. Anything that moves respects `prefers-reduced-motion`.
 - **Inventory first:** before writing markup, output a 1-line inventory of components + states you will produce.
 - **Ambiguity = ask.** If a requirement is ambiguous, ASK. Do not guess aesthetics.
 
@@ -51,13 +52,14 @@ deterministic gate and the agent both read.
 **Resolution order (stop at the first that holds):**
 1. **Repo-root `DESIGN.md` exists** → read it; use its tokens verbatim. This is the happy path.
 2. **An existing system is already wired in** (shadcn/MUI/Radix theme, Tailwind config) → reuse it — YAGNI applies to design systems too.
-3. **Nothing exists** → do NOT block. Pick a **medium-tuned preset** from the `ux-presets` skill (B1 Web vs B2 Mobile — infer from the task; **ASK only if web-vs-mobile is genuinely unclear**, because it changes touch targets, hover, and safe areas). Use the preset **in-context as the implicit system** for this generation, then offer to persist it to repo-root `DESIGN.md` so future sessions reuse it (don't auto-write — that's an unrequested file mutation).
-4. **No preset fits** → generate a DESIGN.md once with `agy_execute mode=plan pro-high` (Gemini); thereafter text-only models are sufficient.
+3. **A reference site exists** (brand to match, look to echo) → `web_extract` it and distill its design DNA (4–6 core hex, type roles, radius/spacing rhythm) into a DESIGN.md starter, lint it, then work inside it.
+4. **Nothing exists** → do NOT block. Pick a **medium-tuned preset** from the `ux-presets` skill (B1 Web vs B2 Mobile — infer from the task; **ASK only if web-vs-mobile is genuinely unclear**, because it changes touch targets, hover, and safe areas). Use the preset **in-context as the implicit system** for this generation, then offer to persist it to repo-root `DESIGN.md` so future sessions reuse it (don't auto-write — that's an unrequested file mutation).
+5. **No preset fits** → generate a DESIGN.md once with `agy_execute mode=plan pro-high` (Gemini); thereafter text-only models are sufficient.
 
 The non-negotiables a preset/system must define before any screen is written:
 - **Tokens:** colour (one accent + neutrals), type scale, spacing (8px grid), radius, elevation.
 - **Elevation scale:** 3–5 named levels only. Map every shadow to one.
-- **State contract:** every interactive component declares all states (web: + `:hover`/`:focus-visible`; mobile: + `:active`/pressed, NO hover).
+- **State contract:** every interactive component declares all states (web: + `:hover`/`:focus-visible`; mobile: + `:active`/pressed, NO hover); motion ships with a `prefers-reduced-motion` fallback.
 
 **Lint the system (when persisted to disk):**
 ```bash
@@ -73,15 +75,34 @@ All five are required. If you can't produce inventory + states with confidence,
 4. **Required interaction states** per interactive component.
 5. **One reference** screen/component that already feels like the product (brand tone).
 
+**Generic-default check (before building):** if there is no DESIGN.md, sketch a mini plan first — 4–6 named hex, type roles, a one-line layout concept or ASCII wireframe, one principle. Then ask: *would I produce this same plan for any similar brief?* Every part that answers yes is a default, not a choice — revise it and say what changed.
+
+**Scale to the task:** internal single-file tools → one-line brief + one draft is fine; user-facing product UI → full brief + 2–3 variants. The gates are the same either way.
+
 ### Step 2 — Generate fast, converge early
 Generate several variants, commit early to the direction with the clearest hierarchy under real content.
+- **Variants are files, not vibes:** write 2–3 drafts as separate HTML files (`.ux/drafts/<slug>-{a,b,c}.html`), screenshot each, view the images side by side, and commit to one direction before touching real code. When redesigning existing UI, first capture a BEFORE screenshot of the current page as reference context.
 - **Convergence trigger:** after two generate-revise loops, variants must visibly converge toward your constraints. If they don't, tighten the brief first — prompting forever compounds drift.
 
 ### Step 3 — Normalise the draft into the system
 Replace ad-hoc colours with tokens, remap shadows to the elevation scale, snap spacing to the rhythm, turn one-offs into component variants.
 - Gate: sample 10 components, verify token mapping. If fewer than 8 map cleanly, stop and repair the baseline.
 
-### Step 4 — Slop-audit gate (blocks handoff on fail)
+### Step 4 — Render & Inspect (vision verify — multimodal models)
+
+The deterministic gates check CSS text; they never see the page. When the
+generating model is multimodal (GLM-5.3, Claude, Gemini), close the
+loop with eyes — this is the single biggest quality lever for flash-tier
+models:
+
+1. **Reference-first.** If the task gives a URL or screenshot as the design target, capture it with `web_screenshot` (pi-web 0.6.2+ returns the PNG inline) BEFORE generating. Every visual judgment is made against that reference.
+2. **Inspect your own build.** Serve the UI (dev server or `python3 -m http.server`), then capture and LOOK — default: local headless Chrome + `read` (renders inline; commands in the `ux-capture` skill; offline, no daemon); alternative: `web_screenshot` (pi-web 0.6.2+) at a daemon-reachable address (full playbook in `ux-capture`). Fix what regex gates can't see: broken layout, weak hierarchy, spacing rhythm, brand fit. Batch fixes, re-screenshot, stop when converged (same 2-loop trigger as Step 2).
+3. **Visibility baseline.** Judge at what a viewer sees at 1×–3×. Nothing sub-visible can fail, and nothing sub-visible may be produced — no ±1px claims, no per-pixel diffs, no instrument-read values on either side.
+4. **Gates stay final.** `ux_audit` (Step 5) remains the blocking authority; vision settles only what looking can settle.
+
+Text-only models, or no capture path at all (no headless Chrome, no reachable `web_screenshot`) → skip this step; the deterministic gates are the whole loop.
+
+### Step 5 — Slop-audit gate (blocks handoff on fail)
 
 Run `ux_audit` on the generated CSS. The contrast gate reports **APCA Lc**
 (perceptual, primary — Lc ≥75 body / ≥45 large-bold / ≥30 non-text) with a
@@ -94,9 +115,9 @@ tells (glassmorphism, gradient orbs, neon glow, default-card).
 | Token coverage | ≥8/10 components map to tokens | Pause, repair baseline |
 | Shadow recipes | ≤3 named recipes on core surfaces | Collapse to named elevations |
 | Contrast (APCA) | Lc ≥75 body, ≥45 large-bold, ≥30 non-text (WCAG sidecar shown) | Block handoff until fixed |
-| State coverage | all interactive elements have focus + disabled | Keep in draft |
+| State coverage | all interactive elements have focus + disabled; any transition/animation ships a prefers-reduced-motion fallback | Keep in draft |
 | Component hygiene | no duplicates, no frame-pile | Refactor before handoff |
-| Slop tells | no glassmorphism / orbs / glow / default-card / 1px-gray-border | Refactor: space → bg shift → elevation before a border |
+| Slop tells | no glassmorphism / orbs / glow / default-card / 1px-gray-border / tracked-out eyebrow / tinted near-black bg | Refactor: space → bg shift → elevation before a border |
 
 ## Model routing (who does what)
 
@@ -115,6 +136,7 @@ never the review gate.
 | **Per-screen brief** | Main Pi model: **GLM-5.2** | 1M ctx holds the whole DESIGN.md while scoping one screen |
 | **Generate variants** | Main Pi model: **DeepSeek-v4**, **GLM-5.2**, or **Kimi K3** | Text-only models lead frontend inside a locked system; cheaper than vision calls. |
 | **Normalise into system** | Main Pi model: **DeepSeek-v4** or **GLM-5.2** | Long context, token remapping, mechanical precision |
+| **Render & inspect** | The generating model itself, when multimodal (GLM-5.3, Claude, Gemini) via `web_screenshot` | Eyes on your own output beat rules in a prompt — flash-tier models produce notably better UI when they see the rendered result (inline image blocks) |
 | **Slop audit** | `ux_audit` tool (deterministic) + DESIGN.md lint | Contrast (APCA) + token coverage + slop tells are computable, not judgement |
 | **Optional polish** (never a gate) | `agy_execute mode=accept-edits sonnet` (Claude) or `opus` | Only if brand-fit is uncertain after the deterministic gate passes. NOT required. |
 
@@ -137,3 +159,21 @@ screen stays in draft until refactored.
 - Magic pixel values; off-scale font sizes; ad-hoc accent colours.
 - Shipping a component without `focus-visible` + `disabled` states.
 - Prompting "make it modern/clean" with no DESIGN.md — the single biggest slop trigger.
+
+### Named cliché clusters (credit: anthropics/skills frontend-design)
+All legitimate for *some* briefs — but they are defaults, not choices, and appear regardless of subject. Where the brief pins a direction, follow it exactly; where an axis is free, don't spend it here:
+
+- **The cream-clay look** — warm cream bg (near `#F4F1EA`) + high-contrast serif display + terracotta accent (near `#D97757`); on anyone else's brief it reads as Claude-flavoured.
+- **Acid on black** — near-black background + single acid-green/vermilion accent.
+- **Broadsheet kit** — hairline rules, zero border-radius everywhere, dense newspaper columns.
+- **The SaaS-card kit** — identical rounded cards, one radius for everything, the same soft shadow under each, gradient washes as decoration.
+- **Template chrome** — tracked-out ALL-CAPS eyebrow above every heading; meta strings joined with middle dots (`A · B · C`); `WORD — fragment` labels; tinted near-black (`#0B0B0B`, `#111`) standing in for black; monospace for small data labels; `→` appended to links/buttons.
+
+## Taste rules
+
+- **Ground it in the subject.** Distinctive choices come from the brief's industry, materials, and vernacular — a toy for kids and a trading dashboard should not share a visual language. If the subject is unclear, confirm it before designing.
+- **Typography carries personality.** Choose typefaces deliberately per project (1–2 families, clearly distinct roles); body lines under ~80 chars. Never accent a single word of a headline; no ALL-CAPS labels by default; structural devices (numbers, rules, eyebrows) only when they encode real information — `01 / 02 / 03` is for actual sequences.
+- **Motion: one orchestrated moment.** A single page-load sequence or reveal lands better than effects scattered everywhere; fade-and-slide-up on every section is an AI tell. Motion that answers an action (opening, confirming) is welcome. Always ship a `prefers-reduced-motion` fallback.
+- **Design writing is design.** Use the user's words, not system words ("notifications", not "webhook config"). CTAs say what happens ("Save changes", not "Submit"); one name per action across the flow. Errors direct instead of apologising; empty states invite action.
+- **Spend boldness in one place.** One memorable element; everything around it quiet and disciplined. Quality floor without announcing it: responsive, visible keyboard focus, reduced motion, accessible contrast.
+- **Data-viz rules (dashboards & charts).** Chart fills must pass non-text contrast (≥3:1) against their track. Adjacent categorical fills must be nameably different, not opacity steps; cap ramps at 7. Secondary series ≤0.85 opacity or a muted token; today/selected gets full accent. Numeric cells get `font-variant-numeric: tabular-nums`. Empty/zero chart states show an axis or "no data" slot, never a blank canvas. Tables: row hover on bg, right-aligned numerics, sentence-case headers.