@brunosps00/dev-workflow 1.0.5 → 1.1.0

package/scaffold/scripts/lib/resolve-browser.mjs

@@ -0,0 +1,405 @@
+#!/usr/bin/env node
+
+// Resolves which browser to drive for dev-workflow's browser-automation flows
+// (dw-qa, dw-functional-doc, dw-redesign-ui), with WSL resilience.
+//
+// Resolution order: env BROWSER_TEST -> .dw/config.json (browserTest) -> auto-detect.
+// On WSL with no explicit config, auto-detects a Windows browser (Edge first, then
+// Chrome) and launches it in remote-debugging mode so flows connect over CDP instead
+// of opening WSLg / losing layout fidelity in the bundled Linux Chromium.
+//
+// Returns one of:
+//   { mode: "cdp",    endpoint, source, cleanup }   // connect over CDP (browser ready)
+//   { mode: "launch", launchOptions, source }        // let Playwright launch the browser
+//
+// DEFAULT (no BROWSER_TEST): the full Playwright Chromium in headless via
+// channel:"chromium", which uses the new headless mode (desktop-faithful rendering,
+// not the lighter headless-shell) and never opens WSLg. This is the robust default on
+// WSL. Set BROWSER_TEST to opt into a Windows browser.
+//
+// NOTE on WSL networking: the Chromium debug port binds Windows loopback only. In mirrored
+// networking mode WSL shares that loopback, so 127.0.0.1 connects directly. In NAT mode the
+// helper starts the prebuilt cdp-relay.exe on Windows (0.0.0.0:<fixed port> -> 127.0.0.1:debug)
+// and connects via the Windows host gateway. That needs the one-time setup performed by
+// `npx @brunosps00/dev-workflow setup-wsl-browser` (builds the relay + adds the Hyper-V firewall
+// rule). Without it, the helper falls back to the local headless Chromium.
+
+import fs from "node:fs";
+import net from "node:net";
+import http from "node:http";
+import path from "node:path";
+import { spawn, spawnSync } from "node:child_process";
+
+// Full Chromium in new-headless mode: desktop-faithful rendering, no WSLg.
+const BUNDLED_LAUNCH = { channel: "chromium" };
+
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+const dedupe = (items) => [...new Set(items.filter(Boolean))];
+
+export function detectWsl() {
+  if (process.env.WSL_DISTRO_NAME) {
+    return true;
+  }
+  try {
+    return /microsoft/i.test(fs.readFileSync("/proc/version", "utf8"));
+  } catch {
+    return false;
+  }
+}
+
+// WSL2 mirrored networking creates a `loopback0` interface and shares Windows' loopback, so
+// 127.0.0.1 reaches a Windows browser's debug port directly. NAT mode has no loopback0 and
+// needs the Windows-side relay instead. Used to choose between the two connection strategies.
+export function isMirroredNetworking() {
+  return fs.existsSync("/sys/class/net/loopback0");
+}
+
+function readConfigValue(projectRoot) {
+  if (process.env.BROWSER_TEST && process.env.BROWSER_TEST.trim()) {
+    return { value: process.env.BROWSER_TEST.trim(), source: "env:BROWSER_TEST" };
+  }
+  if (projectRoot) {
+    try {
+      const cfg = JSON.parse(fs.readFileSync(path.join(projectRoot, ".dw", "config.json"), "utf8"));
+      if (cfg && typeof cfg.browserTest === "string" && cfg.browserTest.trim()) {
+        return { value: cfg.browserTest.trim(), source: ".dw/config.json" };
+      }
+    } catch {
+      // no config / unreadable -> fall through to auto-detect
+    }
+  }
+  return { value: undefined, source: null };
+}
+
+function classifyValue(value) {
+  if (/^(https?:\/\/|cdp:\/\/)/i.test(value)) {
+    return "cdp";
+  }
+  if (/\.exe$/i.test(value) || value.startsWith("/mnt/")) {
+    return "exe";
+  }
+  if (["chrome", "msedge", "chromium"].includes(value.toLowerCase())) {
+    return "channel";
+  }
+  return value.includes("/") ? "exe" : "channel";
+}
+
+function getFreePort() {
+  return new Promise((resolve, reject) => {
+    const server = net.createServer();
+    server.unref();
+    server.on("error", reject);
+    server.listen(0, "127.0.0.1", () => {
+      const { port } = server.address();
+      server.close(() => resolve(port));
+    });
+  });
+}
+
+function windowsHostIp() {
+  // In WSL2 NAT mode the Windows host is the default-route gateway (the vEthernet
+  // adapter), NOT the /etc/resolv.conf nameserver (which can be a DNS-tunneling proxy
+  // like 10.255.255.254 that does not forward arbitrary TCP ports). Prefer the gateway.
+  try {
+    const out = spawnSync("ip", ["route", "show", "default"], { encoding: "utf8" });
+    const match = out.stdout?.match(/default via ([0-9.]+)/);
+    if (match) {
+      return match[1];
+    }
+  } catch {
+    // ignore
+  }
+  try {
+    const match = fs.readFileSync("/etc/resolv.conf", "utf8").match(/nameserver\s+([0-9.]+)/);
+    if (match) {
+      return match[1];
+    }
+  } catch {
+    // ignore
+  }
+  return null;
+}
+
+function httpGetJson(url, timeoutMs = 1000) {
+  return new Promise((resolve) => {
+    const request = http.get(url, { timeout: timeoutMs }, (response) => {
+      let data = "";
+      response.on("data", (chunk) => (data += chunk));
+      response.on("end", () => {
+        try {
+          resolve(JSON.parse(data));
+        } catch {
+          resolve(null);
+        }
+      });
+    });
+    request.on("error", () => resolve(null));
+    request.on("timeout", () => {
+      request.destroy();
+      resolve(null);
+    });
+  });
+}
+
+async function findReachableCdp(port, extraHosts = []) {
+  const hosts = dedupe(["127.0.0.1", "localhost", ...extraHosts, windowsHostIp()]);
+  for (const host of hosts) {
+    const base = `http://${host}:${port}`;
+    const info = await httpGetJson(`${base}/json/version`);
+    if (info) {
+      return { base, host, info };
+    }
+  }
+  return null;
+}
+
+async function waitForCdp(hosts, port, { timeoutMs = 12000, intervalMs = 250 } = {}) {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    for (const host of dedupe(hosts)) {
+      const base = `http://${host}:${port}`;
+      const info = await httpGetJson(`${base}/json/version`);
+      if (info) {
+        return { base, host, info };
+      }
+    }
+    await sleep(intervalMs);
+  }
+  return null;
+}
+
+// A Windows path for the launched browser (it runs on Windows). Returns { winPath, wslPath }.
+function windowsTempDir() {
+  const rand = `dw-browser-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+  let winTemp = null;
+  try {
+    winTemp = spawnSync("cmd.exe", ["/c", "echo %TEMP%"], { encoding: "utf8" }).stdout?.split(/\r?\n/)[0]?.trim() || null;
+  } catch {
+    winTemp = null;
+  }
+  if (!winTemp || !/^[A-Za-z]:\\/.test(winTemp)) {
+    return null;
+  }
+  const winPath = `${winTemp}\\${rand}`;
+  let wslPath = null;
+  try {
+    wslPath = spawnSync("wslpath", ["-u", winPath], { encoding: "utf8" }).stdout?.trim() || null;
+  } catch {
+    wslPath = null;
+  }
+  return wslPath ? { winPath, wslPath } : null;
+}
+
+// Fixed port the Windows-side relay listens on, so a single Hyper-V firewall rule covers it.
+const DEFAULT_RELAY_PORT = 39222;
+
+function relayPort(projectRoot) {
+  const fromEnv = Number(process.env.DW_RELAY_PORT);
+  if (fromEnv) return fromEnv;
+  if (projectRoot) {
+    try {
+      const cfg = JSON.parse(fs.readFileSync(path.join(projectRoot, ".dw", "config.json"), "utf8"));
+      if (Number(cfg?.relayPort)) return Number(cfg.relayPort);
+    } catch {
+      // ignore
+    }
+  }
+  return DEFAULT_RELAY_PORT;
+}
+
+// The prebuilt Rust relay (cdp-relay.exe), built on Windows by `setup-wsl-browser`. Order:
+// .dw/config.json relayExe -> %LOCALAPPDATA%\dev-workflow\cdp-relay.exe. Returns { winPath, wslPath } or null.
+function findRelayExe(projectRoot) {
+  const candidates = [];
+  if (projectRoot) {
+    try {
+      const cfg = JSON.parse(fs.readFileSync(path.join(projectRoot, ".dw", "config.json"), "utf8"));
+      if (typeof cfg?.relayExe === "string" && cfg.relayExe.trim()) candidates.push(cfg.relayExe.trim());
+    } catch {
+      // ignore
+    }
+  }
+  try {
+    const lad = spawnSync("cmd.exe", ["/c", "echo %LOCALAPPDATA%"], { encoding: "utf8" }).stdout?.split(/\r?\n/)[0]?.trim();
+    if (lad && /^[A-Za-z]:\\/.test(lad)) candidates.push(`${lad}\\dev-workflow\\cdp-relay.exe`);
+  } catch {
+    // ignore
+  }
+  for (const winPath of candidates) {
+    let wslPath = null;
+    try {
+      wslPath = spawnSync("wslpath", ["-u", winPath], { encoding: "utf8" }).stdout?.trim() || null;
+    } catch {
+      // ignore
+    }
+    if (wslPath && fs.existsSync(wslPath)) return { winPath, wslPath };
+  }
+  return null;
+}
+
+// Launches the Windows browser in remote-debugging mode and returns a CDP descriptor.
+// - mirrored networking: WSL shares the Windows loopback (Hyper-V LoopbackEnabled), connect 127.0.0.1.
+// - NAT networking: the prebuilt cdp-relay.exe bridges 0.0.0.0:<relayPort> -> 127.0.0.1:<debug> on the
+//   Windows side, and WSL connects via the Windows host gateway. This needs a one-time Hyper-V firewall
+//   inbound rule for <relayPort> (added by `setup-wsl-browser`), because WSL's Hyper-V firewall defaults
+//   inbound to Block. The browser echoes the request Host into webSocketDebuggerUrl, so the ws stays
+//   reachable through the relay.
+// --remote-allow-origins=* is required or Chromium drops the DevTools ws (anti-DNS-rebinding).
+async function launchWindowsBrowser(exePath, { headless, projectRoot }) {
+  const mirrored = isMirroredNetworking();
+  const tmp = windowsTempDir();
+  if (tmp) {
+    try {
+      fs.mkdirSync(tmp.wslPath, { recursive: true });
+    } catch {
+      // best effort
+    }
+  }
+
+  const debugPort = await getFreePort();
+  const args = [
+    `--remote-debugging-port=${debugPort}`,
+    "--remote-allow-origins=*",
+    "--no-first-run",
+    "--no-default-browser-check",
+  ];
+  if (tmp) args.push(`--user-data-dir=${tmp.winPath}\\profile`);
+  if (headless) args.push("--headless=new");
+  args.push("about:blank");
+
+  const browserChild = spawn(exePath, args, { detached: true, stdio: "ignore" });
+  browserChild.unref();
+
+  const cleanups = [() => browserChild.kill()];
+  if (tmp) cleanups.push(() => fs.rmSync(tmp.wslPath, { recursive: true, force: true }));
+  const cleanup = async () => {
+    for (const fn of cleanups) {
+      try {
+        await fn();
+      } catch {
+        // ignore
+      }
+    }
+  };
+
+  let hosts;
+  let port;
+  if (mirrored) {
+    hosts = ["127.0.0.1", "localhost"];
+    port = debugPort;
+  } else {
+    const relay = findRelayExe(projectRoot);
+    if (!relay) {
+      await cleanup();
+      throw new Error(
+        "WSL is in NAT mode; reaching the Windows browser needs cdp-relay.exe. Run " +
+          "`npx @brunosps00/dev-workflow setup-wsl-browser` (builds the relay on Windows and adds the " +
+          "Hyper-V firewall rule). Alternatively enable mirrored networking or set BROWSER_TEST to a CDP URL.",
+      );
+    }
+    const rport = relayPort(projectRoot);
+    const relayChild = spawn(relay.wslPath, [String(rport), String(debugPort)], { detached: true, stdio: "ignore" });
+    relayChild.unref();
+    cleanups.unshift(() => relayChild.kill());
+    hosts = [windowsHostIp(), "127.0.0.1"].filter(Boolean);
+    port = rport;
+  }
+
+  const found = await waitForCdp(hosts, port);
+  if (!found) {
+    await cleanup();
+    throw new Error(
+      `Launched ${path.basename(exePath)} but its CDP endpoint was not reachable (${hosts.join("/")}:${port}). ` +
+        "The Hyper-V firewall rule may be missing — run `npx @brunosps00/dev-workflow setup-wsl-browser`.",
+    );
+  }
+
+  return { mode: "cdp", endpoint: found.base, source: `launched:${path.basename(exePath)}${mirrored ? "" : "+relay"}`, cleanup };
+}
+
+const noopCleanup = async () => {};
+
+function bundledDescriptor(headless, source = "bundled") {
+  return { mode: "launch", launchOptions: { ...BUNDLED_LAUNCH, headless }, source };
+}
+
+// When an explicit BROWSER_TEST cannot be honored, degrade to the headless default
+// (resilient) unless allowFallback is false (then throw, e.g. for diagnostics).
+function degradeOrThrow(message, { headless, allowFallback }) {
+  if (allowFallback) {
+    process.stderr.write(`resolve-browser: ${message} Falling back to headless Chromium.\n`);
+    return bundledDescriptor(headless, "fallback");
+  }
+  throw new Error(message);
+}
+
+export async function resolveBrowser({ projectRoot, headless = true, allowFallback = true } = {}) {
+  const { value, source } = readConfigValue(projectRoot);
+
+  if (!value) {
+    return bundledDescriptor(headless);
+  }
+
+  const kind = classifyValue(value);
+
+  if (kind === "cdp") {
+    const url = new URL(value.replace(/^cdp:\/\//i, "http://"));
+    const port = Number(url.port) || 9222;
+    const found = await findReachableCdp(port, [url.hostname]);
+    if (!found) {
+      return degradeOrThrow(
+        `BROWSER_TEST endpoint '${value}' is not reachable (start the browser with --remote-debugging-port=${port}).`,
+        { headless, allowFallback },
+      );
+    }
+    return { mode: "cdp", endpoint: found.base, source, cleanup: noopCleanup };
+  }
+
+  if (kind === "exe") {
+    if (!fs.existsSync(value)) {
+      return degradeOrThrow(`BROWSER_TEST points to '${value}', but that file does not exist.`, {
+        headless,
+        allowFallback,
+      });
+    }
+    try {
+      return await launchWindowsBrowser(value, { headless, projectRoot });
+    } catch (error) {
+      return degradeOrThrow(error.message, { headless, allowFallback });
+    }
+  }
+
+  // channel: chrome | msedge | chromium
+  const channel = value.toLowerCase();
+  return { mode: "launch", launchOptions: { channel, headless }, source };
+}
+
+// CLI probe: `node resolve-browser.mjs [--project-root <dir>] [--headed] [--keep-open]`
+// Prints the resolved descriptor as JSON (cleans up any launched browser unless --keep-open).
+function parseProbeArgs(argv) {
+  const out = {};
+  for (let i = 0; i < argv.length; i += 1) {
+    const token = argv[i];
+    if (token === "--headed") out.headed = true;
+    else if (token === "--keep-open") out.keepOpen = true;
+    else if (token === "--project-root") out.projectRoot = argv[(i += 1)];
+  }
+  return out;
+}
+
+const invokedDirectly = process.argv[1] && path.resolve(process.argv[1]).endsWith("resolve-browser.mjs");
+if (invokedDirectly) {
+  const args = parseProbeArgs(process.argv.slice(2));
+  resolveBrowser({ projectRoot: args.projectRoot ?? process.cwd(), headless: !args.headed })
+    .then(async (descriptor) => {
+      const { cleanup, ...printable } = descriptor;
+      process.stdout.write(`${JSON.stringify(printable, null, 2)}\n`);
+      if (typeof cleanup === "function" && !args.keepOpen) {
+        await cleanup();
+      }
+    })
+    .catch((error) => {
+      process.stderr.write(`resolve-browser: ${error.message}\n`);
+      process.exitCode = 1;
+    });
+}

package/scaffold/scripts/lib/ui-slop-detect.mjs

@@ -0,0 +1,102 @@
+#!/usr/bin/env node
+
+// Thin wrapper around `impeccable detect` — the deterministic UI design-slop detector by
+// Paul Bakaus (https://github.com/pbakaus/impeccable, Apache-2.0, derived from Anthropic's
+// frontend-design skill). dev-workflow does NOT vendor it; npx fetches it on demand, so
+// there is no extra dependency to install.
+//
+// Purpose: turn "the LLM might notice slop" into a deterministic gate. /dw-review (UI diffs)
+// and /dw-verify run this and block on findings at or above --fail-on severity.
+//
+// Usage:
+//   node .dw/scripts/lib/ui-slop-detect.mjs [paths...] [--fail-on error] [--fast]
+//   (defaults: paths=".", --fail-on=error)
+//
+// Output: normalized JSON { failOn, summary: { bySeverity }, blocking, findings }.
+// Exit: 1 if any finding >= failOn; 0 otherwise (including when impeccable cannot run — a
+// missing detector should not hard-fail a review, only warn).
+
+import { spawnSync } from "node:child_process";
+
+const SEVERITY_RANK = { info: 0, warning: 1, error: 2, critical: 3 };
+
+function parseArgs(argv) {
+  const paths = [];
+  const flags = { failOn: "error", fast: false };
+  for (let index = 0; index < argv.length; index += 1) {
+    const token = argv[index];
+    if (token === "--fast") {
+      flags.fast = true;
+    } else if (token === "--fail-on") {
+      flags.failOn = String(argv[(index += 1)] ?? "error").toLowerCase();
+    } else if (token.startsWith("--fail-on=")) {
+      flags.failOn = token.slice("--fail-on=".length).toLowerCase();
+    } else if (!token.startsWith("--")) {
+      paths.push(token);
+    }
+  }
+  if (paths.length === 0) {
+    paths.push(".");
+  }
+  return { paths, flags };
+}
+
+function rank(severity) {
+  return SEVERITY_RANK[String(severity).toLowerCase()] ?? 1;
+}
+
+function main() {
+  const { paths, flags } = parseArgs(process.argv.slice(2));
+  const detectArgs = ["-y", "impeccable@latest", "detect", "--json"];
+  if (flags.fast) {
+    detectArgs.push("--fast");
+  }
+  detectArgs.push(...paths);
+
+  const result = spawnSync("npx", detectArgs, { encoding: "utf8", timeout: 180000 });
+  if (result.error || typeof result.stdout !== "string") {
+    process.stderr.write(
+      `ui-slop-detect: could not run impeccable (${result.error?.message ?? "no output"}). ` +
+        "Skipping the deterministic UI gate — install Node/npx or run `npx impeccable detect` manually.\n",
+    );
+    process.exit(0);
+  }
+
+  let findings;
+  try {
+    findings = JSON.parse(result.stdout);
+    if (!Array.isArray(findings)) {
+      throw new Error("unexpected output shape");
+    }
+  } catch (error) {
+    process.stderr.write(`ui-slop-detect: could not parse impeccable output (${error.message}).\n`);
+    process.stdout.write(result.stdout);
+    process.exit(0);
+  }
+
+  const bySeverity = {};
+  for (const finding of findings) {
+    const severity = String(finding.severity ?? "warning").toLowerCase();
+    bySeverity[severity] = (bySeverity[severity] ?? 0) + 1;
+  }
+
+  const threshold = rank(flags.failOn);
+  const blocking = findings.filter((finding) => rank(finding.severity) >= threshold);
+
+  process.stdout.write(
+    `${JSON.stringify(
+      {
+        failOn: flags.failOn,
+        summary: { total: findings.length, bySeverity },
+        blocking: blocking.length,
+        findings,
+      },
+      null,
+      2,
+    )}\n`,
+  );
+
+  process.exit(blocking.length > 0 ? 1 : 0);
+}
+
+main();

package/scaffold/skills/dw-testing-discipline/references/playwright-recipes.md

@@ -272,6 +272,56 @@ Tests now start authenticated. No login loop in every test.
 - Some authentication flows (Google Sign-In, MFA hardware keys) cannot be automated; use test-mode bypasses with a dedicated test account.
 - Visual regression tests are sensitive to font rendering across OSes; pin to a CI runner OS.
 
+## Browser on WSL (resilient resolution)
+
+WSL makes browser automation fragile: the Playwright MCP may be blocked, headed runs open
+WSLg, and the bundled headless can lose fidelity. dev-workflow ships `.dw/scripts/lib/resolve-browser.mjs`
+to pick a browser deterministically. Both `.dw/scripts/functional-doc/run-playwright-flow.mjs`
+(video, via `page.screencast`) and `.dw/scripts/lib/capture-screenshots.mjs` (responsive shots)
+use it, so the same rules apply everywhere.
+
+Resolution order: `BROWSER_TEST` env → `.dw/config.json` (`browserTest`) → default.
+
+- **Default (no config):** full Chromium in new-headless mode (`channel: "chromium"`) — desktop-faithful
+  rendering, never opens WSLg. This is the recommended default on WSL.
+- **`BROWSER_TEST` = CDP URL** (e.g. `http://localhost:9222`): connects with `chromium.connectOverCDP`.
+  Tries `127.0.0.1` first, then the Windows host (default-route gateway) for NAT.
+- **`BROWSER_TEST` = Windows exe** (e.g. `/mnt/c/.../msedge.exe`): launches it with a temp profile in
+  remote-debugging mode (`--remote-allow-origins=*`) and connects over CDP. **Works in both WSL2 modes:**
+  in mirrored networking it connects to `127.0.0.1` directly; in NAT mode it starts the prebuilt
+  **`cdp-relay.exe`** (a tiny Rust binary, no runtime) on Windows — `0.0.0.0:39222` → `127.0.0.1:<debug>` —
+  and connects via the Windows host gateway. Falls back to headless Chromium if the relay/rule is absent.
+- **`BROWSER_TEST` = channel** (`chrome` | `msedge` | `chromium`): launches that channel locally.
+
+NAT mode needs a one-time setup (the WSL **Hyper-V firewall** defaults inbound to Block, and Chromium
+binds its debug port to loopback only):
+
+```bash
+npx @brunosps00/dev-workflow setup-wsl-browser
+```
+
+This builds `cdp-relay.exe` with the Windows Rust toolchain (`rustup` on Windows) and adds a Hyper-V
+firewall inbound allow rule for TCP 39222 (one UAC prompt). After that, the *real* Windows browser is
+driven from WSL — including `page.screencast` video — under NAT. The launched browser and relay use a
+throwaway profile and are killed on exit.
+
+Two env vars, two jobs — keep them distinct:
+- `BROWSER` — opens URLs for a human (used by `/dw-generate-pr`).
+- `BROWSER_TEST` — the automation target for QA / functional-doc / redesign capture.
+
+To drive the real Windows browser, set `BROWSER_TEST` to its exe path (NAT works as long as `node` is on
+the Windows PATH; mirrored works too). To force the faithful local-headless path instead, leave
+`BROWSER_TEST` unset or set it to `chromium`.
+
+```bash
+# Probe what would be used (cleans up any launched browser):
+node .dw/scripts/lib/resolve-browser.mjs --project-root .
+
+# Responsive screenshots fallback when the Playwright MCP is unavailable:
+node .dw/scripts/lib/capture-screenshots.mjs --url http://localhost:3000/path \
+  --out QA/evidence/ui --widths 375,1440 --slug home
+```
+
 ## Cross-skill integration
 
 When running these recipes, the doctrine in this skill applies:

package/scaffold/skills/dw-ui-discipline/SKILL.md

@@ -92,6 +92,11 @@ Without this sentence, defaults take over: light mode, default contrasts, animat
 | Designing state coverage | `references/state-matrix.md` |
 | Interactive widget (button, form, modal, anything clickable) | `references/accessibility-floor.md` |
 | No design authority exists in the project | `references/curated-defaults.md` (palettes / fonts / scales) |
+| Choosing or reviewing a palette / dark mode | `references/color-oklch.md` (OKLCH, tinted neutrals, contrast) |
+| Fonts, sizing, hierarchy, line length | `references/type-scale.md` (modular scale, pairing, measure) |
+| Adding animation or transitions | `references/motion.md` (easing, duration, reduced-motion) |
+| Cross-device / breakpoints / touch | `references/responsive.md` (mobile-first, container queries) |
+| Any user-facing copy (labels, errors, empty states) | `references/ux-writing.md` |
 
 ## The 14 visual-slop patterns (full catalog in `references/visual-slop.md`)
 

package/scaffold/skills/dw-ui-discipline/references/color-oklch.md

@@ -0,0 +1,60 @@
+# Color & contrast — OKLCH, tinted neutrals, dark mode
+
+> Patterns adapted from [impeccable](https://github.com/pbakaus/impeccable) (Apache-2.0, derived from
+> Anthropic's frontend-design skill). Read when building or reviewing a palette.
+
+## Work in OKLCH, not hex/HSL
+
+OKLCH (`oklch(L C H)`) is perceptually uniform: equal lightness steps *look* equally spaced, and changing
+hue does not shift perceived brightness (HSL's big flaw — HSL yellow at 50% L looks far lighter than HSL
+blue at 50% L). Modern browsers support `oklch()` natively.
+
+- **L** (lightness) 0–100% — drive your scale off this.
+- **C** (chroma) 0–~0.37 — saturation. Keep neutrals low (0.005–0.03), accents moderate (0.1–0.2).
+- **H** (hue) 0–360.
+
+## Tinted neutrals (the single highest-leverage move)
+
+Pure grays (`#777`, `oklch(50% 0 0)`) look dead. Tint every neutral slightly toward one hue — usually the
+brand hue or its complement — so the UI feels intentional.
+
+```css
+/* Cool, slightly blue-tinted neutral scale */
+--n-50:  oklch(98% 0.005 250);
+--n-100: oklch(96% 0.006 250);
+--n-300: oklch(87% 0.010 250);
+--n-500: oklch(62% 0.014 250);
+--n-700: oklch(42% 0.014 250);
+--n-900: oklch(22% 0.012 250);
+--n-950: oklch(14% 0.010 250);
+```
+
+Pure `#000` / `#fff` are anti-patterns (the detector flags `pure-black-white`). Use `oklch(14% 0.01 H)`
+for "black" surfaces and `oklch(98% 0.005 H)` for "white".
+
+## Building a scale
+
+Pick the hue + chroma, then step lightness on a roughly even curve (98 / 96 / 92 / 87 / 78 / 68 / 62 / 52 /
+42 / 32 / 22 / 14). Keep chroma roughly constant for neutrals; for an accent, let chroma peak in the mid
+lightness range (most vivid at 55–65% L) and fall off at the extremes.
+
+## Accent & semantic colors
+
+- One primary accent carries the brand. Avoid the training-data default blue `#3B82F6` — shift the hue or
+  darken it (`oklch(55% 0.18 255)` reads more deliberate).
+- Semantic set: success (green ~145H), warning (amber ~75H), danger (red ~25H), info (blue ~250H). Keep
+  their lightness consistent with each other so badges feel like a family.
+
+## Contrast (non-negotiable, see accessibility-floor.md)
+
+- Body text ≥ 4.5:1; large text (≥24px or ≥18.7px bold) and UI component boundaries ≥ 3:1.
+- Don't rely on hue alone to convey state — pair color with icon/text (color-blind users).
+- Test the *actual* foreground/background pair, not the token names.
+
+## Dark mode
+
+Dark mode is not "invert lightness". Re-tune:
+- Raise surface lightness in steps as elements come forward (`oklch(16%)` page → `18%` card → `22%`
+  popover) instead of borders everywhere.
+- Reduce accent chroma slightly in dark mode — vivid colors vibrate on dark backgrounds.
+- Keep body text around `oklch(90% 0.01 H)`, not pure white, to cut glare.

package/scaffold/skills/dw-ui-discipline/references/motion.md

@@ -0,0 +1,52 @@
+# Motion — easing, duration, stagger, reduced motion
+
+> Patterns adapted from [impeccable](https://github.com/pbakaus/impeccable) (Apache-2.0, derived from
+> Anthropic's frontend-design skill). Read when adding animation or transitions.
+
+## Motion conveys state, not decoration
+
+Animate to explain a change: where did this come from, what just happened, where did it go. If a motion
+doesn't answer one of those, cut it. Decorative motion is a visual-slop pattern.
+
+## Easing — avoid bounce/elastic
+
+Real objects decelerate smoothly. Bounce and elastic easing feel dated and tacky (the detector flags
+`bounce-easing` / spring overshoot like `cubic-bezier(0.68,-0.55,0.27,1.55)`).
+
+- **Enter** (element appears): ease-out — fast start, soft landing. `cubic-bezier(0.16, 1, 0.3, 1)`
+  (ease-out-expo) or `ease-out`.
+- **Exit** (element leaves): ease-in — accelerate away. `cubic-bezier(0.4, 0, 1, 1)`.
+- **Move/resize on screen:** ease-in-out (standard) `cubic-bezier(0.4, 0, 0.2, 1)`.
+- Never linear for UI (only for continuous things like spinners/marquees).
+
+## Duration
+
+- Micro (hover, small fades): 100–150ms.
+- Standard (dropdowns, toggles, cards): 200–300ms.
+- Large (page/route, full-screen sheets): 300–500ms.
+- Over ~500ms feels sluggish; under ~80ms is imperceptible (just snap with no transition).
+
+## Stagger
+
+When several items enter together, stagger them 20–50ms apart so the eye follows the sequence — but cap
+total stagger (don't make the 12th list item wait 600ms). Stagger entrances, not exits.
+
+## What to animate (performance)
+
+Animate only `transform` and `opacity` — they run on the compositor and don't trigger layout/paint.
+Animating `width`, `height`, `top`, `left`, `margin` janks. Use `transform: translate/scale` instead.
+
+## `prefers-reduced-motion` (required)
+
+Honor it. Replace movement with an instant or opacity-only change.
+
+```css
+@media (prefers-reduced-motion: reduce) {
+  *, *::before, *::after {
+    animation-duration: 0.01ms !important;
+    transition-duration: 0.01ms !important;
+  }
+}
+```
+
+Don't remove *feedback* entirely — a state change still needs to be visible, just not kinetic.