@bacnh85/pi-ux 0.4.7 → 0.6.0

package/CHANGELOG.md

@@ -1,5 +1,123 @@
 # Changelog
 
+## 0.6.0 (2026-09-17)
+
+### Added
+
+- **`ux_audit` accepts `path`** — audit a CSS file verbatim (absolute or
+  cwd-relative) instead of retyping it into the `css` string. Incident-driven:
+  retyped/condensed CSS drifted (inlined DESIGN.md shadow values, mislabeled
+  colour pairs) and produced false gate failures and false confidence.
+  Exactly one of `path`/`css`; the tool guidance now leads with
+  "NEVER retype CSS when the file is on disk".
+
+### Changed
+
+- **ux-capture skill**: new Interaction section — `web_interact` (pi-web
+  ≥0.16.0) as the default path for behavior verification, with the manual CDP
+  recipe (trusted input, double-unwrap, clipboard activation caveats) as
+  fallback; honest sub-500px capture + `reduced_motion` documented as native
+  pi-web behavior; the iframe-wrapper layout probe demoted to a manual-capture
+  fallback.
+- **ux-design skill** Step 4: render-and-inspect loop gains "Interact &
+  verify" — click the primary CTA, submit the form, read back state with
+  `web_interact` before the audit gate.
+
+## 0.5.0 (2026-09-16)
+
+### Added
+
+- **Step 1.5 — Derive a direction** in the ux-design skill: the positive
+  counterpart to the guardrail. From the brief's subject material, commit —
+  before any markup — to mood adjectives, a one-line visual concept, a type
+  voice, a color mood (hex), and exactly one signature element. Test for a
+  real direction: two different designers following it must produce visibly
+  different pages. Replaces the passive generic-default check.
+- **Direction playbook** (injected, ux-design): the positive layer the skill
+  previously lacked. Typography-voice pairing table (editorial → Newsreader +
+  Source Sans 3, ledger → Spline Sans pair, technical → IBM Plex pair, warm
+  consumer → DM Sans, …) with off-table alternatives; color-mood construction
+  (temperature first, every neutral tinted, committed accent posture, band
+  rhythm); composition anatomy (hierarchy by scale/weight/color, hero formula,
+  rows-over-card-grids, shaped whitespace, depth via composition); the
+  signature element how-to; default-vs-directed contrast snippets.
+- **Step 4 render-inspect is REQUIRED in strict mode** for multimodal models,
+  with a concrete LOOK checklist (squint test, dead zones, monotony, timidity
+  — "cover the logo, could this page belong to anyone?", type sizes, mood
+  visibility) instead of the previous "fix what regex gates can't see".
+- **Style-direction starters** in ux-presets (Option B+): S1 Editorial print
+  (Newsreader + Source Sans 3, paper/ink/oxblood), S2 Ledger (Spline Sans
+  pair, desk/rule/tabular-nums, stamp badges), S3 Warm consumer (DM Sans,
+  linen/basil, category spines, freshness badges). All color pairs verified
+  against the shipped APCA implementation (Lc ≥75 body, ≥60 small-bold
+  badges). B1/B2 remain as neutral fallbacks.
+- **`ux-routing` skill** — the model-routing table moved out of the injected
+  body into a consult-when-delegating reference skill (offsets the added
+  injection weight; routing prose was irrelevant to most non-delegating
+  turns).
+- **`bench/` design-quality harness**: three fixed briefs (landing page,
+  dashboard, mobile screen), `run.sh` (headless pi run with pinned model +
+  screenshot capture at desktop/mobile widths), and a fixed six-axis rubric
+  (hierarchy, composition, typography, color/mood, copy, feel). Results are
+  gitignored; see bench/README section in the main README.
+- **ux-capture: layout probe + viewport-truth section.** Headless Chrome
+  clamps window width to 500px, so a `--window-size=390` capture renders at
+  500 and crops the PNG — right-edge "cuts" that aren't in your CSS. The
+  skill now documents the clamp and prescribes a 390×844 iframe-wrapper probe
+  (an iframe is a true 390px CSS viewport) that measures
+  `scrollWidth`/viewport honestly on the delivered file. Capturing mobile via
+  the wrapper is also required: never widen a viewport to make a problem
+  invisible.
+- **ux-capture: capture with entrance animations disabled**
+  (`--force-prefers-reduced-motion`). Staggered page-load reveals with
+  `opacity:0` backwards-fill screenshot as blank sections otherwise — the
+  forced query doubles as a reduced-motion audit (every section must remain
+  fully readable with animations off).
+- **ux-design LOOK checklist** is now pinned to the brief's target viewport,
+  with an explicit dead-zone check for app screens (content must not leave a
+  large empty region below the last element at the target height).
+- **Polish pass (critic-driven):** a glm-5.3-flash calibration review against
+  a reference-grade page named five half-point gaps; each became a rule in
+  the Direction playbook — display scale floor (h1 ≥ clamp(2.75rem, 7vw,
+  6.75rem), 3–4× body), signature elements at composition scale (≥25vw,
+  edge-bleeding, reduced contrast), a three-surface color budget (header
+  inherits the base), repeating rows as fixed column grids with a shared
+  terminal axis, and a 2–3-mark "punctuation kit" (accent H1 terminal,
+  framed pull quotes, stamps, texture glyphs — placeholder monograms banned).
+
+### Changed
+
+- Step 0 rung 4 reframed: a preset is a **floor, not an identity** — after
+  dropping one in, the direction step must still bend display face, neutrals,
+  and accent until the page could not be mistaken for the stock preset.
+- Step 5 gate table now lists exactly what `ux_audit` implements (contrast /
+  tokens / states+motion / slop tells); the unimplemented rows (token
+  coverage, shadow recipes, component hygiene) are documented as model-side
+  checks instead of implying mechanical enforcement.
+- ux_audit tool description fixed: "block handoff until this fails to pass"
+  → "handoff is blocked until this passes".
+
+### Why
+
+Field benchmarking (`bench/`, glm-5.3-flash, three briefs, fixed rubric —
+hierarchy / composition / typography / color-mood / copy / feel, 1–5 each)
+showed the 0.4.x skill produced correct-but-forgettable pages: ~70% of the
+injected guidance was prohibitions, so the model played safe (uniform
+sections, no signature, cream-clay/broadsheet cliché drift on landing pages).
+Discipline without direction is half the method; 0.5.0 ships the other half.
+
+**Measured:** baseline 0.4.7 = 60.5/90 → 0.5.0 = 79.5/90 (+19); after the
+critic-driven polish pass, **landing = 29.5 and 29 on two consecutive runs
+(goal ≥29)**, run total 84/90, and three new case types (portfolio, pricing,
+settings-form) scored 28–28.5 on first try — all 15 scored pages pass
+`ux_audit`, and a non-UI task with pi-ux active shows zero derailment.
+Winning directions each run were distinct and subject-grounded (alpine
+expedition log with route-card signature; white/ink/vermilion with an
+elevation-profile card; forest-green badge-stamp identity; ink-ledger
+dashboard with OVERDUE stamps; grocer's stock-card mobile screen; printed
+monograph portfolio). Per-run evidence in `bench/results/*/SCORES.md`
+(gitignored; scores reproduced here).
+
 ## 0.4.7 (2026-09-12)
 
 ### Fixed

package/README.md

@@ -1,10 +1,10 @@
 # pi-ux
 
-Anti-slop UI/UX design discipline for the [Pi coding agent](https://pi.dev). Anchors a lintable **DESIGN.md**, runs **deterministic** slop-audit gates (APCA contrast + tokens + states + slop tells), and works **with text-only models** (DeepSeek-v4, GLM-5.2, Kimi K3) — `agy`/Gemini/Claude is optional polish, never the review gate.
+Anti-slop UI/UX design discipline for the [Pi coding agent](https://pi.dev). Anchors a lintable **DESIGN.md**, **derives a design direction** (mood, type voice, color mood, signature element) from the subject, runs **deterministic** slop-audit gates (APCA contrast + tokens + states + slop tells), and works **with text-only models** (DeepSeek-v4, GLM-5.2, Kimi K3) — `agy`/Gemini/Claude is optional polish, never the review gate.
 
 ## Why
 
-AI-generated UI converges on the same defaults — purple/indigo glow, shadow-heavy cards, missing focus/disabled/error states — because under vague direction, models reach for high-frequency statistical patterns. Slop is an **ownership problem**: "the design has no owner at the system level." The fix is shift-left: own the system in a DESIGN.md, then gate deterministically.
+AI-generated UI fails in two directions. Without discipline it converges on slop — purple/indigo glow, shadow-heavy cards, missing focus/disabled/error states. Without direction it converges on the *correct but forgettable* default — Inter, a blue accent, white cards, timid sizes — which passes every lint and still has no feel, because under vague direction models reach for high-frequency statistical patterns either way. The fix is both halves: **own the system** in a DESIGN.md, **derive a direction** from the subject, then gate deterministically.
 
 **Text-only models now lead frontend** (Kimi K3, an open MIT model, is #1 on the Arena.ai Frontend Code Arena, ahead of Claude Fable 5). Inside a fully-specified system they produce non-slop UI — which means the review gate can be mechanical, not a vision-LLM call.
 
@@ -45,23 +45,27 @@ The injected skill enforces **Constraint-First Design Generation**:
    ```bash
    npx @google/design.md lint DESIGN.md
    ```
-   If absent, reuse a preset (`ux-presets` skill: shadcn/Material/Radix) or scaffold one once. pi-ux orchestrates `@google/design.md` via shell-out — **not** a runtime dependency.
+   If absent, reuse a preset or style-direction starter (`ux-presets` skill: shadcn/Material/Radix; S1 Editorial print / S2 Ledger / S3 Warm consumer) or scaffold one once. Presets are floors, not identities. pi-ux orchestrates `@google/design.md` via shell-out — **not** a runtime dependency.
 1. **5-field brief per screen** — user job, inventory, token constraints, required states, one reference.
+1.5. **Derive a direction** — from the subject's material, commit to mood adjectives, a one-line visual concept, a type voice (pairing table), a color mood (hex), and one signature element — before any markup. The test: two different designers following the direction must produce visibly different pages.
 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. **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.
+4. **Render & Inspect** (multimodal models; required in strict mode) — reference-first capture, then screenshot your own build and LOOK against a concrete checklist (squint test, dead zones, monotony, timidity, type, mood). 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. 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 **Direction playbook** ships in the skill as the positive layer: a typography-voice pairing table (editorial → Newsreader + Source Sans 3, ledger → Spline Sans pair, …), color-mood construction (temperature, tinted neutrals, committed accent posture, band rhythm), composition anatomy (hero formula, rows-over-card-grids, shaped whitespace), the signature element, and default-vs-directed contrast snippets. Taste rules add the named cliché clusters (the cream/terracotta "Claude look", acid-on-black, broadsheet kit, SaaS-card kit, template chrome), typography-as-personality, one-orchestrated-motion, and design-writing rules.
 
 ## The `ux_audit` tool
 
 Deterministic slop-audit — no model needed, all gates are computable:
 
 ```
-ux_audit css="..." pairs=[{fg:"#111",bg:"#fff",label:"body",weight:400,size:16,min:4.5}]
+ux_audit path="web/src/app.css" pairs=[{fg:"#111",bg:"#fff",label:"body",weight:400,size:16,min:4.5}]
+ux_audit css="..." pairs=[...]
 ```
 
+Pass `path` to a stylesheet file — it is audited **verbatim**. Never retype or condense CSS into the `css` string when the file is on disk: retyped copies drift (inlined tokens, mislabeled pairs) and cause false gate failures or false confidence. Exactly one of `path`/`css`.
+
 | Gate | What it checks |
 |------|----------------|
 | **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. |
@@ -75,25 +79,18 @@ Returns pass/fail per gate + a formatted report. In `strict` mode this is the ga
 
 ## Model routing (deterministic-first)
 
-The skill tells the agent which model to use for each step. The gate is mechanical, not a vision-LLM call:
-
-| Step | Best tool/model |
-|------|-----------------|
-| Define system (DESIGN.md) | Reuse a preset OR `agy_execute mode=plan pro-high` (Gemini) **once** |
-| Lint system | `npx @google/design.md lint DESIGN.md` (shell-out) |
-| Per-screen brief | **GLM-5.2** (1M ctx) |
-| Generate variants | **DeepSeek-v4**, **GLM-5.2**, or **Kimi K3** (text-only, inside constraints) |
-| Normalise into system | **DeepSeek-v4** or **GLM-5.2** |
-| Slop audit | `ux_audit` tool (deterministic) + DESIGN.md lint |
-| Optional polish (never a gate) | `agy_execute mode=accept-edits sonnet` (Claude) |
-
-**The inversion rule:** the cheaper/weaker the model, the MORE you must externalise constraints. **The deterministic-first principle:** don't spend vision-model quota on what `ux_audit` computes for free.
+The full who-does-what table lives in the **`ux-routing`** skill (not injected — consulted when delegating). The gate is mechanical, not a vision-LLM call. **The inversion rule:** the cheaper/weaker the model, the MORE you must externalise constraints. **The deterministic-first principle:** don't spend vision-model quota on what `ux_audit` computes for free.
 
 ## Skills
 
-- **`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-design`** — the Constraint-First method + Direction playbook (auto-injected by the hook when active).
+- **`ux-presets`** — reference presets for Step 0: neutral Web/Mobile DESIGN.md starters, three style-direction starters (S1 Editorial print, S2 Ledger, S3 Warm consumer — APCA-verified pairs), 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.
+- **`ux-routing`** — the model-routing table for delegating design steps (Define/Generate/Inspect/Audit) across agy/Gemini, Claude, DeepSeek, GLM, Kimi. Not injected.
+
+## Benchmark
+
+`bench/` holds a design-quality harness: three fixed briefs (landing, dashboard, mobile), `run.sh` (headless `pi` run with the same model + screenshot capture), and a fixed scoring rubric. Used to measure output quality across pi-ux versions; results are gitignored.
 
 ## Configuration
 

package/extensions/index.js

@@ -1,4 +1,6 @@
 import { createRequire } from "node:module";
+import fs from "node:fs";
+import path from "node:path";
 
 const require = createRequire(import.meta.url);
 const {
@@ -67,9 +69,13 @@ function auditParametersSchema() {
     type: "object",
     additionalProperties: false,
     properties: {
+      path: {
+        type: "string",
+        description: "Path to a CSS stylesheet file to audit verbatim (absolute or cwd-relative). PREFERRED over retyping `css` — retyped copies drift (inlined tokens, mislabeled pairs) and cause false audit failures. Exactly one of path/css.",
+      },
       css: {
         type: "string",
-        description: "CSS stylesheet content to audit (inline stylesheets, styled-components output, or a concatenated .css file).",
+        description: "CSS stylesheet content to audit (inline stylesheets, styled-components output, or a concatenated .css file). Prefer `path` for on-disk files. Exactly one of path/css.",
       },
       pairs: {
         type: "array",
@@ -92,6 +98,23 @@ function auditParametersSchema() {
   };
 }
 
+/**
+ * Resolve the stylesheet to audit: a file `path` read verbatim (preferred —
+ * retyped `css` drifts and causes false gate failures) or inline `css`.
+ * Exactly one of the two.
+ */
+export function resolveAuditCss(params, cwd) {
+  const css = typeof params.css === "string" ? params.css : "";
+  const hasCss = css.trim().length > 0;
+  const p = typeof params.path === "string" ? params.path.trim() : "";
+  if (hasCss && p) throw new Error("Pass exactly one of `path` or `css` — not both.");
+  if (!hasCss && !p) throw new Error("Pass a stylesheet to audit: `path` (preferred, read verbatim) or `css`.");
+  // Relative paths resolve against the tool-call cwd (falls back to the
+  // process cwd) — the session cwd can differ from this process's cwd.
+  if (p) return fs.readFileSync(path.resolve(cwd || process.cwd(), p), "utf8");
+  return css;
+}
+
 export function formatAuditResult(result) {
   const lines = [];
   lines.push(result.pass ? "✅ UX AUDIT PASSED" : "❌ UX AUDIT FAILED");
@@ -170,9 +193,10 @@ 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 + 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.",
+      "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, handoff is blocked until this passes. 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: [
+      "Pass `path` to the stylesheet file — it is audited verbatim. NEVER retype or condense CSS into the `css` string when the file is on disk: retyped copies drift (inlined DESIGN.md shadow values, mislabeled pairs) and produce false failures or false confidence.",
       "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. 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.",
@@ -180,8 +204,8 @@ export default function uxExtension(pi) {
       "State coverage flags interactive elements (button/a/input/...) missing :focus-visible or :disabled rules.",
     ],
     parameters: auditParametersSchema(),
-    async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
-      const css = typeof params.css === "string" ? params.css : "";
+    async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+      const css = resolveAuditCss(params, ctx?.cwd);
       const pairs = Array.isArray(params.pairs) ? params.pairs : [];
       const result = audit({ css, pairs });
       return {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@bacnh85/pi-ux",
-  "version": "0.4.7",
-  "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.",
+  "version": "0.6.0",
+  "description": "Anti-slop UI/UX design discipline for your Pi agent — anchors a lintable DESIGN.md, derives a design direction (mood, type voice, color mood, signature), runs deterministic slop-audit gates (APCA contrast + tokens + states + slop tells), works with text-only models, ships reference design-system presets.",
   "keywords": [
     "pi-package",
     "pi",

package/skills/ux-capture/SKILL.md

@@ -12,20 +12,140 @@ description: >
 
 Judge captures at viewer resolution (1×–3×); never chase sub-visible precision.
 
-## Default — web_screenshot (pi-web ≥0.7.0, auto local detection)
+**Disable entrance animations when capturing**: pass `reduced_motion=true` to
+`web_screenshot` / `web_interact` (pi-web ≥0.16.0), or add
+`--force-prefers-reduced-motion` to manual headless Chrome (or emulate the media
+query). Pages rightly use staggered page-load reveals with `opacity:0`
+backwards-fill — captured mid-animation they screenshot as blank sections,
+and you will "fix" content that isn't broken. The same forced query doubles
+as a reduced-motion audit: with animations off, every section must still be
+fully visible and readable.
+
+**Capture at the brief's target viewport.** Web pages: 1280–1440 wide. App
+screens and mobile-first briefs: the width the brief names (usually 390) at
+its target height (~844). pi-web handles this honestly now: `web_screenshot`
+and `web_interact` with `width`/`viewport` below 500px automatically use CDP
+device-metrics emulation (true 390px CSS viewport) and return a
+`scrollWidth`/`innerWidth` probe — `scrollWidth > width` means overflowing CSS.
+If you fall back to manual headless Chrome, know its trap: many builds
+**clamp window width to 500px**, so a "390 capture" secretly renders at 500
+and crops (see the layout probe below for the wrapper that does it honestly).
+If content overflows or dead-ends at the target size, the page is broken —
+**fix the page. Never widen the viewport to make a problem invisible.**
+
+## Interaction — web_interact (pi-web ≥0.16.0)
+
+A screenshot proves the page LOOKS right; only interaction proves it WORKS.
+After visual inspection, verify behavior with `web_interact` — one call = one
+browser lifecycle: open `url`, run `steps` in order, get per-step results, a
+final inline PNG, and a scrollWidth probe.
+
+```text
+web_interact url="http://localhost:5173" viewport={width:390,height:844} \
+  reduced_motion=true grant=["clipboard-read","clipboard-write"] steps=[
+  {click: "#copy-btn"},
+  {evaluate: "document.getElementById('status').textContent", label: "status"},
+  {type: {selector: "#email", text: "a@b.co"}},
+  {press: "Enter"},
+  {wait_for: "[data-success]"}
+```
+
+- **Trusted clicks**: steps click via CDP `Input.dispatchMouseEvent` at the
+  element's center — synthetic `el.click()` grants no user activation, so
+  `document.execCommand('copy')` and login/clipboard flows would silently fail
+  under it. Under a trusted click, copy returns true.
+- **evaluate is double-unwrapped**: `Runtime.evaluate` nests the value at
+  `{result:{result:{value}}}` — the tool returns the real value; if you ever
+  hand-roll CDP, single-unwrapping yields `undefined` and makes the app LOOK
+  broken when it isn't.
+- Steps stop at the first failure with the reason — a broken selector surfaces
+  loudly instead of no-op'ing later steps.
+- Clipboard readback on insecure origins: there is no clipboard API to read
+  back with; `execCommand` returning true under a trusted click is the
+  strongest available signal (grant permissions for secure origins).
+
+Manual CDP (fallback only, when web_interact is unavailable): launch Chrome
+with `--remote-debugging-port=0`, read `<profile>/DevToolsActivePort` for the
+ws URL, create targets over the websocket (`Target.createTarget` — not the
+`/json/new` HTTP endpoint, whose method flipped to PUT), attach with
+`flatten: true`.
+
+## Layout probe (fallback for manual captures)
+
+Needed only when CDP tooling above is unavailable. Two Chrome facts make naive mobile checks lie:
+
+1. **Headless Chrome clamps window width to 500px.** A `--window-size=390`
+   capture renders the page at 500px and crops the PNG to 390 — cuts at the
+   right edge are the CROP, not your CSS. Detect it:
+   `--dump-dom` a page containing `window.innerWidth` — 500 at a 390 request
+   means clamped.
+2. `window.innerWidth` therefore never reports the true mobile viewport.
+
+The honest way to see and measure a 390px screen: a **wrapper page with a
+390×844 iframe** (an iframe IS a true 390px CSS viewport, immune to the
+clamp), rendered at a 500px window with `--allow-file-access-from-files`:
+
+```bash
+cp index.html /tmp/page.html
+cat > /tmp/wrapper.html <<'EOF'
+<!DOCTYPE html><html><head><meta charset="utf-8"><style>
+body{margin:0;background:#888}#frame{width:390px;height:844px;border:0;outline:2px solid #000}
+</style></head><body>
+<iframe id="frame" src="./page.html"></iframe>
+<pre id="out">measuring…</pre>
+<script>
+const f=document.getElementById('frame');
+f.addEventListener('load',()=>{
+  const d=f.contentDocument;
+  document.getElementById('out').textContent=
+    'page scrollWidth:'+d.documentElement.scrollWidth+' / viewport:390';
+});
+</script>
+</body></html>
+EOF
+"$CHROME" --headless --disable-gpu --allow-file-access-from-files \
+  --virtual-time-budget=6000 --window-size=500,900 \
+  --screenshot=/tmp/mobile-390.png "file:///tmp/wrapper.html"
+"$CHROME" --headless --disable-gpu --allow-file-access-from-files \
+  --virtual-time-budget=6000 --window-size=500,900 \
+  --dump-dom "file:///tmp/wrapper.html" | grep -o 'page scrollWidth:[^<]*'
+```
+
+**Pass = scrollWidth 390 / viewport:390**, and the screenshot shows the true
+mobile render (grey letterbox on the right is the wrapper, not your page).
+If scrollWidth exceeds 390, fix the CSS (min-width on rows/grid, an
+unbreakable string, a fixed-width column) and probe again — on the delivered
+file, after the last edit.
+
+**Alternative: puppeteer-core device emulation** (when node ≥18 and npm are
+available — no wrapper file, and it gives true `fullPage` + a JS overflow
+probe): `npm i puppeteer-core` once, then launch with
+`executablePath` pointing at installed Chrome and
+`page.setViewport({ width: 390, height: 844, deviceScaleFactor: 2 })`.
+`setViewport` is real device-metrics emulation — immune to the window clamp.
+Probe with `document.documentElement.scrollWidth` via `page.evaluate` before
+screenshotting; `page.screenshot({ fullPage: true })` for the tall capture.
+
+## Default — web_screenshot (pi-web ≥0.16.0, auto local detection)
 
 `web_screenshot` auto-routes localhost/LAN/file URLs to the locally installed
 headless Chrome and returns the PNG inline — no daemon, no manual commands:
 
-- `web_screenshot url="http://localhost:PORT"` — done; the model sees the render.
+- `web_screenshot url="http://localhost:PORT" width=390 height=844` — the
+  model sees the render; below 500px the capture is CDP device-emulated
+  (honest viewport, no clamp) and includes the scrollWidth probe.
+- `reduced_motion=true` disables entrance animations for the shot.
 - `full_page=true` captures a tall 8000px window; `wait_for` settles JS via
   `--virtual-time-budget`; `engine="local"` forces local on a public URL.
 - `web_pdf` works the same way (`--print-to-pdf`) for full-content archival.
 - If Chrome is missing: `web_status` shows `localChrome.path`; set `CHROME_PATH`.
+- Empty replies / connection resets from a dev-server URL usually mean a
+  STALE HUNG server on the port (accepts TCP, returns nothing) — `lsof -ti
+  :PORT` and kill it before diagnosing the tools.
 
 ## Fallback — manual headless Chrome (pi-web <0.7.0 or if the tool errors)
 
-Headless Chrome writes the PNG; the `read` tool shows it inline (multimodal models see it).
+Headless Chrome writes the PNG; the `read` tool shows it inline (multimodal models see it). Keep `--window-size` at the target viewport (e.g. `390,844` for a phone screen) — never widen it to hide overflow.
 
 - 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`

package/skills/ux-design/SKILL.md

@@ -4,11 +4,13 @@ description: >
   Anti-slop UI/UX design discipline for AI-generated interfaces. Enforces
   industrial-design principles (Dieter Rams: honest, thorough to the last
   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, render-and-inspect
-  with vision (multimodal models see their own output), pass a measurable slop-audit
-  gate. Works deterministically with text-only models
+  statistical-default slop (purple glow, shadow-as-texture, missing states) —
+  and equally not the correct-but-forgettable default (Inter, blue accent,
+  timid sizes). Covers the Constraint-First method: own the system via a
+  lintable DESIGN.md, write a 5-field brief, DERIVE A DIRECTION from the
+  subject (mood, type voice, color mood, signature element), generate inside
+  constraints, normalise, render-and-inspect with vision, 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.
@@ -16,11 +18,20 @@ argument-hint: ""
 license: MIT
 ---
 
-# UX Design Discipline — Anti-Slop, Industrial-Design Method
+# UX Design Discipline — Direction + Anti-Slop, Industrial-Design Method
 
-You implement UI INSIDE an existing design system. You do NOT invent visual
-language. Slop fills the gaps you leave — so you stop leaving gaps. The system
-is anchored by a repo-root **DESIGN.md** that every generation reads.
+Design work has two moves, and skipping either produces slop:
+
+1. **Discipline** — never drift into the statistical default: tokens only, named
+   elevation, full states, none of the banned tells. (Steps 0–5 + the audit gate.)
+2. **Direction** — always commit to a visual point of view drawn from the
+   subject, before any markup. (Step 1.5 + the Direction playbook.)
+
+Discipline without direction gives the correct-but-forgettable page — Inter,
+a blue accent, white cards, timid sizes — that no design lead would ship.
+Direction without discipline gives purple glow and missing states. The
+repo-root **DESIGN.md** anchors the system; the **direction brief** anchors
+the taste. You produce both.
 
 ## The anti-slop guardrail (hard rules)
 
@@ -53,11 +64,11 @@ deterministic gate and the agent both read.
 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. **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).
+4. **Nothing exists** → do NOT block. Pick a preset from the `ux-presets` skill (B1 Web / B2 Mobile neutral, or a style-direction starter — infer from the task; **ASK only if web-vs-mobile is genuinely unclear**, because it changes touch targets, hover, and safe areas). Use it **in-context as the implicit system** for this generation, then offer to persist it to repo-root `DESIGN.md` (don't auto-write — that's an unrequested file mutation). **A preset is a floor, not an identity:** Step 1.5 must still bend its display face, neutrals, and accent until the finished page could not be mistaken for the stock preset. If your page could be the untouched preset, you did not design.
 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.
+- **Tokens:** colour (one accent + tinted 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); motion ships with a `prefers-reduced-motion` fallback.
 
@@ -75,10 +86,29 @@ 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 1.5 — Derive a direction (before any markup)
+
+This is the taste step, and it is not optional for user-facing UI. From the
+brief, extract the subject's **material** and commit to a direction brief.
+Test for a real direction: *two different designers following it must produce
+visibly different pages.* If they would produce the same page, you wrote a
+default, not a direction — revise.
+
+1. **Subject material** — industry, material, era, energy. "B2B invoicing" is a category; "the accountant's desk — paper, ink, ruled columns, stamps" is material. Design the material.
+2. **Mood adjectives** — three, committed ("calm, ruled, exact"). "Modern, clean, minimal" are the absence of mood — banned as answers.
+3. **Visual concept** — one line naming the world this page lives in ("an expedition logbook, not a travel-agency template"; "a ledger book, not an admin panel").
+4. **Type voice** — display + body pairing from the Direction playbook table (or a deliberate off-table choice). Never default to Inter/system-ui when the subject has a voice.
+5. **Color mood** — temperature, neutral tint, the one accent, written as hex (playbook below).
+6. **Signature element** — the one memorable thing (playbook below). Exactly one.
+
+Say the direction in one line before writing markup —
+`Direction: <concept> · type <display>+<body> · palette <hex> · signature: <element>` —
+then generate inside it. When you catch yourself mid-build reaching for a
+stock choice, ask the generic-default question: *would I produce this same
+plan for any similar brief?* Every yes is a default masquerading as a choice.
+
 ### 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.
@@ -88,61 +118,129 @@ Generate several variants, commit early to the direction with the clearest hiera
 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 — Render & Inspect (vision verify — multimodal models)
+### Step 4 — Render & Inspect (vision verify)
 
 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:
+generating model is multimodal (GLM-5.3, Claude, Gemini) this step is
+**REQUIRED in strict mode** — you see your own output, which is the single
+biggest quality lever for flash-tier models. Skipping it is a gate failure
+even when `ux_audit` passes. (Text-only models, or genuinely no capture path
+→ skip; the deterministic gates are the whole loop.)
 
 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.
+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); alternative: `web_screenshot` at a daemon-reachable address (full playbook in `ux-capture`).
+3. **The LOOK checklist** — at the **brief's target viewport** (mobile briefs: capture at exactly 390 wide; never widen the capture to make a problem invisible — that is cheating the loop). Fix every failure in one batch, re-capture, repeat (2-loop convergence trigger, then move on):
+   - **Squint test:** three distinguishable levels of hierarchy? Does the eye land first where it should?
+   - **Dead zones:** any region with nothing for the eye? Whitespace piling up on one side? On app screens: does content leave a large empty region below the last element at the target height?
+   - **Monotony:** consecutive sections with identical weight/background? Every content group in the same box?
+   - **Timidity:** cover the logo — could this page belong to anyone? Then amplify the display scale or the signature; the direction is not coming through.
+   - **Type & overflow at target width:** display sizes actually large? measure comfortable? **any horizontal scroll, cut-off text, or squeezed badges at the target width?** orphans, cramped labels?
+   - **Mood:** is the palette's temperature visible at a glance, or is it generic white+blue?
+4. **Interact & verify** — a screenshot proves looks, not behavior. Drive the page with `web_interact` (pi-web ≥0.16.0): click the primary CTA, submit the form, toggle a control, and read back state — steps stop at the first failure with the reason. Trusted CDP clicks grant user activation, so clipboard/login flows behave for real.
+5. **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.
+6. **Gates stay final.** `ux_audit` (Step 5) remains the blocking authority; vision settles only what looking can settle.
 
 ### 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
 WCAG 2.x ratio sidecar for compliance reporting. APCA catches dark-theme +
-thin-type slop that the legacy WCAG ratio misses. A 4th gate flags named AI
-tells (glassmorphism, gradient orbs, neon glow, default-card).
+thin-type slop that the legacy WCAG ratio misses.
 
-| Gate | Pass | Fail action |
+| Gate (implemented in `ux_audit`) | Pass | Fail action |
 |---|---|---|
-| 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; 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 / tracked-out eyebrow / tinted near-black bg | Refactor: space → bg shift → elevation before a border |
+| Tokens | no hardcoded hex outside `:root` definitions; no ad-hoc box-shadows built from raw values | Move values into tokens / named elevations |
+| States + motion | interactive elements have `:focus-visible` + `:disabled`; any transition/animation ships a `prefers-reduced-motion` fallback | Keep in draft |
+| Slop tells | no glassmorphism / gradient orbs / neon glow / default-card / 1px-gray-border / tracked-out eyebrow / tinted near-black bg | Refactor: space → bg shift → elevation before a border |
+
+**Model-side checks** (not mechanically gated — you verify): token mapping ≥8/10 sampled components; ≤3 named shadow recipes; no duplicate components. A 4th slop gate flags named AI tells automatically.
+
+## Direction playbook (the positive layer)
 
-## Model routing (who does what)
+The guardrail stops bad; the playbook produces good. Pull from it in Step 1.5.
 
-Split the work along each model's strength. **The inversion rule:** the cheaper/weaker the model, the MORE you must externalise constraints. Taste lives in the brief, not the weights.
+### Typography voice
 
-**The deterministic-first principle:** the gate is mechanical (DESIGN.md lint +
-`ux_audit`), not a vision-LLM call. Text-only models now lead frontend
-(Kimi K3 is #1 on the Arena.ai Frontend Code Arena, ahead of Claude Fable 5) —
-inside a locked system they produce non-slop. agy/Gemini/Claude is optional,
-never the review gate.
+Choose deliberately; 1–2 families with clearly distinct roles. Inter/system-ui
+is the statistical default this method exists to escape — reach past it unless
+the subject is genuinely neutral infrastructure. Pairings that work (Google
+Fonts; first = display, second = body):
 
-| Step | Best tool/model | Why |
+| Subject voice | Pairing | Why it works |
 |---|---|---|
-| **Define system** (DESIGN.md: tokens, elevation, type) | Reuse a preset (ux-presets) OR `agy_execute mode=plan pro-high` (Gemini) **once** | Preset is cheapest. Gemini = strongest visual reasoning for the one-time scaffold. |
-| **Lint system** | `npx @google/design.md lint DESIGN.md` (shell-out) | Deterministic token-ref + contrast + structure validation. |
-| **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. |
+| Editorial / literary / journal | **Newsreader** + **Source Sans 3** | serif display at 500–600, tight leading; body stays quiet |
+| Expedition / outdoors / heritage | **Bricolage Grotesque 800** + **Newsreader** | heavy grotesque display over a serif body reads "printed field guide" |
+| Financial / ledger / legal | **Spline Sans** + **Spline Sans Mono** | mono for every numeral, `tabular-nums`; ruled borders do the branding |
+| Technical / infra / dev tool | **IBM Plex Sans** + **IBM Plex Mono** | personality from weight contrast + hairline rules, not decoration |
+| Warm consumer / food / home | **DM Sans** 700–800 display + body | geometric warmth; personality from color + radius + scale |
+| Dense data / dashboard | Spline Sans pair or IBM Plex pair | personality from rhythm and status-color discipline |
+
+Cautions: the cream+Fraunces+terracotta and Space-Grotesk-on-dark looks are
+named cliché clusters below. Off-table picks that still carry voice:
+Archivo, Schibsted Grotesk, Libre Caslon Text, Spectral (displays);
+Public Sans, Instrument Sans, Work Sans, Outfit (bodies).
+
+Numbers that make type feel designed: marketing h1 ≥ `clamp(2.75rem, 7vw, 6.75rem)`
+(≈96–108px at 1440 — the hero must dominate at 3–4× body size or the scale
+step is wrong); section h2 ≥ 2rem; stat/metric numerals ≥ 2rem with
+`tabular-nums`; display weight 700–800 against body 400; body 1rem–1.125rem/1.6
+at 45–75ch; display letter-spacing −0.01 to −0.025em. Timid sizes are the #1
+"no feel" symptom — when in doubt, bigger display, fewer words.
+
+### Color mood construction
+
+- **Temperature first:** warm or cool page? Then tint EVERY neutral with the mood hue at very low chroma — warm paper `#F6F4EE`, green-black ink `#22302A`, blue-gray desk `#F3F1EA`. Never pure `#fff`/`#000`.
+- **One accent, posture committed:** deep + saturated (vermilion, forest, indigo, oxblood) beats bright + default. Pure blue `#0066FF` on white IS the default look. Test the accent's APCA pair before committing to it.
+- **Support colors only when they encode meaning** (success/danger/warning), each with a soft tinted background for badges — never as decoration.
+- **Bands give rhythm:** 2–3 background treatments across a page (paper → tinted → dark ink → paper). A dark band mid-page is a strong, cheap rhythm marker. Alternating white sections are not rhythm, they're fog.
+- **Surface budget: three surfaces, one family.** Base, one warm/tinted mid, one inverse (dark) — all tinted by the same mood hue — plus the accent reserved for CTAs and marks. If the header/nav introduces a color the rest of the page never uses, delete it: the header inherits the base surface. Five unrelated surfaces read as template collage.
+
+### Composition anatomy
+
+- **Hierarchy = scale + weight + color contrast**, not shadow boxes. If hierarchy needs a shadow, the scale is broken.
+- **Hero formula:** kicker (small, real information) → one big claim (display face, ≥3rem, ≤9 words) → one sub (≤2 lines) → one primary action. No gradient-blob backgrounds; the whitespace and type ARE the design.
+- **Rows beat card grids** for repeated content (trips, features, invoices, episodes) — and a row is a **fixed column grid, not flowing text**: 4–5 columns at identical x-positions across all rows (identity left, one datum per middle column, terminal value — price/CTA — right-aligned on a shared axis), hairline separators, equal row heights. Metadata never wraps to a second line; if it doesn't fit the column, the copy is too long. If you must card, vary the span — one wide, two narrow.
+- **Shaped whitespace:** asymmetric gutters, a deliberately wide margin around one element, rag that breathes. Whitespace is a material you place, not what's left over.
+- **Depth via composition** — overlap, scale steps, band shifts — not glow or shadow-piles.
+
+### The signature element
+
+Exactly one memorable element, drawn from the subject, **scaled like
+composition rather than framed like content**: ≥25% of the viewport wide,
+allowed to bleed off the canvas edge, set at reduced contrast so it reads as
+atmosphere — never a small bordered "illustration card" smaller than the
+headline it sits beside. Forms that work: an oversized glyph or numeral from
+the subject's own writing system, a rotated stamp/seal, index numerals treated
+as design objects, a contour/texture system that fills the hero, one
+full-bleed moment. Everything else stays quiet. If you cannot name your
+signature element, you don't have one — and the page will be forgettable.
+
+### The punctuation kit (authored details, 2–3 per viewport)
+
+Small deliberate marks are the difference between "clean" and "authored":
+
+- one accent-colored terminal on the H1 (a colored period, a final word);
+- pull quotes framed by a bracket, rule, or oversized mark — not a floating italic slab;
+- one stamp/seal/badge marking the page's scarcity or guarantee claim;
+- texture glyphs from the subject's language on repeated items (JP kanji beside route names, §, №, coordinates);
+- terminal marks as data affordances (an arrow on prices/rows) — but NEVER appended to every link/button (that is the template-chrome cliché below).
+
+Placeholder monograms (initials in a circle) are not punctuation — replace
+them with role labels and one real credential line.
+
+### Default vs directed (feel the difference)
+
+- *Default:* `Inter`, `#111` on `#fff`, `h1{font-size:2.5rem}`, blue button, three equal cards.
+- *Directed (same brief, "ledger" concept):* Spline Sans + mono `tabular-nums`, desk `#F3F1EA`, ruled table borders, one rotated `OVERDUE` stamp badge, forest accent `#1E6B50`.
+
+Same effort. One is a page; the other is a template.
 
-**Cross-family rule:** Gemini/Claude produce → deterministic gate reviews. Don't spend vision-model quota on what `ux_audit` computes for free. agy review is a fallback for aesthetic uncertainty, never the gate.
+## Model routing
 
-DeepSeek/GLM/Kimi K3 are safe for design **only inside a fully-specified system**. If no system exists yet, generate a DESIGN.md once (preset or agy), then text-only models are sufficient for every generation thereafter.
+The who-does-what table lives in the `ux-routing` skill (not injected). Always
+true: **the deterministic gate reviews; a multimodal model looks at its own
+render; taste lives in the direction brief, not the model choice.**
 
 ## Banned anti-patterns
 
@@ -158,7 +256,7 @@ screen stays in draft until refactored.
 - Shadows as texture (drifting blur/opacity per component). Shadows = named elevation only.
 - 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.
+- Prompting "make it modern/clean" with no DESIGN.md and no direction — 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:
@@ -172,8 +270,8 @@ All legitimate for *some* briefs — but they are defaults, not choices, and app
 ## 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.
+- **Typography carries personality.** Choose typefaces deliberately per project (1–2 families, clearly distinct roles — the playbook table is the starting point, not the ceiling); 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.
+- **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. In a screenshot test, placeholder names ("Acme", "Lorem", "Feature One") read as template — write real content even in drafts.
+- **Spend boldness in one place.** One memorable element (the signature); 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.

package/skills/ux-presets/SKILL.md

@@ -3,11 +3,12 @@ name: ux-presets
 description: >
   Reference design-system presets for ux-design. Anti-slop shortcuts: instead of
   inventing tokens, elevation, and state contracts from scratch, reuse one of
-  these battle-tested systems (shadcn/ui, Material 3, Radix) or drop in a
-  medium-tuned DESIGN.md starter (Web or Mobile) as the implicit system when no
-  DESIGN.md exists. Use when starting a new UI project with no existing design
-  system, when Step 0 (Own the system) of the ux-design method has nothing to
-  reuse, or when asked for a starter token set. These are REFERENCES only —
+  these battle-tested systems (shadcn/ui, Material 3, Radix), drop in a
+  medium-tuned DESIGN.md starter (Web or Mobile), or adopt a style-direction
+  starter (Editorial print, Ledger, Warm consumer) that already carries a point
+  of view. Use when starting a new UI project with no existing design system,
+  when Step 0 (Own the system) of the ux-design method has nothing to reuse,
+  or when asked for a starter token set. These are REFERENCES only —
   pi-ux never bundles CSS.
 argument-hint: ""
 license: MIT
@@ -172,7 +173,6 @@ Map EVERY shadow to a named level — never invent blur/opacity per component:
 ```
 
 ### B2 — Mobile preset (touch-first, native / RN / mobile web)
-
 ```markdown
 ---
 name: Mobile Baseline
@@ -275,6 +275,130 @@ is nearer than the page — keep it that way.
 - iOS vs Android: follow the host platform — iOS HIG (SF symbols, larger corner radius, sheet) vs Material 3 (FAB, ripple, top app bar).
 ```
 
+## Option B+ — style-direction starters (a floor WITH a point of view)
+
+B1/B2 are deliberately neutral — they pass the gates but carry no identity, and
+a project that keeps them untouched ships the "correct but forgettable" page.
+The three starters below pair the same gate-hardened token structure with a
+**subject material and type voice**, so Step 1.5 starts from a direction
+instead of a blank. Pick the one whose material matches the brief; then still
+bend it (Step 1.5): swap the accent to the subject's world, adjust the mood
+adjectives, and commit a signature element of your own. All pairs below were
+verified against the APCA ladder (Lc ≥75 body · ≥45 large · ≥60 small-bold
+badges).
+
+### S1 — Editorial print (journal, heritage brand, long-form, portfolio)
+
+Material: the printed page — warm paper, ink, hairline rules. Near-square
+corners; separation by rules and whitespace, elevation almost never. Display
+**Newsreader** (500–600, tight leading) over **Source Sans 3** body.
+
+```yaml
+name: Editorial Print
+colors:
+  bg: "#F6F2E9"          # warm paper
+  surface: "#EEE8DA"     # shaded paper band
+  text: "#20241F"        # ink
+  text-muted: "#565B50"
+  accent: "#7D2B25"      # oxblood — links, rules, stamps
+  accent-hover: "#67241E"
+  border: "#DBD3C2"      # hairline
+  danger: "#9B2C20"
+typography:
+  body:   { fontFamily: "Source Sans 3", fontSize: 1.0625rem, lineHeight: 1.65 }
+  h1:     { fontFamily: Newsreader, fontSize: 3rem, fontWeight: 600, lineHeight: 1.1 }
+  h2:     { fontFamily: Newsreader, fontSize: 2.1rem, fontWeight: 600 }
+  label:  { fontFamily: "Source Sans 3", fontSize: 0.85rem, fontWeight: 600 }
+rounded:  { sm: 2px, md: 2px, lg: 3px }   # print is square
+components:
+  ruled-row:   { borderTop: "1.5px solid {colors.text}", padding: "{spacing.md} 0" }
+  link:        { color: "{colors.accent}", textDecorationThickness: "1px" }
+  button-quiet: { border: "1.5px solid {colors.text}", color: "{colors.text}", rounded: "{rounded.sm}" }
+  stamp:       { color: "{colors.accent}", border: "2px solid {colors.accent}", transform: "rotate(-2deg)" }
+```
+
+Do: rules over shadows (border hierarchy); generous margins around display
+type; numerals and folios as design objects. Don't: shadows bigger than
+`--elev-sm`; rounded-2xl softness; dark mode (this system IS paper).
+
+### S2 — Ledger (finance, invoicing, dense data, legal, ops dashboards)
+
+Material: the accountant's desk — desk paper, cards, ruled columns, stamps.
+Every numeral in the mono face with `font-variant-numeric: tabular-nums`.
+Display **Spline Sans** + **Spline Sans Mono** for all data.
+
+```yaml
+name: Ledger
+colors:
+  bg: "#F3F1EA"          # desk
+  surface: "#FCFBF7"     # card
+  text: "#1C211E"        # ink
+  text-muted: "#5B625D"
+  accent: "#1E6B50"      # ledger green — buttons, positive
+  accent-text: "#17573F" # green as TEXT on desk/card (Lc 79-81)
+  accent-hover: "#155640"
+  danger: "#B0362A"      # stamp text on #F4E3E0 (small-bold ≥600)
+  warning: "#8A6210"     # stamp text on #F2EAD4 (small-bold ≥600)
+  border: "#E0DDD2"
+  rule: "#1C211E"        # 1.5px structural rules — the branding
+typography:
+  body:   { fontFamily: "Spline Sans", fontSize: 0.9rem, lineHeight: 1.5 }
+  data:   { fontFamily: "Spline Sans Mono", fontWeight: 500, fontVariantNumeric: tabular-nums }
+  h1:     { fontFamily: "Spline Sans", fontSize: 1.5rem, fontWeight: 700, letterSpacing: "-0.015em" }
+  label:  { fontFamily: "Spline Sans Mono", fontSize: 0.6875rem, fontWeight: 500, letterSpacing: "0.08em", textTransform: uppercase }
+rounded:  { sm: 3px, md: 6px, lg: 8px }
+components:
+  panel:        { backgroundColor: "{colors.surface}", border: "1.5px solid {colors.rule}", rounded: "{rounded.md}" }
+  kpi-value:    { font: "{typography.data}", fontSize: 1.6875rem, fontWeight: 600 }
+  status-paid:  { color: "{colors.accent-text}", backgroundColor: "#E2EEE7", fontWeight: 700, fontSize: "0.65rem" }
+  status-overdue: { color: "{colors.danger}", backgroundColor: "#F4E3E0", fontWeight: 700, fontSize: "0.65rem", transform: "rotate(-2deg)" }
+  table-head:   { font: "{typography.label}", borderBottom: "1.5px solid {colors.rule}" }
+```
+
+Do: structural 1.5px rules; status badges as stamps (soft bg + dark text);
+KPI strip as one ruled panel, not four floating cards. Don't: pastel
+dashboards with soft shadows everywhere; chart fills lighter than 3:1 against
+the track; intercom-blue accents.
+
+### S3 — Warm consumer (food, home, family, habits, kitchen/bath apps)
+
+Material: warm kitchen linen. Chunky friendly radii, one deep green spine,
+freshness told in color (fresh/expiring/expired), oversized action. Display
+**DM Sans** 700–800.
+
+```yaml
+name: Warm Consumer
+colors:
+  bg: "#FAF6EE"          # linen
+  surface: "#FFFFFF"     # card
+  text: "#27302A"
+  text-muted: "#5C6457"  # passes on BOTH linen and white
+  accent: "#2F6B3C"      # basil — FAB, primary actions
+  accent-pressed: "#245430"
+  accent-soft: "#E5F0E2"
+  danger: "#A93222"      # expired badge text on #F8E3DD (bold)
+  warning: "#8A5D0B"     # expiring badge text on #F7ECD4 (bold)
+  border: "#EAE4D6"
+typography:
+  body:   { fontFamily: "DM Sans", fontSize: 1rem, lineHeight: 1.45 }
+  h1:     { fontFamily: "DM Sans", fontSize: 1.4375rem, fontWeight: 800, letterSpacing: "-0.02em" }
+  badge:  { fontFamily: "DM Sans", fontSize: 0.65625rem, fontWeight: 700, letterSpacing: "0.03em" }
+rounded:  { sm: 12px, md: 16px, lg: 22px }
+components:
+  list-row:    { backgroundColor: "{colors.surface}", border: "1.5px solid {colors.border}", rounded: "{rounded.md}", padding: "12px 14px" }
+  category-spine: { position: absolute, left: 0, width: 5px, backgroundColor: "{category-color}" }
+  fab:         { backgroundColor: "{colors.accent}", color: "#F2F7EE", rounded: 999px, padding: "16px 26px", fontWeight: 800 }
+  badge-soon:  { color: "{colors.warning}", backgroundColor: "#F7ECD4" }
+  badge-expired: { color: "{colors.danger}", backgroundColor: "#F8E3DD" }
+```
+
+Do: category color spines (5px, left edge); FAB as the page's one loud
+element; header bands in the accent color. Don't: neon or candy gradients;
+hover-only feedback (touch medium — use B2's tap rules); body below 16px.
+
+Mobile adaptation: any S-starter keeps its palette/type and takes B2's
+mechanics (44pt targets, `:active` states, safe areas, thumb zone).
+
 ## Option C — minimal `:root` token set (CSS-only, no DESIGN.md)
 
 For CSS-only projects that do not adopt DESIGN.md, drop this compact baseline
@@ -330,11 +454,13 @@ into the project's `:root`. It satisfies the token + elevation + state gates of
 
 1. Run **Step 0** of ux-design. If the project already has a DESIGN.md / tokens / elevation / states → use them.
 2. If not, pick **Option A** — reuse an installed system (shadcn/Material/Radix) when the stack matches, OR pull a named style (Claymorphism, Brutalism, …) from the design.md library. Both reuse-before-invent; both still must pass `ux_audit`.
-3. Otherwise pick **Option B** — infer the medium (Web B1 vs Mobile B2) from the task, use the starter in-context as the implicit system, and keep generating. Only ASK if web-vs-mobile is unclear.
+3. Otherwise pick **Option B** — infer the medium (Web B1 vs Mobile B2) from the task, use the starter in-context as the implicit system, and keep generating. Only ASK if web-vs-mobile is unclear. When the subject's material clearly matches a style-direction starter (**S1 Editorial print / S2 Ledger / S3 Warm consumer**), prefer it over the neutral B-starter — it hands Step 1.5 a direction for free.
 4. Only for CSS-only projects that won't adopt DESIGN.md, use **Option C** (`:root` block).
 5. Generate screens with any text-only model (DeepSeek-v4 / GLM-5.2 / Kimi K3) INSIDE these constraints.
 6. Run `ux_audit` with the CSS + the most common text colour pairs before handoff.
 
+**Floors, not identities:** whichever starter you pick, Step 1.5 of ux-design still bends it — accent toward the subject's world, mood adjectives committed, one signature element named. The finished page must not be recognisable as the stock starter.
+
 ## Audit-ready pairs
 
 ```jsonc
@@ -354,3 +480,4 @@ into the project's `:root`. It satisfies the token + elevation + state gates of
 - Not a CSS framework — reference only. Don't bundle it; copy what you need.
 - Not themeable at runtime — it's a baseline to extend, not a product.
 - Not opinionated about the accent — `accent` / `{colors.accent}` is the ONE knob you turn for brand.
+- Not an identity — even the S-starters are floors. A finished page that looks exactly like its starter means Step 1.5 was skipped.

package/skills/ux-routing/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: ux-routing
+description: >
+  Reference table for dividing UX work across models in the Pi ecosystem —
+  who defines the DESIGN.md scaffold, who generates variants, who renders and
+  inspects, what reviews. Consult when delegating design work to other models
+  (agy/Gemini, Claude, DeepSeek, Kimi) or when deciding whether the main model
+  should do a step itself. Not injected into every turn by design; the
+  always-true core rule lives in ux-design: the deterministic gate reviews, a
+  multimodal model looks at its own render, and taste lives in the direction
+  brief, not in the model choice.
+---
+
+# Model routing for design work (who does what)
+
+Split the work along each model's strength. **The inversion rule:** the
+cheaper/weaker the model, the MORE you must externalise constraints. Taste
+lives in the direction brief, not the weights.
+
+**The deterministic-first principle:** the gate is mechanical (DESIGN.md lint +
+`ux_audit`), not a vision-LLM call. Text-only models now lead frontend
+(Kimi K3 is #1 on the Arena.ai Frontend Code Arena, ahead of Claude Fable 5) —
+inside a locked system they produce non-slop. agy/Gemini/Claude is optional,
+never the review gate.
+
+| Step | Best tool/model | Why |
+|---|---|---|
+| **Define system** (DESIGN.md: tokens, elevation, type) | Reuse a preset (ux-presets) OR `agy_execute mode=plan pro-high` (Gemini) **once** | Preset is cheapest. Gemini = strongest visual reasoning for the one-time scaffold. |
+| **Derive direction** (Step 1.5) | The generating model itself, after reading the subject material | Direction needs the subject brief, not a bigger model. |
+| **Lint system** | `npx @google/design.md lint DESIGN.md` (shell-out) | Deterministic token-ref + contrast + structure validation. |
+| **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) + tokens + states + 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. |
+
+**Cross-family rule:** Gemini/Claude produce → deterministic gate reviews. Don't
+spend vision-model quota on what `ux_audit` computes for free. agy review is a
+fallback for aesthetic uncertainty, never the gate.
+
+DeepSeek/GLM/Kimi K3 are safe for design **only inside a fully-specified
+system** (DESIGN.md or preset + direction brief). If no system exists yet,
+create it once (preset + Step 1.5 direction, or agy), then text-only models
+are sufficient for every generation thereafter.