@bacnh85/pi-ux 0.3.0

package/AGENTS.md

@@ -0,0 +1,29 @@
+# pi-ux
+
+Anti-slop UI/UX design discipline extension. Forks the pi-ponytail shape
+(hook + command + skill) for design discipline instead of code laziness.
+
+Before writing any code here, stop at the first rung that holds:
+
+1. Does this need to be built at all? (YAGNI)
+2. Does it already exist in this codebase? Reuse it.
+3. Does the standard library already do this? Use it.
+4. Can it be one line? Make it one line.
+5. Only then: write the minimum code that works.
+
+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 only makes sure their output lands inside a defensible design system.
+
+## What NOT to build here
+
+- ❌ A design-token generator (use agy/Gemini or reuse shadcn/ui).
+- ❌ A bundled CSS framework (reference only).
+- ❌ A UI renderer (that's agy + the main model's job).
+- ❌ TypeScript (plain JS like ponytail — zero deps).
+
+## Test
+
+```bash
+npm test   # node --test extensions/test/*.test.js
+```

package/CHANGELOG.md

@@ -0,0 +1,33 @@
+# Changelog
+
+## 0.3.0
+
+- **`ux_audit` tool (deterministic slop-audit gate).** New LLM-callable tool
+  that runs three computable gates — no model needed:
+  - **Contrast**: WCAG 2.x relative-luminance ratio for fg/bg colour pairs
+    (4.5:1 body, 3:1 large/UI).
+  - **Tokens**: flags hardcoded hex outside `:root` token defs and `box-shadow`
+    declarations not built from `var(--…)` tokens.
+  - **States**: flags interactive selectors (`button`/`a`/`input`/…/`[role=button]`)
+    missing `:focus-visible` or `:disabled` rules.
+  - Returns a pass/fail per gate + a formatted report. In `strict` mode this is
+    the gate that blocks handoff.
+- **`ux-presets` skill.** Reference design-system presets for Step 0 (Own the
+  system) of the ux-design method — no bundled CSS. Option A: reuse
+  shadcn/ui, Material 3, Radix, or Park/Ark UI (YAGNI-first). Option B: a
+  compact ~20-line token set (one accent + neutrals, modular type scale, 8px
+  spacing grid, 4 named elevation levels) plus audit-ready colour pairs.
+- Zero dependencies retained (WCAG math is 10 lines; token scan is regex;
+  state scan is substring checks). Plain JS, `node --test`.
+
+## 0.1.0
+
+- Initial release.
+- Anti-slop guardrail via `before_agent_start` hook (enforced, not ignorable).
+- `/ux` command: `lite | strict | off | status | default <mode>`.
+- `skills/ux-design/SKILL.md`: full Constraint-First method + model routing
+  (Gemini/Claude via `agy_execute`, DeepSeek-v4 / GLM-5.2 as main Pi models).
+- Modes: `lite` (guardrail only), `strict` (guardrail + audit gate, default).
+- Config via env (`PI_UX_DEFAULT_MODE`, `PI_UX_QUIET_STARTUP`,
+  `PI_UX_HIDE_STATUS`) and `~/.config/pi-ux/config.json`.
+- Zero dependencies (plain JS, `node --test`).

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 bacnh85
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,102 @@
+# 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.
+
+## 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.
+
+## Install
+
+```bash
+npm install @bacnh85/pi-ux
+```
+
+Pi auto-discovers the extension and skill.
+
+## Usage
+
+```
+/ux              # toggle / show status
+/ux strict       # guardrail + enforce ux_audit gate before handoff (default)
+/ux lite         # guardrail only (ideation, exploration)
+/ux off          # disable
+/ux status       # current + default mode
+/ux default lite # persist default mode
+```
+
+The guardrail is injected into the system prompt on every agent start while active. Turn off with `/ux off` or the phrases "stop ux" / "normal mode".
+
+## Modes
+
+| Mode | Behavior |
+|------|----------|
+| `off` | No guardrail |
+| `lite` | Anti-slop guardrail enforced; audit gate recommended but not blocking |
+| `strict` (default) | Guardrail + enforce `ux_audit` gate before declaring a screen done |
+
+## The method
+
+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.
+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.
+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.
+
+## 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}]
+```
+
+| Gate | What it checks |
+|------|----------------|
+| **Contrast** | WCAG 2.x relative-luminance ratio for each fg/bg pair (4.5:1 body, 3:1 large/UI) |
+| **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` |
+
+Returns pass/fail per gate + a formatted report. In `strict` mode this is the gate that blocks handoff.
+
+## Skills
+
+- **`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.
+
+The skill tells the agent which model to use for each step:
+
+| 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) |
+| Normalise into system | **DeepSeek-v4** or **GLM-5.2** |
+| Slop audit | `ux_audit` tool (deterministic) |
+| Final review/polish | `agy_execute mode=plan sonnet` (Claude) |
+
+**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.
+
+## Configuration
+
+Environment variables (override config file):
+
+| Variable | Default | Effect |
+|----------|---------|--------|
+| `PI_UX_DEFAULT_MODE` | `strict` | Default mode on startup |
+| `PI_UX_QUIET_STARTUP` | unset | Suppress the startup toast |
+| `PI_UX_HIDE_STATUS` | unset | Hide the status-bar indicator |
+
+Config file: `~/.config/pi-ux/config.json` (or `$XDG_CONFIG_HOME/pi-ux/`):
+
+```json
+{ "defaultMode": "strict", "quietStartup": false, "hideStatus": false }
+```
+
+## License
+
+MIT

package/extensions/index.js

@@ -0,0 +1,252 @@
+import { createRequire } from "node:module";
+
+const require = createRequire(import.meta.url);
+const {
+  DEFAULT_MODE,
+  RUNTIME_MODES,
+  getDefaultMode,
+  getQuietStartup,
+  getHideStatus,
+  normalizeMode,
+  normalizePersistedMode,
+  isDeactivationCommand,
+  writeDefaultMode,
+} = require("../hooks/ux-config.js");
+const { getUxInstructions } = require("../hooks/ux-instructions.js");
+const { audit } = require("../hooks/ux-audit.js");
+
+export const readDefaultMode = getDefaultMode;
+export const readQuietStartup = getQuietStartup;
+
+export function resolveSessionMode(entries, fallbackMode = DEFAULT_MODE) {
+  const fallback = normalizePersistedMode(fallbackMode) || DEFAULT_MODE;
+  if (!Array.isArray(entries)) return fallback;
+
+  for (let i = entries.length - 1; i >= 0; i -= 1) {
+    const entry = entries[i];
+    if (entry?.type !== "custom" || entry?.customType !== "ux-mode") continue;
+
+    const mode = normalizePersistedMode(entry?.data?.mode);
+    if (mode) return mode;
+  }
+
+  return fallback;
+}
+
+export function parseUxCommand(text, defaultMode = DEFAULT_MODE) {
+  const fallback = normalizePersistedMode(defaultMode) || DEFAULT_MODE;
+  const normalizedText = String(text || "").trim().toLowerCase();
+
+  if (!normalizedText) {
+    return { type: "set-mode", mode: fallback === "off" ? "strict" : fallback };
+  }
+
+  const [primary, secondary] = normalizedText.split(/\s+/);
+
+  if (primary === "status") return { type: "status" };
+
+  if (primary === "default") {
+    // ponytail: a default must be a runtime level, not a session-only mode.
+    const mode = normalizeMode(secondary);
+    return mode ? { type: "set-default", mode } : { type: "invalid", reason: "invalid-default-mode" };
+  }
+
+  const mode = normalizeMode(primary);
+  return mode ? { type: "set-mode", mode } : { type: "invalid", reason: "invalid-mode", mode: primary };
+}
+
+export { writeDefaultMode };
+
+// ponytail: plain JSON-schema object, not TypeBox — at runtime the symbols are
+// stripped on JSON.stringify anyway, and we keep zero deps. Shape matches what
+// Type.Object produces for the LLM tool spec.
+function auditParametersSchema() {
+  return {
+    type: "object",
+    additionalProperties: false,
+    properties: {
+      css: {
+        type: "string",
+        description: "CSS stylesheet content to audit (inline stylesheets, styled-components output, or a concatenated .css file).",
+      },
+      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).",
+        items: {
+          type: "object",
+          additionalProperties: false,
+          properties: {
+            fg: { type: "string", description: "Foreground colour, e.g. '#111111'." },
+            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." },
+          },
+          required: ["fg", "bg"],
+        },
+      },
+    },
+  };
+}
+
+function formatAuditResult(result) {
+  const lines = [];
+  lines.push(result.pass ? "✅ UX AUDIT PASSED" : "❌ UX AUDIT FAILED");
+  lines.push("");
+
+  const c = result.gates.contrast;
+  lines.push(c.pass ? "✓ Contrast" : "✗ Contrast");
+  for (const r of c.results) {
+    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})`);
+  }
+
+  const t = result.gates.tokens;
+  lines.push(t.pass ? "✓ Tokens" : "✗ Tokens");
+  for (const h of t.hardcodedHex) lines.push(`  ✗ hardcoded hex: ${h}`);
+  for (const s of t.adhocShadow) lines.push(`  ✗ ad-hoc box-shadow: ${s}`);
+
+  const s = result.gates.states;
+  lines.push(s.pass ? "✓ States" : "✗ States");
+  for (const m of s.missingFocusVisible) lines.push(`  ✗ ${m}`);
+  for (const m of s.missingDisabled) lines.push(`  ✗ ${m}`);
+
+  return lines.join("\n");
+}
+
+export default function uxExtension(pi) {
+  let currentMode = DEFAULT_MODE;
+  let configuredDefaultMode = getDefaultMode();
+  let hideStatus = getHideStatus();
+
+  function syncStatus(ctx) {
+    if (hideStatus) return;
+    if (!ctx?.ui?.setStatus) return;
+    // ponytail: try/catch guards against theme proxy throwing before init.
+    let theme;
+    try { theme = ctx.ui.theme; if (!theme?.fg) return; } catch { return; }
+    if (currentMode === "off") {
+      try { ctx.ui.setStatus("ux", ""); } catch { return; }
+      return;
+    }
+    const levelIcons = { lite: "🎨", strict: "📐" };
+    const icon = levelIcons[currentMode] || "";
+    const label = currentMode.toUpperCase();
+    try {
+      ctx.ui.setStatus("ux", " 🎨 " + theme.fg("muted", "ux: ") + theme.fg("text", icon + " " + label));
+    } catch { return; }
+  }
+
+  const setMode = (mode, ctx) => {
+    const normalized = normalizePersistedMode(mode);
+    if (!normalized) return;
+
+    pi.appendEntry("ux-mode", { mode: normalized });
+    currentMode = normalized;
+    syncStatus(ctx);
+  };
+
+  pi.registerTool({
+    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)",
+    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.",
+      "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 : "";
+      const pairs = Array.isArray(params.pairs) ? params.pairs : [];
+      const result = audit({ css, pairs });
+      return {
+        content: [{ type: "text", text: formatAuditResult(result) }],
+        details: result,
+      };
+    },
+  });
+
+  pi.registerCommand("ux", {
+    description: `Anti-slop UI/UX discipline. Modes: ${RUNTIME_MODES.join("|")}. Commands: status, default <mode>`,
+    handler: async (args, ctx) => {
+      const parsed = parseUxCommand(args, configuredDefaultMode);
+
+      if (parsed.type === "status") {
+        ctx?.ui?.notify?.(`UX: current ${currentMode} • default ${configuredDefaultMode}`, "info");
+        return;
+      }
+
+      if (parsed.type === "set-default") {
+        try {
+          const written = writeDefaultMode(parsed.mode);
+          if (written) {
+            configuredDefaultMode = getDefaultMode();
+            const message = configuredDefaultMode === written
+              ? `Default UX mode set to ${written}.`
+              : `Saved default ${written}, but env override keeps default at ${configuredDefaultMode}.`;
+            ctx?.ui?.notify?.(message, "info");
+          } else {
+            ctx?.ui?.notify?.(`Invalid default mode. Use: lite, strict, or off.`, "warning");
+          }
+        } catch (e) {
+          ctx?.ui?.notify?.(`Failed to save default mode: ${e.message}`, "error");
+        }
+        return;
+      }
+
+      if (parsed.type === "set-mode") {
+        setMode(parsed.mode, ctx);
+        ctx?.ui?.notify?.(`UX discipline: ${parsed.mode}`, "info");
+        return;
+      }
+
+      if (parsed.type === "invalid") {
+        const msg = parsed.reason === "invalid-default-mode"
+          ? "Invalid default mode. Use: lite, strict, or off."
+          : `Unknown mode: ${parsed.mode}. Use: lite, strict, off, status, or default <mode>.`;
+        ctx?.ui?.notify?.(msg, "warning");
+        return;
+      }
+
+      ctx?.ui?.notify?.("Unknown or unsupported /ux mode.", "warning");
+    },
+  });
+
+  pi.on("input", async (event, ctx) => {
+    if (event?.source === "extension") return;
+
+    const text = String(event?.text || "");
+    if (currentMode !== "off" && isDeactivationCommand(text)) {
+      setMode("off", ctx);
+    }
+  });
+
+  pi.on("agent_start", async (_event, ctx) => {
+    syncStatus(ctx);
+  });
+
+  pi.on("agent_end", async (_event, ctx) => {
+    syncStatus(ctx);
+  });
+
+  pi.on("session_start", async (_event, ctx) => {
+    const entries = ctx?.sessionManager?.getBranch?.() || ctx?.sessionManager?.getEntries?.() || [];
+    configuredDefaultMode = getDefaultMode();
+    hideStatus = getHideStatus();
+    currentMode = resolveSessionMode(entries, configuredDefaultMode);
+    syncStatus(ctx);
+    if (!getQuietStartup()) {
+      ctx?.ui?.notify?.(`pi-ux loaded: ${currentMode}`, "info");
+    }
+  });
+
+  pi.on("before_agent_start", async (event) => {
+    if (!currentMode || currentMode === "off") return;
+    // Guard null/undefined event and missing systemPrompt.
+    const base = event?.systemPrompt ? `${event.systemPrompt}\n\n` : "";
+    return { systemPrompt: `${base}${getUxInstructions(currentMode)}` };
+  });
+}

package/extensions/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "module"
+}

package/hooks/ux-audit.js

@@ -0,0 +1,162 @@
+// 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.
+//   2. Tokens    — off-system values (raw hex, magic px, ad-hoc shadows).
+//   3. States    — interactive elements missing focus-visible / disabled.
+//
+// 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.
+
+// --- WCAG contrast --------------------------------------------------------
+
+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);
+}
+
+function contrastRatio(fg, bg) {
+  const l1 = relativeLuminance(fg);
+  const l2 = relativeLuminance(bg);
+  if (l1 === null || l2 === null) return null;
+  const light = Math.max(l1, l2);
+  const dark = Math.min(l1, l2);
+  return (light + 0.05) / (dark + 0.05);
+}
+
+// --- token coverage -------------------------------------------------------
+
+// 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 '{'.
+function extractTokens(css) {
+  const tokens = new Map(); // value -> name(s)
+  const rootBlock = /:root\b[^{]*\{([^}]*)\}/g;
+  let rootMatch;
+  while ((rootMatch = rootBlock.exec(css)) !== null) {
+    const decls = rootMatch[1];
+    const declRe = /--([a-zA-Z0-9-]+)\s*:\s*([^;]+);/g;
+    let decl;
+    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}`);
+    }
+  }
+  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)
+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) {
+    const hex = hexMatch[0];
+    const key = hex.toLowerCase();
+    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];
+    if (!/var\(--/.test(val)) findings.adhocShadow.push(val.trim());
+  }
+
+  return findings;
+}
+
+// --- 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().
+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 (!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');
+
+  return findings;
+}
+
+// --- 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 contrastResults = safePairs.map((p) => {
+    const ratio = contrastRatio(p.fg, p.bg);
+    return {
+      ...p,
+      ratio: ratio === null ? null : Math.round(ratio * 100) / 100,
+      pass: ratio === null ? false : ratio >= (p.min ?? 4.5),
+    };
+  });
+
+  const contrastPass = contrastResults.every((r) => r.pass);
+
+  return {
+    gates: {
+      contrast: { pass: contrastPass, results: contrastResults },
+      tokens: { pass: off.hardcodedHex.length === 0 && off.adhocShadow.length === 0, ...off },
+      states: { pass: states.missingFocusVisible.length === 0 && states.missingDisabled.length === 0, ...states },
+    },
+    pass: contrastPass
+      && off.hardcodedHex.length === 0 && off.adhocShadow.length === 0
+      && states.missingFocusVisible.length === 0 && states.missingDisabled.length === 0,
+  };
+}
+
+module.exports = {
+  channelLuminance,
+  relativeLuminance,
+  contrastRatio,
+  extractTokens,
+  scanOffSystem,
+  scanStates,
+  audit,
+};

package/hooks/ux-config.js

@@ -0,0 +1,108 @@
+// pi-ux — shared configuration resolver
+//
+// Resolution order for default mode:
+//   1. PI_UX_DEFAULT_MODE environment variable
+//   2. Config file defaultMode field (XDG_CONFIG_HOME/pi-ux/config.json)
+//   3. 'strict'
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const DEFAULT_MODE = 'strict';
+const RUNTIME_MODES = ['off', 'lite', 'strict'];
+
+function normalizeMode(mode) {
+  if (typeof mode !== 'string') return null;
+  const normalized = mode.trim().toLowerCase();
+  return RUNTIME_MODES.includes(normalized) ? normalized : null;
+}
+
+function normalizePersistedMode(mode) {
+  return normalizeMode(mode);
+}
+
+function isDeactivationCommand(text) {
+  const t = String(text || '').trim().toLowerCase().replace(/[.!?\s]+$/, '');
+  return t === 'stop ux' || t === 'normal mode';
+}
+
+function getConfigDir() {
+  if (process.env.XDG_CONFIG_HOME) {
+    return path.join(process.env.XDG_CONFIG_HOME, 'pi-ux');
+  }
+  if (process.platform === 'win32') {
+    return path.join(
+      process.env.APPDATA || path.join(os.homedir(), 'AppData', 'Roaming'),
+      'pi-ux'
+    );
+  }
+  return path.join(os.homedir(), '.config', 'pi-ux');
+}
+
+function getConfigPath() {
+  return path.join(getConfigDir(), 'config.json');
+}
+
+function readConfig() {
+  try {
+    const raw = fs.readFileSync(getConfigPath(), 'utf8').replace(/^\uFEFF/, '');
+    const config = JSON.parse(raw);
+    if (config && typeof config === 'object') return config;
+  } catch (_) {}
+  return {};
+}
+
+function readConfigBool(envVar, configKey) {
+  const env = process.env[envVar];
+  if (env !== undefined) {
+    const v = env.trim().toLowerCase();
+    return v !== '' && v !== '0' && v !== 'false' && v !== 'no';
+  }
+  return readConfig()[configKey] === true;
+}
+
+function getDefaultMode() {
+  const envMode = process.env.PI_UX_DEFAULT_MODE;
+  if (envMode && RUNTIME_MODES.includes(envMode.toLowerCase())) {
+    return envMode.toLowerCase();
+  }
+  const config = readConfig();
+  if (config.defaultMode && RUNTIME_MODES.includes(config.defaultMode.toLowerCase())) {
+    return config.defaultMode.toLowerCase();
+  }
+  return DEFAULT_MODE;
+}
+
+function getQuietStartup() {
+  return readConfigBool('PI_UX_QUIET_STARTUP', 'quietStartup');
+}
+
+function getHideStatus() {
+  return readConfigBool('PI_UX_HIDE_STATUS', 'hideStatus');
+}
+
+function writeDefaultMode(mode) {
+  const normalized = normalizeMode(mode);
+  if (!normalized) return null;
+
+  const config = readConfig();
+  config.defaultMode = normalized;
+
+  const configPath = getConfigPath();
+  fs.mkdirSync(path.dirname(configPath), { recursive: true });
+  fs.writeFileSync(configPath, JSON.stringify(config, null, 2), 'utf8');
+  return normalized;
+}
+
+module.exports = {
+  DEFAULT_MODE,
+  RUNTIME_MODES,
+  getDefaultMode,
+  getQuietStartup,
+  getHideStatus,
+  normalizeMode,
+  normalizePersistedMode,
+  isDeactivationCommand,
+  writeDefaultMode,
+};

package/hooks/ux-instructions.js

@@ -0,0 +1,42 @@
+// Shared pi-ux instruction builder for Claude hooks and Pi extension.
+//
+// Reads the skill body, strips frontmatter, prepends a mode banner.
+// ponytail: no per-mode row filtering needed here — the UX method is mode-
+// invariant; only the banner differs (strict enforces the audit gate).
+
+const fs = require('fs');
+const path = require('path');
+const { DEFAULT_MODE, normalizeMode, normalizePersistedMode } = require('./ux-config');
+const SKILL_PATH = path.join(__dirname, '..', 'skills', 'ux-design', 'SKILL.md');
+
+function getUxInstructions(mode) {
+  const configuredMode = normalizePersistedMode(mode) || DEFAULT_MODE;
+  const effectiveMode = normalizeMode(configuredMode) || DEFAULT_MODE;
+
+  const banner = effectiveMode === 'strict'
+    ? 'UX DISCIPLINE ACTIVE — level: strict. Run ux_audit before declaring a screen done; block handoff on fail.'
+    : 'UX DISCIPLINE ACTIVE — level: lite. Anti-slop guardrail enforced; audit gate recommended but not blocking.';
+
+  try {
+    const body = String(fs.readFileSync(SKILL_PATH, 'utf8')).replace(/^---[\s\S]*?---\s*/, '');
+    return banner + '\n\n' + body;
+  } catch (e) {
+    // ponytail: SKILL.md missing or unreadable — compact inline fallback keeps the guardrail.
+    return [
+      banner,
+      '',
+      'You implement UI INSIDE an existing design system. You do NOT invent visual language.',
+      '- Tokens ONLY (colour/type/spacing/radius/elevation). No off-system values.',
+      '- Elevation: named levels only. Never invent shadow blur/opacity.',
+      '- Accent: ONLY the defined accent token. No purple/indigo glow unless requested.',
+      '- Type: modular scale only. No custom font sizes.',
+      '- Spacing: 8px grid via tokens. No magic pixel values.',
+      '- Every interactive element declares: default, hover, focus-visible, active, disabled',
+      '  + error/empty/loading where relevant.',
+      '- Before markup: output a 1-line inventory of components + states.',
+      '- If ambiguous, ASK. Do not guess aesthetics.',
+    ].join('\n');
+  }
+}
+
+module.exports = { getUxInstructions };

package/package.json

@@ -0,0 +1,43 @@
+{
+  "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.",
+  "keywords": [
+    "pi-package",
+    "pi",
+    "ux",
+    "ui",
+    "design",
+    "anti-slop",
+    "skills"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/bacnh85/pi-extensions.git"
+  },
+  "files": [
+    "AGENTS.md",
+    "README.md",
+    "CHANGELOG.md",
+    "hooks/",
+    "skills/",
+    "extensions/index.js",
+    "extensions/package.json",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --test extensions/test/*.test.js"
+  },
+  "pi": {
+    "extensions": [
+      "./extensions/index.js"
+    ],
+    "skills": [
+      "./skills"
+    ]
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/skills/ux-design/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: ux-design
+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, 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
+  desktop. Active via /ux lite|strict|off.
+argument-hint: ""
+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.
+
+## The anti-slop guardrail (hard rules)
+
+- **Tokens ONLY** — colour, type, spacing, radius, elevation. No off-system values.
+- **Elevation:** named levels only (sm/md/lg/xl). Never invent shadow blur/opacity. A modal is nearer than a card; a dropdown nearer than the page — and it stays that way whoever edited last.
+- **Accent:** ONLY the defined accent token. No purple/indigo gradients. No glow unless explicitly requested. (Glow is the #1 AI-slop signature.)
+- **Type:** modular scale only (e.g. 1.25 ratio). No custom font sizes.
+- **Spacing:** 8px grid via tokens. No magic pixel values.
+- **States:** every interactive element declares `default`, `hover`, `focus-visible`, `active`, `disabled` + `error`/`empty`/`loading` where relevant.
+- **Inventory first:** before writing markup, output a 1-line inventory of components + states you will produce.
+- **Ambiguity = ask.** If a requirement is ambiguous, ASK. Do not guess aesthetics.
+
+## 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.
+- **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.
+
+### 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).
+4. **Required interaction states** per interactive component.
+5. **One reference** screen/component that already feels like the product (brand tone).
+
+### Step 2 — Generate fast, converge early
+Generate several variants, commit early to the direction with the clearest hierarchy under real content.
+- **Convergence trigger:** after two generate-revise loops, variants must visibly converge toward your constraints. If they don't, tighten the brief first — prompting forever compounds drift.
+
+### Step 3 — Normalise the draft into the system
+Replace ad-hoc colours with tokens, remap shadows to the elevation scale, snap spacing to the rhythm, turn one-offs into component variants.
+- Gate: sample 10 components, verify token mapping. If fewer than 8 map cleanly, stop and repair the baseline.
+
+### Step 4 — Slop-audit gate (blocks handoff on fail)
+
+| 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 |
+| State coverage | all interactive elements have focus + disabled | Keep in draft |
+| Component hygiene | no duplicates, no frame-pile | Refactor before handoff |
+
+## 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.
+
+| 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 |
+| **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 |
+
+**Cross-family rule:** Gemini produces → Claude-class reviews. Don't spend both quota groups on trivial tasks.
+
+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.
+
+## Banned anti-patterns
+
+- Purple/indigo glow gradients unless the brand explicitly calls for them.
+- 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.

package/skills/ux-presets/SKILL.md

@@ -0,0 +1,110 @@
+---
+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.
+argument-hint: ""
+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.
+
+## Option A — reuse an existing system (preferred, YAGNI)
+
+| System | When | Install |
+|---|---|---|
+| **shadcn/ui** | React/Next, want copy-in components you own | `npx shadcn@latest init` — copies component source into your repo, not a dependency |
+| **Material 3 (MUI)** | Want the full Material system, theming maturity | `@mui/material` + MUI theme — elevation, states, colour system all defined |
+| **Radix UI Primitives** | Want unstyled, accessible primitives (dialogs, menus, popovers) you style yourself | `@radix-ui/react-*` — focus/disabled/aria handled correctly already |
+| **Park UI / Ark UI** | Multi-framework, headless + styled variants | Ark UI primitives + Park UI recipes |
+
+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)
+
+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.
+
+```css
+:root {
+  /* Colour — one accent + neutrals. No purple glow. */
+  --accent: #0066ff;          /* swap for the brand accent; ONE accent only */
+  --accent-hover: #0052cc;
+  --text: #111111;
+  --text-muted: #595959;
+  --bg: #ffffff;
+  --surface: #f7f7f8;
+  --border: #e4e4e7;
+  --danger: #c2261b;
+
+  /* Type — modular scale (ratio 1.25). No custom sizes. */
+  --text-sm: 0.8rem;
+  --text-base: 1rem;
+  --text-lg: 1.25rem;
+  --text-xl: 1.563rem;
+  --text-2xl: 1.953rem;
+
+  /* Spacing — 8px grid. No magic pixels. */
+  --space-1: 4px;   /* half-step for hairlines only */
+  --space-2: 8px;
+  --space-3: 16px;
+  --space-4: 24px;
+  --space-5: 32px;
+  --space-6: 48px;
+
+  /* Radius */
+  --radius-sm: 4px;
+  --radius-md: 8px;
+  --radius-lg: 12px;
+
+  /* Elevation — 4 named levels. Map EVERY shadow to one of these. */
+  --elev-sm: 0 1px 2px rgba(0,0,0,0.05);
+  --elev-md: 0 2px 8px rgba(0,0,0,0.08);
+  --elev-lg: 0 8px 24px rgba(0,0,0,0.12);
+  --elev-xl: 0 16px 48px rgba(0,0,0,0.16);
+}
+
+/* State contract — interactive elements MUST declare these. */
+:focus-visible { outline: 2px solid var(--accent); outline-offset: 2px; }
+:disabled { opacity: 0.5; cursor: not-allowed; }
+```
+
+## 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.
+
+## Audit-ready pairs for the minimal set
+
+```jsonc
+// Pass these to ux_audit.pairs to check the baseline itself.
+[
+  { "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 }
+]
+```
+
+## What this preset is NOT
+
+- 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.