@bacnh85/pi-ux 0.3.0 → 0.4.3

package/CHANGELOG.md

@@ -1,5 +1,88 @@
 # Changelog
 
+## 0.4.3
+
+- **Named styles via the design.md library.** `ux-presets` now documents a
+  reuse path for named aesthetics (Claymorphism, Brutalism, Bento, Art Deco, …):
+  fetch the canonical `DESIGN.md` from the [design.md style library](https://designmd.app/library),
+  `npx @google/design.md lint` it, then `ux_audit` — block handoff on fail. No
+  style is pre-approved: the stock Claymorphism template ships a button that
+  fails `ux_audit` at **Lc −15.67** (lilac `#E6E6FA` on peach `#FDBCB4`),
+  corrected to ink-on-peach (Lc 75.72 ✓). Glassmorphism and neumorphism remain
+  banned slop tells regardless of library entry.
+- Step 2 of "How to use with ux-design" names the library path alongside
+  shadcn/Material/Radix as reuse-before-invent options.
+
+## 0.4.2
+
+- **Review fixes** (7 findings, all pinned with regression tests):
+  - **FIX (HIGH)** `parseOklch` silently corrupted percentage lightness: the
+    regex placed `%?` outside the capture group, so `oklch(L% C H)` (the
+    standard CSS form) never divided L by 100, clamping any `0 < L < 100` to
+    white. Captured inside the group now. Affects both APCA and WCAG.
+  - **FIX (latent)** `parseOklch` returned linear sRGB without gamma encoding;
+    APCA's `sRGBtoY` then double-linearized oklch values, making contrast
+    wrong. Added the standard linear→sRGB gamma transfer. oklch contrast now
+    matches the equivalent hex.
+  - **FIX (MEDIUM, FP)** neon-glow heuristic flagged a normal accent shadow
+    (≤12px coloured blur) as slop — the `/0\.d/` alpha fallback was too broad.
+    Rewritten to require a blur radius ≥ 20px (the actual glow signature).
+  - **FIX (MEDIUM, FN)** neon-glow heuristic missed coloured **hex** glow
+    shadows (only inspected `rgba?()`). Now parses hex colours in shadows too.
+  - **FIX (LOW)** gradient-orb regex truncated at the first inner `)` (nested
+    `rgba`/`hsl` stops). Now captures one level of nested parens.
+  - **FIX (LOW)** `apcaThreshold` gave bold body text (14–17px) the relaxed
+    Lc 45; per APCA guidance bold body text stays at Lc 60 until ≥18px.
+  - **FIX (LOW)** alpha hex (`#RRGGBBAA` / `#RGBA`) was invisible to the
+    token gate (`\b` failed between adjacent hex digits). Switched to a
+    negative-lookahead regex matching 3/4/6/8-digit hex.
+- 12 new regression tests (64 → 76).
+
+## 0.4.1
+
+- **Medium-tuned DESIGN.md presets (Web + Mobile).** `ux-presets` Option B is
+  now split into **B1 Web** (mouse + keyboard: hover, `:focus-visible`, desktop
+  type scale, 65ch measure, responsive container) and **B2 Mobile** (touch-first:
+  ≥44pt tap targets, `:active`/pressed with NO `:hover`, safe-area insets,
+  16px base to avoid iOS zoom, thumb-zone layout, iOS-HIG/Material notes). Each
+  is spec-compliant and lintable from day one.
+- **Step 0 unblocks when DESIGN.md is missing.** The resolution order is now:
+  (1) use repo-root DESIGN.md if present; (2) reuse an already-wired system
+  (shadcn/MUI/Radix/Tailwind); (3) otherwise drop in a medium-tuned preset
+  (infer Web vs Mobile from the task; ASK only if genuinely unclear) as the
+  implicit system and keep generating; (4) only if no preset fits, generate one
+  once with `agy`. The agent no longer stalls in the common no-DESIGN.md case;
+  it offers to persist the preset to repo root but does not auto-write.
+
+## 0.4.0
+
+- **DESIGN.md anchor (shift-left).** Step 0 of the ux-design method now points
+  at a repo-root **DESIGN.md** (Google Labs open standard) as the single source
+  of truth the agent reads before styling. Lint via shell-out:
+  `npx @google/design.md lint DESIGN.md` — pi-ux orchestrates the tool, it is
+  NOT a runtime dependency (pi-ux stays zero-dep). The `ux-presets` skill ships
+  a spec-compliant DESIGN.md starter alongside the existing `:root` CSS block.
+- **APCA contrast (primary gate) + WCAG 2.x sidecar.** The `ux_audit` contrast
+  gate now reports perceptual APCA Lc as the primary pass/fail (Lc ≥75 body,
+  ≥45 large/bold, ≥30 non-text) with the legacy WCAG ratio shown as a
+  compliance sidecar for orgs that must report it. APCA catches dark-theme +
+  thin-type slop that WCAG 2.x misses — the exact text-only-model failure
+  mode. `pairs` gain optional `weight`/`size` to set the APCA threshold.
+- **oklch() support.** Colour parsing now accepts `oklch(L C H)` in addition
+  to hex (DESIGN.md allows oklch values).
+- **Slop-tell gate (4th gate).** New deterministic gate flagging named AI
+  signatures: glassmorphism (`backdrop-filter`), gradient orbs, neon glow,
+  the untouched shadcn default-card reflex (`rounded-2xl`+`shadow-lg`+`p-6`),
+  and 1px gray card borders. Co-occurrence heuristics avoid false positives on
+  legitimate token-based elevation.
+- **Deterministic-first model routing.** The skill's model-routing table is
+  rewritten: text-only models (DeepSeek-v4, GLM-5.2, Kimi K3) now do
+  generation + normalisation inside a locked system; `agy`/Gemini/Claude is
+  demoted to optional one-time DESIGN.md generation + optional polish — never
+  the review gate. Text-only models now lead frontend (Kimi K3 is #1 on the
+  Arena.ai Frontend Code Arena, ahead of Claude Fable 5).
+- Zero dependencies retained. Plain JS, `node --test` (64 tests).
+
 ## 0.3.0
 
 - **`ux_audit` tool (deterministic slop-audit gate).** New LLM-callable tool

package/README.md

@@ -1,12 +1,12 @@
 # pi-ux
 
-Anti-slop UI/UX design discipline for the [Pi coding agent](https://pi.dev). Enforces industrial-design principles (Dieter Rams: honest, thorough to the last detail, as little design as possible) so AI-generated interfaces are defensible systems, not statistical-default slop (purple glow, shadow-as-texture, missing states).
-
-This is a **discipline enforcer**, not a generator. Generation stays with `agy_execute` (Gemini/Claude) and the main Pi models (DeepSeek-v4, GLM-5.2); pi-ux makes sure their output lands inside a defensible design system.
+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.
 
 ## Why
 
-AI-generated UI converges on the same defaults — purple/indigo glow, shadow-heavy cards, missing focus/disabled/error states — because under vague direction ("make it modern/clean"), models reach for high-frequency statistical patterns. Slop is an **ownership problem**: "the design has no owner at the system level." A skill alone is ignorable; a `before_agent_start` hook is not.
+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.
+
+**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.
 
 ## Install
 
@@ -41,45 +41,55 @@ The guardrail is injected into the system prompt on every agent start while acti
 
 The injected skill enforces **Constraint-First Design Generation**:
 
-0. **Own the system** — tokens (colour/type/spacing/radius), 3–5 named elevation levels, state contract. If absent, no generation yet — use the `ux-presets` skill to reuse shadcn/ui, Material, or Radix, or copy a compact token set.
+0. **Own the system via DESIGN.md** — a repo-root `DESIGN.md` (Google Labs open standard: YAML token frontmatter + rationale) is the single source of truth. Lint it before generating:
+   ```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.
 1. **5-field brief per screen** — user job, inventory, token constraints, required states, one reference.
-2. **Generate fast, converge early** — 2-loop convergence trigger, else tighten the brief.
+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): token coverage ≥8/10, ≤3 shadow recipes, WCAG AA contrast, full state coverage.
+4. **Slop-audit gate** — run `ux_audit` (measurable): APCA contrast, token coverage, state coverage, slop tells.
 
 ## The `ux_audit` tool
 
 Deterministic slop-audit — no model needed, all gates are computable:
 
 ```
-ux_audit css="..." pairs=[{fg:"#111",bg:"#fff",label:"body",min:4.5}]
+ux_audit css="..." pairs=[{fg:"#111",bg:"#fff",label:"body",weight:400,size:16,min:4.5}]
 ```
 
 | Gate | What it checks |
 |------|----------------|
-| **Contrast** | WCAG 2.x relative-luminance ratio for each fg/bg pair (4.5:1 body, 3:1 large/UI) |
+| **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 |
 
 Returns pass/fail per gate + a formatted report. In `strict` mode this is the gate that blocks handoff.
 
-## Skills
+**Why APCA over WCAG 2.x:** APCA is perceptual and accounts for font weight/size; it catches dark-theme + thin-type slop that the legacy WCAG ratio misses. Example: `#aaa` on `#1e1e1e` scores APCA Lc -54.4 (fails ≥75) but WCAG 7.18:1 (passes ≥4.5) — APCA catches what WCAG can't.
 
-- **`ux-design`** — the Constraint-First method + model routing (auto-injected by the hook when active).
-- **`ux-presets`** — reference design-system presets for Step 0: reuse shadcn/ui / Material 3 / Radix, or copy a compact token set. Reference only — no bundled CSS.
+## Model routing (deterministic-first)
 
-The skill tells the agent which model to use for each step:
+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 (tokens, elevation) | `agy_execute mode=plan pro-high` (Gemini) or reuse shadcn/Material |
-| Per-screen brief | **GLM-5.2** (200K ctx) |
-| Generate variants | `agy_execute mode=accept-edits flash-high` (Gemini) |
+| 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) |
-| Final review/polish | `agy_execute mode=plan sonnet` (Claude) |
+| 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.
+
+## Skills
 
-**The inversion rule:** the cheaper/weaker the model, the MORE you must externalise constraints. DeepSeek/GLM are safe for design only inside a fully-specified system.
+- **`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.
 
 ## Configuration
 

package/extensions/index.js

@@ -71,15 +71,17 @@ function auditParametersSchema() {
       },
       pairs: {
         type: "array",
-        description: "Foreground/background colour pairs to check for WCAG contrast (fg + bg as #hex, a label, and a min ratio defaulting to 4.5).",
+        description: "Foreground/background colour pairs to check for contrast (APCA primary + WCAG sidecar). fg + bg as #hex or oklch(); optional weight/size set the APCA threshold; min is the WCAG compliance floor.",
         items: {
           type: "object",
           additionalProperties: false,
           properties: {
-            fg: { type: "string", description: "Foreground colour, e.g. '#111111'." },
+            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: "Minimum contrast ratio. 4.5 for body, 3.0 for large/UI. 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." },
+            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." },
           },
           required: ["fg", "bg"],
         },
@@ -94,10 +96,11 @@ function formatAuditResult(result) {
   lines.push("");
 
   const c = result.gates.contrast;
-  lines.push(c.pass ? "✓ Contrast" : "✗ Contrast");
+  lines.push(c.pass ? "✓ Contrast (APCA)" : "✗ Contrast (APCA)");
   for (const r of c.results) {
+    const lc = r.apca === null ? "n/a" : `Lc ${r.apca}`;
     const ratio = r.ratio === null ? "n/a" : `${r.ratio.toFixed(2)}:1`;
-    lines.push(`  ${r.pass ? "✓" : "✗"} ${r.label || `${r.fg}/${r.bg}`}: ${ratio} (min ${r.min ?? 4.5})`);
+    lines.push(`  ${r.pass ? "✓" : "✗"} ${r.label || `${r.fg}/${r.bg}`}: ${lc} (min Lc ${r.apcaMin}) · WCAG ${ratio} (min ${r.min ?? 4.5})`);
   }
 
   const t = result.gates.tokens;
@@ -110,6 +113,10 @@ function formatAuditResult(result) {
   for (const m of s.missingFocusVisible) lines.push(`  ✗ ${m}`);
   for (const m of s.missingDisabled) lines.push(`  ✗ ${m}`);
 
+  const st = result.gates.slopTells;
+  lines.push(st.pass ? "✓ Slop tells" : "✗ Slop tells");
+  for (const tell of st.tells) lines.push(`  ✗ ${tell}`);
+
   return lines.join("\n");
 }
 
@@ -149,12 +156,12 @@ export default function uxExtension(pi) {
     name: "ux_audit",
     label: "UX Slop Audit",
     description:
-      "Run deterministic slop-audit gates on CSS: WCAG contrast, off-system token values (hardcoded hex / ad-hoc shadows), and missing interaction states (:focus-visible / :disabled). No model needed — all gates are computable. In strict mode, block handoff until this passes.",
-    promptSnippet: "Run deterministic UX slop-audit (contrast + tokens + states)",
+      "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.",
+    promptSnippet: "Run deterministic UX slop-audit (APCA contrast + tokens + states + slop tells)",
     promptGuidelines: [
-      "Contrast and token-coverage are computable, not judgement — use this tool instead of eyeballing.",
-      "Pass fg/bg colour pairs to check WCAG AA contrast (4.5:1 body, 3:1 large/UI).",
-      "Pass the CSS string to scan for hardcoded hex and ad-hoc box-shadow not built from var() tokens.",
+      "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).",
       "State coverage flags interactive elements (button/a/input/...) missing :focus-visible or :disabled rules.",
     ],
     parameters: auditParametersSchema(),

package/hooks/ux-audit.js

@@ -1,35 +1,139 @@
 // pi-ux — deterministic slop-audit engine (no model, no deps).
 //
-// Three gates, all computable:
-//   1. Contrast  — WCAG 2.x relative-luminance ratio for colour pairs.
+// Four gates, all computable:
+//   1. Contrast  — APCA Lc (primary, perceptual) + WCAG 2.x ratio (sidecar).
 //   2. Tokens    — off-system values (raw hex, magic px, ad-hoc shadows).
 //   3. States    — interactive elements missing focus-visible / disabled.
+//   4. SlopTells — named AI signatures (glassmorphism, orbs, glow, default-card).
 //
-// Ponytail: WCAG math is ~10 lines; token scan is regex; state scan is a
-// selector-set check. No wcag-contrast lib, no css parser, no AST. This is
-// mechanical linting, not judgement — that is the whole point of the gate.
+// Ponytail: all gates are mechanical linting, not judgement. APCA math is
+// ~25 lines; WCAG is ~10; token scan is regex; state scan is substring; tell
+// scan is co-occurrence heuristics. No wcag-contrast lib, no css parser, no AST.
 
-// --- WCAG contrast --------------------------------------------------------
+// --- colour parsing -------------------------------------------------------
+// Accepts hex (3/4/6/8-digit) and oklch(L C H) / oklch(L C H / a). Returns
+// [r,g,b] 0-255, or null. oklch support matters because DESIGN.md (Google's
+// open standard) allows oklch() values.
+
+function parseHex(hex) {
+  const m = /^#?([0-9a-f]{8}|[0-9a-f]{6}|[0-9a-f]{4}|[0-9a-f]{3})$/i.exec(String(hex).trim());
+  if (!m) return null;
+  let h = m[1];
+  if (h.length === 8) h = h.slice(0, 6); // drop alpha
+  if (h.length === 4) h = h.slice(0, 3);
+  if (h.length === 3) h = h.split('').map((c) => c + c).join('');
+  return [parseInt(h.slice(0, 2), 16), parseInt(h.slice(2, 4), 16), parseInt(h.slice(4, 6), 16)];
+}
+
+// ponytail: standard oklch->linear-sRGB->sRGB. ~20 lines, no dep. Handles the
+// cases DESIGN.md allows; guards NaN/overflow.
+function parseOklch(str) {
+  const m = /^oklch\(\s*([0-9.]+%?)\s+([0-9.]+)\s+([0-9.]+)(?:deg)?\s*(?:\/\s*([0-9.]+))?%?\s*\)$/i.exec(String(str).trim());
+  if (!m) return null;
+  const L = Math.min(Math.max(parseFloat(m[1]) / (String(m[1]).endsWith('%') ? 100 : 1), 0), 1);
+  const C = parseFloat(m[2]);
+  const Hdeg = parseFloat(m[3]);
+  if ([L, C, Hdeg].some(Number.isNaN)) return null;
+  const h = (Hdeg * Math.PI) / 180;
+  const a = C * Math.cos(h);
+  const b = C * Math.sin(h);
+  // OKLab -> linear sRGB
+  const l_ = L + 0.3963377774 * a + 0.2158037573 * b;
+  const m_ = L - 0.1055613458 * a - 0.0638541728 * b;
+  const s_ = L - 0.0894841775 * a - 1.2914855480 * b;
+  const l3 = l_ ** 3, m3 = m_ ** 3, s3 = s_ ** 3;
+  let r = 4.0767416621 * l3 - 3.3077115913 * m3 + 0.2309699292 * s3;
+  let g = -1.2684380046 * l3 + 2.6097574011 * m3 - 0.3413193965 * s3;
+  let bl = -0.0041960863 * l3 - 0.7034186147 * m3 + 1.7076147010 * s3;
+  // linear -> sRGB gamma encoding, then to 0-255. APCA's sRGBtoY expects
+  // gamma-encoded sRGB (same as hex produces); without this, oklch values
+  // double-linearize and contrast is wrong.
+  const enc = (c) => {
+    c = Math.min(Math.max(c, 0), 1);
+    return c <= 0.0031308 ? 12.92 * c : 1.055 * Math.pow(c, 1 / 2.4) - 0.055;
+  };
+  const to255 = (c) => Math.round(enc(c) * 255);
+  return [to255(r), to255(g), to255(bl)];
+}
+
+function parseColor(input) {
+  const s = String(input).trim();
+  if (s.startsWith('#') || /^[0-9a-f]{3,8}$/i.test(s)) return parseHex(s);
+  if (s.toLowerCase().startsWith('oklch')) return parseOklch(s);
+  // ponytail: named/hsl/rgb not supported — DESIGN.md tokens use hex/oklch.
+  // Tokens with other formats are just not contrast-checkable here; the gate
+  // still runs on the pairs that ARE parseable.
+  return parseHex(s); // falls back to hex parser (returns null on garbage)
+}
+
+// --- APCA contrast (primary gate) -----------------------------------------
+// Canonical APCA 0.0.98G-4g (W3, constants fixed since Feb 2021). Source:
+// Myndex/apca-w3 master src/apca-w3.js (fetched 2024). Returns signed Lc:
+// positive = dark text on light bg (BoW); negative = light text on dark (WoB).
+// Range ≈ ±106. Polarity matters — text is the FIRST arg, bg the SECOND.
+
+const APCA = {
+  mainTRC: 2.4, sRco: 0.2126729, sGco: 0.7151522, sBco: 0.0721750,
+  normBG: 0.56, normTXT: 0.57, revTXT: 0.62, revBG: 0.65,
+  blkThrs: 0.022, blkClmp: 1.414, scaleBoW: 1.14, scaleWoB: 1.14,
+  loBoWoffset: 0.027, loWoBoffset: 0.027, deltaYmin: 0.0005, loClip: 0.1,
+};
+
+function sRGBtoY(rgb) {
+  const [r, g, b] = rgb;
+  const exp = (chan) => Math.pow(chan / 255.0, APCA.mainTRC);
+  return APCA.sRco * exp(r) + APCA.sGco * exp(g) + APCA.sBco * exp(b);
+}
+
+function apcaContrastLc(textColor, bgColor) {
+  const txtRgb = parseColor(textColor);
+  const bgRgb = parseColor(bgColor);
+  if (!txtRgb || !bgRgb) return null;
+  let txtY = sRGBtoY(txtRgb);
+  let bgY = sRGBtoY(bgRgb);
+  if (isNaN(txtY) || isNaN(bgY) || Math.min(txtY, bgY) < 0 || Math.max(txtY, bgY) > 1.1) return 0.0;
+  // soft black clamp
+  txtY = txtY > APCA.blkThrs ? txtY : txtY + Math.pow(APCA.blkThrs - txtY, APCA.blkClmp);
+  bgY = bgY > APCA.blkThrs ? bgY : bgY + Math.pow(APCA.blkThrs - bgY, APCA.blkClmp);
+  if (Math.abs(bgY - txtY) < APCA.deltaYmin) return 0.0;
+  let SAPC, out;
+  if (bgY > txtY) { // BoW: dark text on light
+    SAPC = (Math.pow(bgY, APCA.normBG) - Math.pow(txtY, APCA.normTXT)) * APCA.scaleBoW;
+    out = SAPC < APCA.loClip ? 0.0 : SAPC - APCA.loBoWoffset;
+  } else { // WoB: light text on dark — negative
+    SAPC = (Math.pow(bgY, APCA.revBG) - Math.pow(txtY, APCA.revTXT)) * APCA.scaleWoB;
+    out = SAPC > -APCA.loClip ? 0.0 : SAPC + APCA.loWoBoffset;
+  }
+  return out * 100.0;
+}
+
+// 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) {
+  const w = typeof weight === 'number' ? weight : 400;
+  const s = typeof size === 'number' ? size : 16;
+  const bold = w >= 700;
+  // APCA font-Lc lookup: Lc 45 = ≥24px regular or ≥18px bold; Lc 60 = ≥18px
+  // regular or bold body (14–17px); Lc 75 = small body. Bold body text is
+  // NOT exempt from readability — it stays at Lc 60 until it's also large.
+  if (s >= 24 || (bold && s >= 18)) return 45;
+  if (s >= 18 || bold) return 60;
+  return 75; // body text — strictest
+}
+
+// --- WCAG 2.x contrast (compliance sidecar) -------------------------------
+// Kept verbatim from v0.3.0 — some orgs must report the WCAG ratio. APCA is
+// the primary gate; WCAG is shown alongside for procurement/legal.
 
 function channelLuminance(c) {
-  // sRGB channel (0-255) -> linear luminance component
   const s = c / 255;
   return s <= 0.03928 ? s / 12.92 : Math.pow((s + 0.055) / 1.055, 2.4);
 }
 
 function relativeLuminance(hex) {
-  // Accept 3/4/6/8-digit hex; strip alpha channel from 4/8-digit forms.
-  const m = /^#?([0-9a-f]{8}|[0-9a-f]{6}|[0-9a-f]{4}|[0-9a-f]{3})$/i.exec(String(hex).trim());
-  if (!m) return null;
-  let h = m[1];
-  // 4/8-digit: drop the trailing alpha channel (last 1/2 digits).
-  if (h.length === 8) h = h.slice(0, 6);
-  if (h.length === 4) h = h.slice(0, 3);
-  if (h.length === 3) h = h.split('').map((c) => c + c).join('');
-  const r = parseInt(h.slice(0, 2), 16);
-  const g = parseInt(h.slice(2, 4), 16);
-  const b = parseInt(h.slice(4, 6), 16);
-  return 0.2126 * channelLuminance(r) + 0.7152 * channelLuminance(g) + 0.0722 * channelLuminance(b);
+  const rgb = parseColor(hex);
+  if (!rgb) return null;
+  return 0.2126 * channelLuminance(rgb[0]) + 0.7152 * channelLuminance(rgb[1]) + 0.0722 * channelLuminance(rgb[2]);
 }
 
 function contrastRatio(fg, bg) {
@@ -45,10 +149,9 @@ function contrastRatio(fg, bg) {
 
 // ponytail: a real CSS parser is overkill. Extract token *names* and *values*
 // from :root { --token: value; } so we can tell generated code apart from the
-// system.
-// ponytail: :root variants (:root.dark, :root[data-theme], grouped :root, .x)
-// are standard dark-mode patterns (shadcn, Tailwind, MUI). \b after :root avoids
-// false matches like :rootCause. Matches any combinator/selector up to '{'.
+// system. :root variants (:root.dark, :root[data-theme], grouped :root, .x)
+// are standard dark-mode patterns (shadcn, Tailwind, MUI). \b after :root
+// avoids false matches like :rootCause.
 function extractTokens(css) {
   const tokens = new Map(); // value -> name(s)
   const rootBlock = /:root\b[^{]*\{([^}]*)\}/g;
@@ -60,7 +163,6 @@ function extractTokens(css) {
     while ((decl = declRe.exec(decls)) !== null) {
       const name = decl[1].trim();
       const value = decl[2].trim();
-      // index by normalised value so we can match usage in generated css
       const key = value.toLowerCase().replace(/\s+/g, ' ');
       const existing = tokens.get(key);
       tokens.set(key, existing ? `${existing},--${name}` : `--${name}`);
@@ -69,16 +171,15 @@ function extractTokens(css) {
   return tokens;
 }
 
-// Hardcoded hex colours not referencing a token.
-const RAW_HEX_RE = /#(?:[0-9a-f]{3}|[0-9a-f]{6})\b/gi;
-
-// box-shadow declarations (we only flag these if they DON'T reference a var)
+// ponytail: negative lookahead (?![0-9a-f]) instead of \b — \b fails between
+// adjacent hex digits so 8-digit alpha hex (#RRGGBBAA) was invisible to this
+// gate. Now matches 3/4/6/8-digit hex without partial-matching longer values.
+const RAW_HEX_RE = /#(?:[0-9a-f]{3,4}|[0-9a-f]{6}|[0-9a-f]{8})(?![0-9a-f])/gi;
 const BOX_SHADOW_RE = /box-shadow\s*:\s*([^;}]+)/gi;
 
 function scanOffSystem(css, tokens) {
   const findings = { hardcodedHex: [], adhocShadow: [] };
 
-  // 1. hardcoded hex outside :root token defs (and :root.dark / grouped variants)
   const rootFree = css.replace(/:root\b[^{]*\{[^}]*\}/g, '');
   let hexMatch;
   while ((hexMatch = RAW_HEX_RE.exec(rootFree)) !== null) {
@@ -87,7 +188,6 @@ function scanOffSystem(css, tokens) {
     if (!tokens.has(key)) findings.hardcodedHex.push(hex);
   }
 
-  // 2. box-shadow not built from tokens
   let shadowMatch;
   while ((shadowMatch = BOX_SHADOW_RE.exec(rootFree)) !== null) {
     const val = shadowMatch[1];
@@ -99,15 +199,14 @@ function scanOffSystem(css, tokens) {
 
 // --- state coverage -------------------------------------------------------
 
-// ponytail: presence check, not a CSS parser. Substring tests are enough to
-// catch the common slop (missing :focus-visible / :disabled). Stateful /g
-// regexes with .test() flake across calls, so use plain includes().
+// 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: [] };
 
   const hasInteractive =
     /\b(?:button|a|input|select|textarea)\b/i.test(css) || /\[role\s*=\s*"?button"?\]/i.test(css);
-  if (!hasInteractive) return findings; // no interactive selectors => nothing to flag
+  if (!hasInteractive) return findings;
 
   if (!css.includes(':focus-visible')) findings.missingFocusVisible.push('no :focus-visible rule for interactive elements');
   if (!css.includes(':disabled')) findings.missingDisabled.push('no :disabled rule for interactive elements');
@@ -115,25 +214,118 @@ function scanStates(css) {
   return findings;
 }
 
+// --- slop tells (named AI signatures) -------------------------------------
+// Co-occurrence heuristics, not single-keyword flags, to avoid false positives
+// on legitimate token-based elevation. Each tell is documented with the slop it
+// catches and the conservative pattern that must all match.
+
+function scanSlopTells(css) {
+  const tells = [];
+  const lower = css.toLowerCase();
+
+  // 1. Glassmorphism — backdrop-filter anywhere is the tell.
+  if (lower.includes('backdrop-filter')) {
+    tells.push('glassmorphism (backdrop-filter) — faux depth implying capability the feature lacks');
+  }
+
+  // 2. Gradient orbs — radial-gradient with a violet/purple/indigo hue +
+  //    large blur. The orb signature is a big diffuse coloured blob: check
+  //    for a blue-dominant saturated hex (B > R+20 AND B > G+20) and a large
+  //    blur (filter:blur(NNpx) in the CSS or ≥100px size in the gradient).
+  //    ponytail: allow one level of nested parens (rgba/hsl stops) so the
+  //    full gradient value is captured, not truncated at the first inner ).
+  const hasBigFilterBlur = /blur\(\s*\d{2,}\s*px/i.test(css);
+  const radial = /radial-gradient\(([^()]*(?:\([^()]*\)[^()]*)*)\)/gi;
+  let rm;
+  while ((rm = radial.exec(css)) !== null) {
+    const v = rm[0];
+    const hasVioletHue = [...v.matchAll(/#(?:[0-9a-f]{3}|[0-9a-f]{6})\b/gi)].some((hm) => {
+      const rgb = parseHex(hm[0]);
+      if (!rgb) return false;
+      return rgb[2] > rgb[0] + 20 && rgb[2] > rgb[1] + 20; // B-dominant
+    });
+    const bigBlur = hasBigFilterBlur || /\b\d{3,}px\b/.test(v);
+    if (hasVioletHue && bigBlur) {
+      tells.push('gradient orb (violet/purple radial-gradient with large blur) — the #1 AI-slop signature');
+      break;
+    }
+  }
+
+  // 3. Neon glow — coloured box-shadow with large blur (≥20px). Checks BOTH
+  //    rgba() and hex colours. A normal accent shadow (≤12px blur) is NOT a
+  //    glow; a large coloured blur is the v0/Cursor tell.
+  const shadowRe = /box-shadow\s*:\s*([^;}]+)/gi;
+  let sm;
+  while ((sm = shadowRe.exec(css)) !== null) {
+    const v = sm[1];
+    const pxVals = [...v.matchAll(/(\d+(?:\.\d+)?)px/gi)].map((mm) => parseFloat(mm[1]));
+    const maxPx = pxVals.length ? Math.max(...pxVals) : 0;
+    if (maxPx < 20) continue; // small blur = normal shadow, not glow
+
+    const colours = [];
+    for (const cm of v.matchAll(/rgba?\(\s*(\d+)\s*,\s*(\d+)\s*,\s*(\d+)\s*(?:,\s*([0-9.]+))?\s*\)/gi)) {
+      colours.push([+cm[1], +cm[2], +cm[3], cm[4] !== undefined ? parseFloat(cm[4]) : 1]);
+    }
+    for (const hm of v.matchAll(/#(?:[0-9a-f]{3}|[0-9a-f]{6})\b/gi)) {
+      const rgb = parseHex(hm[0]);
+      if (rgb) colours.push([rgb[0], rgb[1], rgb[2], 1]);
+    }
+    let foundGlow = false;
+    for (const [r, g, b, a] of colours) {
+      const greyish = Math.abs(r - g) < 15 && Math.abs(g - b) < 15;
+      if (!greyish && a >= 0.3) { foundGlow = true; break; }
+    }
+    if (foundGlow) {
+      tells.push('neon glow (coloured large-blur box-shadow) — v0/Cursor signature');
+      break;
+    }
+  }
+
+  // 4. The default card — untouched shadcn reflex. Require rounded-2xl/3xl AND
+  //    shadow-lg/xl AND p-6/p-8 to co-occur (the actual slop reflex).
+  if (/(rounded-(2xl|3xl))/.test(lower) && /(shadow-(lg|xl))/.test(lower) && /\bp-(6|8)\b/.test(lower)) {
+    tells.push('default card (rounded-2xl + shadow-lg + p-6 reflex) — separate with whitespace → bg shift → elevation first');
+  }
+
+  // 5. 1px gray card border — the most reliable single AI tell. Tailwind
+  //    border-zinc/gray defaults OR a literal 1px solid near-gray hex.
+  const tailwindGray = /\bborder-(zinc|gray|slate|neutral)-(?:100|200)\b/.test(lower);
+  const litGrayBorder = /border[^;}]*:\s*1px\s+solid\s+(#(?:e5e7eb|e4e4e7|d4d4d8|f1f5f9|e2e8f0))\b/i.test(css);
+  if (tailwindGray || litGrayBorder) {
+    tells.push('1px gray card border (border-zinc/gray default or near-gray 1px solid) — the most reliable AI tell');
+  }
+
+  return { tells };
+}
+
 // --- aggregate gate -------------------------------------------------------
 
 function audit({ css = '', pairs = [] }) {
-  // pairs: [{ fg: '#000', bg: '#fff', label: 'body', min: 4.5 }]
-  // ponytail: destructure defaults don't cover null — guard explicitly so a
-  // malformed { pairs: null } or { css: null } call behaves like the empty
-  // value, not a throw.
   const safeCss = typeof css === 'string' ? css : '';
   const safePairs = Array.isArray(pairs) ? pairs : [];
   const tokens = extractTokens(safeCss);
   const off = scanOffSystem(safeCss, tokens);
   const states = scanStates(safeCss);
+  const tells = scanSlopTells(safeCss);
 
   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);
+    // 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;
+    if (lc === null) {
+      pass = ratio === null ? false : ratio >= (p.min ?? 4.5);
+    } else {
+      pass = Math.abs(lc) >= apcaMin;
+    }
     return {
       ...p,
+      apca: lc === null ? null : Math.round(lc * 100) / 100,
+      apcaMin,
       ratio: ratio === null ? null : Math.round(ratio * 100) / 100,
-      pass: ratio === null ? false : ratio >= (p.min ?? 4.5),
+      pass,
     };
   });
 
@@ -144,19 +336,28 @@ function audit({ css = '', pairs = [] }) {
       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 },
+      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.missingFocusVisible.length === 0 && states.missingDisabled.length === 0
+      && tells.tells.length === 0,
   };
 }
 
 module.exports = {
+  parseHex,
+  parseOklch,
+  parseColor,
+  sRGBtoY,
+  apcaContrastLc,
+  apcaThreshold,
   channelLuminance,
   relativeLuminance,
   contrastRatio,
   extractTokens,
   scanOffSystem,
   scanStates,
+  scanSlopTells,
   audit,
 };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@bacnh85/pi-ux",
-  "version": "0.3.0",
-  "description": "Anti-slop UI/UX design discipline for your Pi agent — enforces industrial-design principles, runs deterministic slop-audit gates, and ships reference design-system presets.",
+  "version": "0.4.3",
+  "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",
     "pi",

package/skills/ux-design/SKILL.md

@@ -5,11 +5,11 @@ description: >
   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, write a 5-field brief,
-  generate inside constraints, normalise, pass a measurable slop-audit gate.
-  Includes model routing: Gemini/Claude via agy_execute for generation and
-  review, DeepSeek-v4 / GLM-5.2 as the main Pi models for briefs and
-  normalisation. Use when designing or building any UI — web, mobile, or
+  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
+  (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.
 argument-hint: ""
 license: MIT
@@ -18,7 +18,8 @@ license: MIT
 # UX Design Discipline — 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.
+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.
 
 ## The anti-slop guardrail (hard rules)
 
@@ -33,18 +34,42 @@ language. Slop fills the gaps you leave — so you stop leaving gaps.
 
 ## The Constraint-First method
 
-### Step 0 — Own the system (the model must NEVER invent this)
-If these don't exist, don't generate screens yet — keep the model in ideation mode.
+### Step 0 — Own the system via DESIGN.md (the model must NEVER invent this)
+
+**A repo-root `DESIGN.md` is the single source of truth the agent reads before
+styling anything.** Without it, every generation drifts back to the
+statistical average. So own the system BEFORE generating — but you do NOT have
+to block: when DESIGN.md is missing, drop in a medium-tuned preset as the
+implicit system and keep going (see below).
+
+A DESIGN.md (Google Labs open standard) combines machine-readable design tokens
+(YAML frontmatter: `colors`, `typography`, `rounded`, `spacing`, `components`)
+with human-readable rationale (Overview → Colors → Typography → Layout →
+Elevation → Shapes → Components → Do's & Don'ts). This is the anchor the
+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.
+
+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.
-- Reuse an existing system (Material, shadcn/ui, Radix) — YAGNI applies to design systems too.
+- **State contract:** every interactive component declares all states (web: + `:hover`/`:focus-visible`; mobile: + `:active`/pressed, NO hover).
+
+**Lint the system (when persisted to disk):**
+```bash
+npx @google/design.md lint DESIGN.md
+```
+This validates token references, contrast, section order, and structure as structured JSON. pi-ux **orchestrates** `@google/design.md` via shell-out — it is NOT a runtime dependency (pi-ux stays zero-dep).
 
 ### Step 1 — The 5-field brief (one per screen)
 All five are required. If you can't produce inventory + states with confidence, the work is under-specified — more generation will mostly manufacture cleanup debt.
 1. **User job + success state** — one sentence.
 2. **Screen inventory** — required components and actions.
-3. **Token constraints** — palette, type, spacing, elevation (paste the tokens).
+3. **Token constraints** — palette, type, spacing, elevation (paste the DESIGN.md tokens).
 4. **Required interaction states** per interactive component.
 5. **One reference** screen/component that already feels like the product (brand tone).
 
@@ -58,36 +83,57 @@ Replace ad-hoc colours with tokens, remap shadows to the elevation scale, snap s
 
 ### Step 4 — 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).
+
 | Gate | 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 | WCAG AA: 4.5:1 body, 3:1 large/UI | Block handoff until fixed |
+| 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 |
 | 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 |
 
 ## Model routing (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 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** (tokens, elevation, type) | `agy_execute mode=plan pro-high` (Gemini) OR reuse shadcn/Material | Gemini = strongest visual reasoning (~80% UI similarity). Or human-owned preset. |
-| **Per-screen brief** | Main Pi model: **GLM-5.2** | 200K ctx holds the whole system doc while scoping one screen |
-| **Generate variants** | `agy_execute mode=accept-edits flash-high` (Gemini) | Visual king, safe inside constraints |
+| **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 |
-| **Slop audit** | `ux_audit` tool (deterministic) | Contrast + token coverage are computable, not judgement |
-| **Final review/polish** | `agy_execute mode=plan sonnet` (Claude) or `opus` | Cross-family review; Claude = structured, conservative |
+| **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. |
 
-**Cross-family rule:** Gemini produces → Claude-class reviews. Don't spend both quota groups on trivial tasks.
+**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 are safe for design **only inside a fully-specified system**. If no system exists yet, generate it with Gemini via `agy` first, or reuse a preset.
+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.
 
 ## Banned anti-patterns
 
-- Purple/indigo glow gradients unless the brand explicitly calls for them.
+These are auto-detected by `ux_audit`'s slop-tell gate — fail the gate and the
+screen stays in draft until refactored.
+
+- **Glassmorphism** (`backdrop-filter`) — faux depth that implies capability the feature lacks (violates "honest").
+- **Gradient orbs / purple-indigo glow** (large-blur `radial-gradient`, coloured high-opacity `box-shadow`) — the #1 AI-slop signature, unless the brand explicitly calls for it.
+- **Neon-on-dark** (cyan/violet glowing card borders) — the v0/Cursor signature.
+- **The default card** (`rounded-2xl shadow-lg p-6` untouched shadcn reflex) — separate with whitespace → background shift → elevation, in that order; a border is the last resort.
+- **1px gray card border** (`border-zinc`/`border-gray` defaults) — the most reliable AI tell.
+- **Permanent dark mode** as the default reflex — the most common AI tell.
 - Shadows as texture (drifting blur/opacity per component). Shadows = named elevation only.
-- Glassmorphism / faux-3D that implies capability the feature lacks (violates "honest").
 - 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 tokens — the single biggest slop trigger.
+- Prompting "make it modern/clean" with no DESIGN.md — the single biggest slop trigger.

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 copy a compact
-  token set into the project. 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.
+  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 —
+  pi-ux never bundles CSS.
 argument-hint: ""
 license: MIT
 ---
@@ -15,9 +16,9 @@ license: MIT
 # UX System Presets — anti-slop shortcuts for Step 0
 
 The Constraint-First method starts at "Own the system." If the project has no
-tokens / elevation scale / state contract, do NOT generate screens yet — either
-**reuse an existing system** or **copy a compact token set**. This skill is the
-shortcut drawer for both.
+tokens / elevation scale / state contract, you do NOT have to block generation —
+**reuse an existing system** or **drop in a medium-tuned DESIGN.md starter** as
+the implicit system. This skill is the shortcut drawer for both.
 
 ## Option A — reuse an existing system (preferred, YAGNI)
 
@@ -32,11 +33,254 @@ These already define tokens, 3–5 elevation levels, and full state contracts
 which is exactly what the anti-slop guardrail demands. **Reusing beats
 redefining.** YAGNI applies to design systems too.
 
-## Option B — minimal token set (when no framework, or CSS-only)
+### Named styles (Claymorphism, Brutalism, Bento, Art Deco, …)
 
-When there's nothing to reuse, drop this compact baseline into the project's
-`:root` and point the guardrail at it. It satisfies all three audit gates
-(tokens, elevation, states) with ~20 lines.
+When the brief calls for a *named aesthetic* (a kids app wants Claymorphism;
+an agency site wants Brutalism), **do not invent one and do not hand-copy a
+template blindly.** Pull the canonical, lintable `DESIGN.md` from the
+**[design.md style library](https://designmd.app/library)** (30+ styles,
+same `DESIGN.md` standard this skill uses) and run it through the gate:
+
+1. Fetch the style's `DESIGN.md` from `designmd.app/library/<style>`.
+2. `npx @google/design.md lint DESIGN.md` (token-ref + structure validation).
+3. `ux_audit` on the CSS + the style's common text pairs — **block handoff on fail.**
+
+> **No style is pre-approved.** Named-style templates are aesthetic
+> starting points, not vetted systems. The stock **Claymorphism** template
+> ships a button in lilac (`#E6E6FA`) text on peach (`#FDBCB4`) — that pair
+> fails `ux_audit` at **Lc −15.67** (WCAG 1.31:1). Correct it to ink-on-peach
+> (Lc 75.72 ✓) before trusting it. The gate, not the template, makes a style
+> non-slop. Note: glassmorphism and neumorphism are **banned** slop tells
+> here regardless of any library entry.
+
+## Option B — medium-tuned DESIGN.md starters (lintable, drop-in)
+
+When there's nothing to reuse AND no repo-root DESIGN.md, pick the starter
+matching the medium and use it **in-context as the implicit system** — then
+keep generating. This is how the agent stays unblocked and non-slop when
+DESIGN.md is absent. Lint it (and optionally persist it to repo root) when the
+user wants to keep it:
+
+```bash
+npx @google/design.md lint DESIGN.md
+```
+
+### Which medium? (infer, then ask only if genuinely unclear)
+
+- **Web** — landing page, dashboard, marketing site, admin panel, "responsive", docs, anything mouse + keyboard. Default when the target is a browser at desktop/tablet width.
+- **Mobile** — "iOS/Android app", native (SwiftUI/Kotlin), React Native/Flutter, mobile-first PWA, "screen" for a phone, anything touch-first.
+- Ambiguous (e.g. "a screen", no platform) → **ASK** which medium; do not guess. This is the one decision worth a question, because it changes touch targets, hover, and safe areas.
+
+### B1 — Web preset (mouse + keyboard, responsive)
+
+```markdown
+---
+name: Web Baseline
+description: Anti-slop web system — one accent + neutrals, hover + focus-visible, desktop type scale, 65ch measure.
+colors:
+  primary: "#111111"
+  accent: "#0066ff"
+  accent-hover: "#0052cc"
+  text: "#111111"
+  text-muted: "#595959"
+  bg: "#ffffff"
+  surface: "#f7f7f8"
+  border: "#e4e4e7"
+  danger: "#c2261b"
+  success: "#15803d"
+typography:
+  body:
+    fontFamily: Inter
+    fontSize: 1rem
+    lineHeight: 1.6
+  h1:
+    fontFamily: Inter
+    fontSize: 2.441rem
+    fontWeight: 700
+    lineHeight: 1.15
+  h2:
+    fontFamily: Inter
+    fontSize: 1.953rem
+    fontWeight: 700
+  label:
+    fontFamily: Inter
+    fontSize: 0.8rem
+    fontWeight: 600
+    letterSpacing: 0.02em
+rounded:
+  sm: 6px
+  md: 10px
+  lg: 14px
+spacing:
+  sm: 8px
+  md: 16px
+  lg: 24px
+  xl: 32px
+  2xl: 48px
+components:
+  button-primary:
+    backgroundColor: "{colors.accent}"
+    textColor: "#ffffff"
+    rounded: "{rounded.md}"
+    padding: "{spacing.sm} {spacing.md}"
+  button-primary-hover:
+    backgroundColor: "{colors.accent-hover}"
+  card:
+    backgroundColor: "{colors.surface}"
+    rounded: "{rounded.lg}"
+    padding: "{spacing.lg}"
+  input:
+    backgroundColor: "{colors.bg}"
+    textColor: "{colors.text}"
+    rounded: "{rounded.sm}"
+---
+
+## Overview
+
+Desktop/responsive web. One accent, neutral surfaces, hierarchy by weight.
+Separation by whitespace → background shift → elevation, in that order; a border
+is the last resort.
+
+## Colors
+
+- **primary (#111111):** deep ink for headlines and primary text.
+- **accent (#0066ff):** the sole driver for interaction. The ONE knob to swap for brand.
+- **text-muted (#595959):** secondary copy, captions, metadata.
+- **bg/surface:** warm-tinted off-whites, softer than pure white. Tint pure black/white warm or cool for depth.
+- **danger/success:** reserved for semantic state, never decoration.
+
+## Typography
+
+Inter, hierarchy by weight on a 1.25 modular scale. Body at 1rem / 1.6 line-height.
+Hold the measure (line length) to 60–80 characters for readability.
+
+## Layout
+
+- 8px spacing grid; no magic pixel values. Section padding varies so hero/content/CTA don't feel the same weight.
+- Responsive: max-width container (e.g. 1152px), 12-column awareness, breakpoints at 640/768/1024/1280.
+
+## Elevation & Depth
+
+Map EVERY shadow to a named level — never invent blur/opacity per component:
+`sm` resting card · `md` raised/dropdown · `lg` popover · `xl` modal.
+
+## Do's and Don'ts
+
+- DO declare `default` / `hover` / `focus-visible` / `active` / `disabled` for every interactive element — keyboard nav is primary on web.
+- DON'T use `backdrop-filter`, gradient orbs, coloured glow, or a 1px gray card border — the AI-slop signatures.
+- DON'T ship pure `#fff`/`#000`; tint them.
+```
+
+### B2 — Mobile preset (touch-first, native / RN / mobile web)
+
+```markdown
+---
+name: Mobile Baseline
+description: Anti-slop mobile system — 44pt touch targets, no hover (tap/active), safe-area insets, 16px base (no zoom).
+colors:
+  primary: "#111111"
+  accent: "#0066ff"
+  accent-pressed: "#0052cc"
+  text: "#111111"
+  text-muted: "#595959"
+  bg: "#ffffff"
+  surface: "#f7f7f8"
+  border: "#e4e4e7"
+  danger: "#c2261b"
+typography:
+  body:
+    fontFamily: Inter
+    fontSize: 1rem
+    lineHeight: 1.5
+  h1:
+    fontFamily: Inter
+    fontSize: 1.953rem
+    fontWeight: 700
+    lineHeight: 1.2
+  h2:
+    fontFamily: Inter
+    fontSize: 1.563rem
+    fontWeight: 700
+  label:
+    fontFamily: Inter
+    fontSize: 0.875rem
+    fontWeight: 600
+rounded:
+  sm: 8px
+  md: 12px
+  lg: 16px
+spacing:
+  sm: 8px
+  md: 16px
+  lg: 24px
+  xl: 32px
+components:
+  button-primary:
+    backgroundColor: "{colors.accent}"
+    textColor: "#ffffff"
+    rounded: "{rounded.md}"
+    height: 48px
+    padding: "{spacing.md} {spacing.lg}"
+  button-primary-pressed:
+    backgroundColor: "{colors.accent-pressed}"
+  tap-target:
+    height: 44px
+    width: 44px
+  list-row:
+    backgroundColor: "{colors.bg}"
+    textColor: "{colors.text}"
+    padding: "{spacing.md} {spacing.lg}"
+  tab-bar:
+    backgroundColor: "{colors.bg}"
+    height: 56px
+---
+
+## Overview
+
+Touch-first mobile (iOS / Android / React Native / Flutter / mobile web). One
+accent, generous gutters, thumb-reach layout. Interaction is TAP, not hover.
+
+## Colors
+
+- **primary (#111111):** ink for headings and primary text.
+- **accent (#0066ff):** the sole driver for interaction. The ONE knob to swap for brand.
+- **accent-pressed:** replaces hover — the feedback state for a tap.
+- **bg/surface:** layered to separate content; tint pure black/white warm or cool.
+
+## Typography
+
+Inter on a 1.2 scale. **Body at 16px minimum** — below 16px, iOS Safari
+auto-zooms on input focus, which is slop. Hierarchy by weight, not by shrinking
+the body.
+
+## Layout
+
+- 16px gutters, 24px section padding (thumb ergonomics).
+- Thumb zone: primary actions reachable from the bottom third; place destructive actions away from the thumb arc.
+- Safe-area insets for notch and home indicator: `env(safe-area-inset-top/bottom)` (web), or platform safe-area guides (native).
+- Bottom-anchored patterns: tab bar, bottom sheet, FAB.
+
+## Elevation & Depth
+
+Named levels only: `sm` resting · `md` raised sheet · `lg` modal. A bottom sheet
+is nearer than the page — keep it that way.
+
+## Do's and Don'ts
+
+- DO make every interactive element ≥ 44pt (iOS HIG) / 48dp (Material) — the #1 thing models get wrong.
+- DO use `:active` / pressed states for tap feedback — there is NO hover on touch. Do not ship `:hover`-only feedback.
+- DO respect safe areas (notch, home indicator, keyboard).
+- DON'T use `backdrop-filter`, gradient orbs, coloured glow, or 1px gray borders — AI-slop signatures on mobile too.
+- DON'T set body text below 16px (triggers iOS zoom).
+- iOS vs Android: follow the host platform — iOS HIG (SF symbols, larger corner radius, sheet) vs Material 3 (FAB, ripple, top app bar).
+```
+
+## 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
+into the project's `:root`. It satisfies the token + elevation + state gates of
+`ux_audit` with ~20 lines. Prefer Option B when the project can adopt DESIGN.md
+— it is lintable, diffable, and medium-tuned; this is the plain fallback.
 
 ```css
 :root {
@@ -84,22 +328,24 @@ When there's nothing to reuse, drop this compact baseline into the project's
 
 ## How to use with ux-design
 
-1. Run **Step 0** of ux-design. If the project already has tokens/elevation/states → use them.
-2. If not, pick **Option A** (reuse shadcn/Material/Radix) first. This is the lazy, correct path.
-3. Only if nothing fits, copy **Option B** into the project and adapt `--accent` to the brand.
-4. Generate screens with `agy flash-high` INSIDE these constraints.
-5. Run `ux_audit` with the CSS + the 5 most common text colour pairs before handoff.
+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.
+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.
 
-## Audit-ready pairs for the minimal set
+## Audit-ready pairs
 
 ```jsonc
-// Pass these to ux_audit.pairs to check the baseline itself.
+// Pass these to ux_audit.pairs to check a baseline itself.
+// weight/size enable the APCA thresholds; min is the WCAG compliance sidecar.
 [
-  { "fg": "#111111", "bg": "#ffffff", "label": "body",       "min": 4.5 },
-  { "fg": "#595959", "bg": "#ffffff", "label": "muted",      "min": 4.5 },
-  { "fg": "#0066ff", "bg": "#ffffff", "label": "accent-link","min": 4.5 },
-  { "fg": "#ffffff", "bg": "#0066ff", "label": "button",     "min": 4.5 },
-  { "fg": "#c2261b", "bg": "#ffffff", "label": "danger",     "min": 4.5 }
+  { "fg": "#111111", "bg": "#ffffff", "label": "body",        "min": 4.5, "weight": 400, "size": 16 },
+  { "fg": "#595959", "bg": "#ffffff", "label": "muted",       "min": 4.5, "weight": 400, "size": 16 },
+  { "fg": "#0066ff", "bg": "#ffffff", "label": "accent-link", "min": 4.5, "weight": 400, "size": 16 },
+  { "fg": "#ffffff", "bg": "#0066ff", "label": "button",      "min": 4.5, "weight": 600, "size": 16 },
+  { "fg": "#c2261b", "bg": "#ffffff", "label": "danger",      "min": 4.5, "weight": 400, "size": 16 }
 ]
 ```
 
@@ -107,4 +353,4 @@ When there's nothing to reuse, drop this compact baseline into the project's
 
 - 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` is the ONE knob you turn for brand.
+- Not opinionated about the accent — `accent` / `{colors.accent}` is the ONE knob you turn for brand.