@ryuxdsgn/design-intelligence 2.15.0 → 2.19.0

package/dist/cli/hook.js

@@ -0,0 +1,55 @@
+// The opt-in Claude Code hook that runs `ryux scan --hook` after each Edit or Write. It lives in
+// .claude/settings.json next to the user's own settings; only the RYUX entry is added, updated, or removed.
+import { join } from "node:path";
+import { CLI_CMD, VERSION } from "../product.js";
+import { readIfExists, writeFileEnsured } from "./fsutil.js";
+const SETTINGS = ".claude/settings.json";
+const MATCHER = "Edit|MultiEdit|Write";
+// Pinned to this version so every edit runs the same detectors; `update` moves the pin.
+const command = () => `${CLI_CMD.replace("npx ", "npx -y ")}@${VERSION} scan --hook`;
+const isOurs = (c) => typeof c === "string" && c.includes("@ryuxdsgn/design-intelligence") && c.includes("scan --hook");
+async function read(root) {
+    const raw = await readIfExists(join(root, SETTINGS));
+    if (raw === null)
+        return {};
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+const ours = (s) => (s.hooks?.PostToolUse ?? []).filter((e) => e.hooks?.some((h) => isOurs(h.command)));
+export async function hasHook(root) {
+    const s = await read(root);
+    return Boolean(s && ours(s).length);
+}
+/** Add the hook, or move an existing one to this version. Throws when settings.json is not valid JSON,
+ *  so a file we cannot read is never overwritten. */
+export async function installHook(root) {
+    const s = await read(root);
+    if (!s)
+        throw new Error(`${SETTINGS} is not valid JSON; fix it, then run this again`);
+    const existing = ours(s);
+    if (existing.some((e) => e.hooks.some((h) => h.command === command())))
+        return `${SETTINGS} (scan hook already present)`;
+    const post = (s.hooks?.PostToolUse ?? []).filter((e) => !existing.includes(e));
+    s.hooks = { ...s.hooks, PostToolUse: [...post, { matcher: MATCHER, hooks: [{ type: "command", command: command() }] }] };
+    await writeFileEnsured(join(root, SETTINGS), `${JSON.stringify(s, null, 2)}\n`);
+    return `${SETTINGS} (scan hook ${existing.length ? "updated" : "added"})`;
+}
+/** Remove the RYUX entry and any hook lists it leaves empty. True when something was removed. */
+export async function removeHook(root) {
+    const s = await read(root);
+    if (!s || !ours(s).length)
+        return false;
+    const post = s.hooks.PostToolUse.filter((e) => !ours(s).includes(e));
+    if (post.length)
+        s.hooks.PostToolUse = post;
+    else
+        delete s.hooks.PostToolUse;
+    if (!Object.keys(s.hooks).length)
+        delete s.hooks;
+    await writeFileEnsured(join(root, SETTINGS), `${JSON.stringify(s, null, 2)}\n`);
+    return true;
+}

package/dist/cli/index.js

@@ -10,6 +10,8 @@ import { CLI_CMD, CONTEXT_END, CONTEXT_FILE, CONTEXT_START, MARK_START, MCP_STAT
 import { validateBundle } from "../validate.js";
 import { renderAgentsBlock, renderBundle, renderPointerBlock, SKILL_NAME } from "../render.js";
 import { hasBlock, readIfExists, rel, removeBlock, removePath, upsertBlock, writeFileEnsured } from "./fsutil.js";
+import { hasHook, installHook, removeHook } from "./hook.js";
+import { runScan } from "./scan.js";
 import { readFile, readdir } from "node:fs/promises";
 const AGENT_IDS = [...AGENT_TARGETS.map((a) => a.id), AGENTS_MD_INLINE.id];
 const targetDir = (a, scope) => join(scope.root, scope.global ? a.globalDir : a.dir);
@@ -174,12 +176,27 @@ async function runInstall(flags) {
         console.log(pc.yellow("agents-md is project-only; skipped for --global."));
         agents = agents.filter((x) => x !== AGENTS_MD_INLINE.id);
     }
+    let hook = Boolean(flags.hook);
+    if (!nonInteractive && agents.includes("claude")) {
+        const h = await p.confirm({ message: "Run ryux scan on each file Claude Code edits? (adds a hook to .claude/settings.json)", initialValue: false });
+        if (p.isCancel(h))
+            return cancel();
+        hook = h;
+    }
+    if (hook && !agents.includes("claude")) {
+        console.log(pc.yellow("--hook works with Claude Code only for now; skipped."));
+        hook = false;
+    }
     if (flags["dry-run"]) {
         const plan = await planInstall(agents, scope);
+        if (hook)
+            plan.push(`${(await hasHook(scope.root)) ? "update" : "add"} the scan hook in .claude/settings.json (runs ryux scan after each edit)`);
         console.log(`Dry run: nothing was written. ${CLI_CMD} ${flags.init ? "init" : "install"} would:\n${plan.map((l) => `  ${l}`).join("\n")}`);
         return;
     }
     const written = await install(agents, scope);
+    if (hook)
+        written.push(await installHook(scope.root));
     const summary = written.map((w) => pc.green("✓ ") + w).join("\n");
     if (nonInteractive)
         console.log(summary);
@@ -222,6 +239,8 @@ async function runUpdate(flags) {
     const done = [];
     for (const dir of dirs)
         done.push(...(await writeSkills(dir, scope.root)));
+    if (await hasHook(scope.root))
+        done.push(await installHook(scope.root));
     if (!scope.global) {
         for (const file of ["CLAUDE.md", "GEMINI.md", "AGENTS.md"]) {
             const path = join(scope.root, file);
@@ -241,7 +260,7 @@ async function runRemove(flags) {
     const pointerFiles = scope.global ? [] : ["CLAUDE.md", "GEMINI.md", "AGENTS.md"];
     const hasBlocks = (await Promise.all(pointerFiles.map(async (f) => (await readIfExists(join(scope.root, f)))?.includes(MARK_START)))).some(Boolean);
     const hasLegacyCursor = existsSync(join(scope.root, LEGACY_CURSOR_RULES_DIR));
-    if (!hasSkills && !hasBlocks && !hasLegacyCursor) {
+    if (!hasSkills && !hasBlocks && !hasLegacyCursor && !(await hasHook(scope.root))) {
         console.log("No RYUX install found.");
         return;
     }
@@ -264,6 +283,8 @@ async function runRemove(flags) {
     for (const f of pointerFiles)
         if (await removeBlock(join(scope.root, f)))
             removed.push(`${f} (block)`);
+    if (await removeHook(scope.root))
+        removed.push(".claude/settings.json (scan hook)");
     console.log(removed.length ? removed.map((r) => pc.red("− ") + r).join("\n") : "No files removed.");
 }
 /** Read every file of an installed skill folder, keyed by its path inside the folder. */
@@ -323,6 +344,8 @@ async function runCheck(flags) {
         else
             add("warn", CONTEXT_FILE, "no RYUX project context", "setup");
     }
+    if (await hasHook(scope.root))
+        add("ok", ".claude/settings.json", "scan hook present");
     const ok = !findings.some((f) => f.level === "fail");
     if (!ok)
         process.exitCode = 1;
@@ -440,6 +463,21 @@ const CONTEXT_FIELDS = [
                 { value: "Premium", label: "Premium" },
             ] },
     },
+    {
+        label: "Voice and tone", hint: "(voice words, how it addresses people, what it must never sound like; tone shifts by moment)",
+        ask: { flag: "voice", group: "Design", question: "How should it talk?", example: 'Hangat, lugas, pakai "kamu"', options: [
+                { value: "Warm and casual", label: "Warm and casual" },
+                { value: "Calm and professional", label: "Calm and professional" },
+                { value: "Direct and brief", label: "Direct and brief" },
+                { value: "Playful", label: "Playful", hint: "only where it costs no clarity" },
+                { value: "Reassuring", label: "Reassuring", hint: "for money, health, or waiting" },
+            ], then: { question: "What must it never sound like? Pick any.", example: "not preachy", multi: true, options: [
+                    { value: "not stiff or overly formal", label: "Stiff or overly formal" },
+                    { value: "not salesy or hyped", label: "Salesy or hyped" },
+                    { value: "not too familiar", label: "Too familiar" },
+                    { value: "no jokes when things go wrong", label: "Jokey when things go wrong" },
+                ] } },
+    },
     {
         label: "Motion direction", hint: "(feel, what motion communicates, what to avoid)",
         ask: { flag: "motion", group: "Design", question: "How much motion?", example: "Only to confirm a payment went through", options: [
@@ -723,6 +761,9 @@ Commands:
   setup       Teach RYUX about this project: a few skippable questions, saved to DESIGN.md.
   init        Install RYUX and add the DESIGN.md project context block.
   check       Check the install: files, version, references, pointers, project context.
+  scan        Check source files for rules a machine can see (Rupiah format, alt text, zoom, focus, ...).
+              No LLM, no network. Default path: this folder. Give a URL to measure the rendered page
+              (sideways scroll, contrast, target size, colliding text); that needs Playwright.
   update      Update an install to this version (also migrates RYUX 1.x folders).
   remove      Remove RYUX and the marked blocks.
   help        Show this help.
@@ -737,8 +778,12 @@ Options:
   --mcp                print the ryux MCP connect command
   --yes                skip the confirmation (remove)
   --dry-run            list what install or init would create or update, and write nothing
-  --json               print check's findings as JSON (for agents and CI)
-  --product, --work, --audience, --market, --constraints, --intent, --ux, --ui, --motion <text>
+  --json               print check's or scan's findings as JSON (for agents and CI)
+  --hook               install: run ryux scan after each Claude Code edit (opt-in)
+  --list-rules         scan: list what each check looks for
+  --ignore <ids>       scan: skip rules, e.g. RX-DS-03 (or a ryux-ignore RX-.. comment in the file)
+  --widths <list>      scan <url>: viewport widths in CSS px (default 320,390,1280)
+  --product, --work, --audience, --market, --constraints, --intent, --ux, --ui, --voice, --motion <text>
                        set project context fields without questions (setup)
 
 Examples:
@@ -754,8 +799,12 @@ Examples:
   ${CLI_CMD} remove --yes
   ${CLI_CMD} init --agent claude --dry-run
   ${CLI_CMD} check --json
+  ${CLI_CMD} scan src
+  ${CLI_CMD} scan http://localhost:3000/checkout
+  ${CLI_CMD} scan --list-rules
+  ${CLI_CMD} install --agent claude --hook
 
-Exit codes: 0 done or healthy, 1 a problem was found or the command failed, 2 the command was used wrongly.`);
+Exit codes: 0 done or healthy, 1 a problem was found (for scan: a fail) or the command failed, 2 the command was used wrongly.`);
 }
 async function main() {
     const argv = process.argv.slice(2);
@@ -774,6 +823,8 @@ async function main() {
         case "check":
         case "doctor":
             return runCheck(flags);
+        case "scan":
+            return runScan(argv.slice(1));
         case "init":
             return runInit(flags);
         case "setup":

package/dist/cli/page-probe.js

@@ -0,0 +1,228 @@
+// @ts-nocheck: this function runs inside the page (Playwright serializes it), where the DOM exists;
+// the package compiles for Node without DOM types.
+// Measures a rendered page at the current viewport: horizontal scroll, text contrast, text size,
+// target size, and text that collides. Returns plain findings; the caller adds the width and URL.
+export function probe() {
+    const out = [];
+    const vw = document.documentElement.clientWidth;
+    const selector = (el) => {
+        const parts = [];
+        for (let e = el; e && e !== document.body && parts.length < 3; e = e.parentElement) {
+            let s = e.tagName.toLowerCase();
+            if (e.id) {
+                parts.unshift(`${s}#${e.id}`);
+                break;
+            }
+            const cls = typeof e.className === "string" ? e.className.trim().split(/\s+/)[0] : "";
+            if (cls)
+                s += `.${cls}`;
+            parts.unshift(s);
+        }
+        return parts.join(" > ");
+    };
+    const style = (el) => getComputedStyle(el);
+    const shown = (el) => {
+        for (let e = el; e; e = e.parentElement) {
+            const cs = style(e);
+            if (cs.display === "none" || cs.visibility === "hidden" || cs.opacity === "0")
+                return false;
+            // Visually hidden (the sr-only pattern): clipped, or inside a box of 1px or less that hides overflow.
+            if ((cs.clip && cs.clip !== "auto") || /inset\(50%\)/.test(cs.clipPath))
+                return false;
+            const box = e.getBoundingClientRect();
+            if (cs.overflow !== "visible" && (box.width <= 1 || box.height <= 1))
+                return false;
+        }
+        const r = el.getBoundingClientRect();
+        return r.width > 1 && r.height > 1;
+    };
+    const disabled = (el) => Boolean(el.closest("[disabled],[aria-disabled='true'],[inert]"));
+    const quote = (s) => (s.length > 40 ? `"${s.slice(0, 37)}..."` : `"${s}"`);
+    // Horizontal scroll (RX-RD-01): name the outermost elements that reach past the viewport.
+    if (document.documentElement.scrollWidth > vw + 1) {
+        const culprits = [...document.body.querySelectorAll("*")].filter((el) => {
+            const r = el.getBoundingClientRect();
+            const p = el.parentElement?.getBoundingClientRect();
+            return r.right > vw + 1 && r.width > 0 && (!p || p.right <= vw + 1) && shown(el);
+        });
+        const names = culprits.slice(0, 3).map((el) => `${selector(el)} (to ${Math.round(el.getBoundingClientRect().right)}px)`);
+        out.push({
+            rule: "RX-RD-01",
+            level: "fail",
+            selector: culprits[0] ? selector(culprits[0]) : "html",
+            message: `the page scrolls sideways: ${document.documentElement.scrollWidth}px of content in ${vw}px${names.length ? `; widest: ${names.join(", ")}` : ""}`,
+        });
+    }
+    // Text: every visible element with its own text.
+    const texts = [];
+    for (const el of document.body.querySelectorAll("*")) {
+        if (/^(SCRIPT|STYLE|NOSCRIPT|TEMPLATE|OPTION)$/.test(el.tagName) || el.closest("svg"))
+            continue;
+        const nodes = [...el.childNodes].filter((n) => n.nodeType === 3 && n.textContent.trim());
+        if (!nodes.length || !shown(el))
+            continue;
+        texts.push({ el, nodes, text: nodes.map((n) => n.textContent).join(" ").replace(/\s+/g, " ").trim() });
+    }
+    const rgba = (c) => {
+        const m = c.match(/rgba?\(([^)]+)\)/);
+        if (!m)
+            return null;
+        const [r, g, b, a = 1] = m[1].split(/[\s,/]+/).filter(Boolean).map(Number);
+        return [r, g, b, a];
+    };
+    const over = (top, bottom) => {
+        const a = top[3];
+        return [0, 1, 2].map((i) => top[i] * a + bottom[i] * (1 - a)).concat(1);
+    };
+    // The solid color behind an element, or null when an image, gradient, or blend makes it unknown.
+    const background = (el) => {
+        const layers = [];
+        for (let e = el; e; e = e.parentElement) {
+            const cs = style(e);
+            if (cs.backgroundImage !== "none" || cs.mixBlendMode !== "normal" || (cs.filter && cs.filter !== "none"))
+                return null;
+            const c = rgba(cs.backgroundColor);
+            if (c && c[3] > 0) {
+                layers.push(c);
+                if (c[3] >= 1)
+                    break;
+            }
+        }
+        let color = [255, 255, 255, 1];
+        for (const layer of layers.reverse())
+            color = over(layer, color);
+        return color;
+    };
+    const luminance = ([r, g, b]) => [r, g, b]
+        .map((v) => v / 255)
+        .map((v) => (v <= 0.04045 ? v / 12.92 : ((v + 0.055) / 1.055) ** 2.4))
+        .reduce((sum, v, i) => sum + v * [0.2126, 0.7152, 0.0722][i], 0);
+    // True when something other than the element's own ancestors sits under its text (an image or a
+    // positioned sibling), so the ancestor background is not what the reader sees.
+    const coveredBy = (t) => {
+        t.el.scrollIntoView({ block: "center" });
+        const range = document.createRange();
+        range.setStartBefore(t.nodes[0]);
+        range.setEndAfter(t.nodes[t.nodes.length - 1]);
+        const r = range.getBoundingClientRect();
+        const stack = document.elementsFromPoint(r.left + r.width / 2, r.top + r.height / 2);
+        const below = stack.find((e) => !t.el.contains(e));
+        return Boolean(below && !below.contains(t.el));
+    };
+    const hex = (c) => `#${c.slice(0, 3).map((v) => Math.round(v).toString(16).padStart(2, "0")).join("")}`;
+    // Contrast (RX-A11Y-01) and size (RX-A11Y-02), grouped so one style used 40 times is one finding.
+    const contrast = new Map();
+    const small = new Map();
+    for (const t of texts) {
+        const cs = style(t.el);
+        const size = Number.parseFloat(cs.fontSize);
+        if (size < 12) {
+            const g = small.get(size) ?? { t, count: 0 };
+            g.count++;
+            small.set(size, g);
+        }
+        if (disabled(t.el) || cs.webkitTextFillColor === "rgba(0, 0, 0, 0)")
+            continue;
+        const bg = background(t.el);
+        const fgRaw = rgba(cs.color);
+        if (!bg || !fgRaw)
+            continue;
+        const fg = fgRaw[3] < 1 ? over(fgRaw, bg) : fgRaw;
+        const [hi, lo] = [luminance(fg), luminance(bg)].sort((a, b) => b - a);
+        const ratio = (hi + 0.05) / (lo + 0.05);
+        const large = size >= 24 || (size >= 18.66 && Number(cs.fontWeight) >= 700);
+        const need = large ? 3 : 4.5;
+        if (ratio >= need || coveredBy(t))
+            continue;
+        const key = `${hex(fg)}|${hex(bg)}|${need}`;
+        const g = contrast.get(key) ?? { t, ratio, fg, bg, need, count: 0 };
+        g.count++;
+        contrast.set(key, g);
+    }
+    for (const g of contrast.values()) {
+        out.push({
+            rule: "RX-A11Y-01",
+            level: "fail",
+            selector: selector(g.t.el),
+            message: `${quote(g.t.text)}: contrast ${g.ratio.toFixed(2)}:1 (${hex(g.fg)} on ${hex(g.bg)}), needs ${g.need}:1${g.count > 1 ? `; ${g.count - 1} more with the same colors` : ""}`,
+        });
+    }
+    for (const [size, g] of small) {
+        out.push({
+            rule: "RX-A11Y-02",
+            level: "warn",
+            selector: selector(g.t.el),
+            message: `${quote(g.t.text)}: ${size}px text${g.count > 1 ? ` (${g.count} elements)` : ""}; body text is 14 to 16px on mobile, below 12px is hard to read`,
+        });
+    }
+    window.scrollTo(0, 0);
+    // Target size (RX-A11Y-02): under 24px fails unless spaced as WCAG 2.5.8 allows; inline links in a
+    // sentence are exempt.
+    const controls = [
+        ...document.body.querySelectorAll("a[href],button,input:not([type=hidden]),select,textarea,summary,[role=button],[role=link],[role=checkbox],[role=radio],[role=switch],[role=tab],[role=menuitem]"),
+    ].filter((el) => shown(el) && !disabled(el));
+    const rects = controls.map((el) => el.getBoundingClientRect());
+    const inSentence = (el) => {
+        if (el.tagName !== "A" || style(el).display !== "inline")
+            return false;
+        const block = el.parentElement;
+        return Boolean(block && block.textContent.replace(el.textContent, "").trim().length > 0);
+    };
+    const center = (r) => [r.left + r.width / 2, r.top + r.height / 2];
+    const undersized = controls.map((el, i) => (rects[i].width < 24 || rects[i].height < 24) && !inSentence(el));
+    controls.forEach((el, i) => {
+        if (!undersized[i])
+            return;
+        const [cx, cy] = center(rects[i]);
+        const crowded = rects.some((r, j) => {
+            if (j === i || el.contains(controls[j]) || controls[j].contains(el))
+                return false;
+            if (undersized[j]) {
+                const [x, y] = center(r);
+                return Math.hypot(cx - x, cy - y) < 24;
+            }
+            const dx = Math.max(r.left - cx, 0, cx - r.right);
+            const dy = Math.max(r.top - cy, 0, cy - r.bottom);
+            return Math.hypot(dx, dy) < 12;
+        });
+        const size = `${Math.round(rects[i].width)}x${Math.round(rects[i].height)}px`;
+        const name = quote((el.getAttribute("aria-label") || el.textContent || el.tagName.toLowerCase()).trim().replace(/\s+/g, " "));
+        out.push(crowded
+            ? { rule: "RX-A11Y-02", level: "fail", selector: selector(el), message: `${name}: target ${size}, under 24x24 and crowded by its neighbours; 44x44 is the preferred hit area` }
+            : { rule: "RX-A11Y-02", level: "warn", selector: selector(el), message: `${name}: target ${size}, under 24x24 (spaced enough to pass WCAG 2.5.8); 44x44 is the preferred hit area` });
+    });
+    // Colliding text (RX-QA-03): the text boxes of two unrelated elements overlap.
+    const boxes = texts.slice(0, 1500).map((t) => {
+        const range = document.createRange();
+        range.setStartBefore(t.nodes[0]);
+        range.setEndAfter(t.nodes[t.nodes.length - 1]);
+        return { t, r: range.getBoundingClientRect() };
+    });
+    // Content that scrolls under a fixed or sticky bar is not a collision.
+    const pinned = (el) => {
+        for (let e = el; e; e = e.parentElement)
+            if (/^(fixed|sticky)$/.test(style(e).position))
+                return true;
+        return false;
+    };
+    const seen = new Set();
+    for (let i = 0; i < boxes.length; i++) {
+        for (let j = i + 1; j < boxes.length; j++) {
+            const a = boxes[i];
+            const b = boxes[j];
+            if (a.t.el.contains(b.t.el) || b.t.el.contains(a.t.el) || pinned(a.t.el) !== pinned(b.t.el))
+                continue;
+            const w = Math.min(a.r.right, b.r.right) - Math.max(a.r.left, b.r.left);
+            const h = Math.min(a.r.bottom, b.r.bottom) - Math.max(a.r.top, b.r.top);
+            if (w <= 2 || h <= 2)
+                continue;
+            const smaller = Math.min(a.r.width * a.r.height, b.r.width * b.r.height);
+            if (w * h < 0.3 * smaller || seen.has(a.t.el) || seen.has(b.t.el))
+                continue;
+            seen.add(a.t.el);
+            seen.add(b.t.el);
+            out.push({ rule: "RX-QA-03", level: "warn", selector: selector(a.t.el), message: `${quote(a.t.text)} overlaps ${quote(b.t.text)} (${selector(b.t.el)})` });
+        }
+    }
+    return out;
+}

package/dist/cli/page-scan.js

@@ -0,0 +1,70 @@
+// `ryux scan <url>`: render a page with Playwright at each width and measure it (./page-probe.ts).
+// Playwright is optional: it is loaded from the user's project (or a global install) and never
+// bundled, so installing RYUX stays light.
+import { createRequire } from "node:module";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+import { probe } from "./page-probe.js";
+export const PLAYWRIGHT_MISSING = "Scanning a URL needs Playwright, which RYUX does not install for you. In this project run:\n  npm i -D playwright && npx playwright install chromium";
+async function loadChromium() {
+    const fromProject = createRequire(join(process.cwd(), "noop.js"));
+    for (const name of ["playwright", "playwright-core", "@playwright/test"]) {
+        try {
+            const mod = (await import(pathToFileURL(fromProject.resolve(name)).href));
+            const chromium = mod.chromium ?? mod.default?.chromium;
+            if (chromium)
+                return chromium;
+        }
+        catch {
+            // not installed under this name; try the next
+        }
+    }
+    return null;
+}
+/** Render each URL at each width and return the findings. Throws PLAYWRIGHT_MISSING when there is no
+ *  Playwright, and a launch error when its browser is not installed. */
+export async function scanPages(urls, widths) {
+    const chromium = await loadChromium();
+    if (!chromium)
+        throw new Error(PLAYWRIGHT_MISSING);
+    let browser;
+    try {
+        browser = await chromium.launch();
+    }
+    catch (err) {
+        throw new Error(`Playwright could not start Chromium. Run: npx playwright install chromium\n${err instanceof Error ? err.message.split("\n")[0] : err}`);
+    }
+    const findings = [];
+    try {
+        for (const url of urls) {
+            for (const width of widths) {
+                // Reduced motion lets animations settle, so the page is measured in its final state.
+                const ctx = await browser.newContext({ viewport: { width, height: width <= 480 ? 844 : 900 }, reducedMotion: "reduce" });
+                const page = await ctx.newPage();
+                const errors = [];
+                page.on("pageerror", (e) => errors.push(e.message.split("\n")[0]));
+                const add = (f) => {
+                    findings.push({ ...f, file: url, line: 0, column: 0, width });
+                };
+                try {
+                    await page.goto(url, { waitUntil: "networkidle", timeout: 30_000 }).catch(() => page.goto(url, { waitUntil: "load", timeout: 30_000 }));
+                }
+                catch (err) {
+                    add({ rule: "RX-QA-08", level: "fail", selector: "page", message: `the page did not load: ${err instanceof Error ? err.message.split("\n")[0] : err}` });
+                    await ctx.close();
+                    continue;
+                }
+                await page.waitForTimeout(300);
+                (await page.evaluate(probe)).forEach(add);
+                for (const message of [...new Set(errors)]) {
+                    add({ rule: "RX-QA-08", level: "warn", selector: "page", message: `the page threw "${message}" while loading; check that the primary task still completes` });
+                }
+                await ctx.close();
+            }
+        }
+    }
+    finally {
+        await browser.close();
+    }
+    return findings;
+}

package/dist/cli/scan.js

@@ -0,0 +1,160 @@
+// `ryux scan`: run the deterministic detectors (../scan.ts) over files and folders, measure rendered
+// pages given as URLs (./page-scan.ts), or check the file an agent just edited (--hook, fed by a
+// Claude Code PostToolUse hook on stdin).
+import { existsSync, statSync } from "node:fs";
+import { readFile, readdir } from "node:fs/promises";
+import { join, relative } from "node:path";
+import pc from "picocolors";
+import { RULES } from "../intelligence/content.js";
+import { VERSION } from "../product.js";
+import { DETECTORS, RENDER_CHECKS, SCAN_EXTS, scanSources, toSource } from "../scan.js";
+import { scanPages } from "./page-scan.js";
+const DEFAULT_WIDTHS = [320, 390, 1280];
+const isUrl = (t) => /^(?:https?|file):\/\//.test(t);
+const SKIP_DIRS = new Set(["node_modules", "dist", "build", "out", "coverage", "vendor", ".next", ".nuxt", ".svelte-kit", ".output"]);
+const MAX_BYTES = 512 * 1024;
+const scannable = (path) => SCAN_EXTS.includes(path.slice(path.lastIndexOf(".") + 1).toLowerCase()) && !/\.(?:min\.\w+|d\.ts)$/.test(path);
+async function walk(dir, out) {
+    for (const entry of await readdir(dir, { withFileTypes: true })) {
+        if (entry.name.startsWith(".") || SKIP_DIRS.has(entry.name))
+            continue;
+        const full = join(dir, entry.name);
+        if (entry.isDirectory())
+            await walk(full, out);
+        else if (entry.isFile() && scannable(full))
+            out.push(full);
+    }
+}
+async function scanPaths(paths, skip) {
+    const files = [];
+    let folder = false;
+    for (const p of paths) {
+        if (statSync(p).isDirectory()) {
+            folder = true;
+            await walk(p, files);
+        }
+        else if (scannable(p))
+            files.push(p);
+    }
+    const sources = [];
+    for (const f of files) {
+        if (statSync(f).size > MAX_BYTES)
+            continue;
+        sources.push(toSource(relative(process.cwd(), f) || f, await readFile(f, "utf8")));
+    }
+    return { files: sources.length, findings: scanSources(sources, { folder, skip }) };
+}
+const title = (id) => RULES.find((r) => r.id === id)?.title ?? "";
+function listRules(json) {
+    if (json) {
+        const entry = (d, kind) => ({ rule: d.rule, title: title(d.rule), level: d.level, kind, looksFor: d.looksFor, folderOnly: Boolean(d.folder) });
+        console.log(JSON.stringify([...DETECTORS.map((d) => entry(d, "source")), ...RENDER_CHECKS.map((d) => entry(d, "render"))], null, 2));
+        return;
+    }
+    const row = (d) => {
+        console.log(`${d.level === "fail" ? pc.red("fail") : pc.yellow("warn")}  ${d.rule.padEnd(11)} ${title(d.rule)}`);
+        console.log(`      ${d.looksFor}${d.folder ? " (folder scans only)" : ""}`);
+    };
+    console.log(`ryux scan v${VERSION}: checks for rules a machine can see. No LLM.\n\nSource files (${DETECTORS.length}):`);
+    DETECTORS.forEach(row);
+    console.log(`\nRendered pages, for a URL (${RENDER_CHECKS.length}; needs Playwright in the project; widths ${DEFAULT_WIDTHS.join(", ")} unless --widths):`);
+    RENDER_CHECKS.forEach(row);
+    console.log(`\nfail: wrong wherever it appears, exit 1. warn: worth a look, exit 0.
+Not checked: a judgment call, which belongs to Critique.`);
+}
+/** Read the PostToolUse payload Claude Code sends on stdin and return the edited file, if any. */
+async function hookFile() {
+    let input = "";
+    for await (const chunk of process.stdin)
+        input += chunk;
+    try {
+        const payload = JSON.parse(input);
+        return payload.tool_input?.file_path ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+function report(findings, files, pages = 0) {
+    const mark = { fail: pc.red("✗"), warn: pc.yellow("!") };
+    const lines = findings.map((f) => f.width ? `${mark[f.level]} ${f.file} @${f.width}px ${f.rule} ${f.message} [${f.selector}]` : `${mark[f.level]} ${f.file}:${f.line}:${f.column} ${f.rule} ${f.message}`);
+    const fails = findings.filter((f) => f.level === "fail").length;
+    const warns = findings.length - fails;
+    const what = [files || !pages ? `${files} file${files === 1 ? "" : "s"}` : "", pages ? `${pages} page${pages === 1 ? "" : "s"}` : ""].filter(Boolean).join(" and ");
+    lines.push(`${lines.length ? "\n" : ""}${what} scanned: ${fails} fail, ${warns} warn.`);
+    return lines.join("\n");
+}
+export async function runScan(argv) {
+    const paths = [];
+    const skip = new Set();
+    const opts = { json: false, hook: false, list: false };
+    let widths = DEFAULT_WIDTHS;
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (a === "--json")
+            opts.json = true;
+        else if (a === "--hook")
+            opts.hook = true;
+        else if (a === "--list-rules")
+            opts.list = true;
+        else if (a === "--widths") {
+            widths = (argv[++i] ?? "").split(",").map(Number);
+            if (!widths.length || widths.some((w) => !Number.isInteger(w) || w < 200 || w > 3840)) {
+                console.error("--widths takes CSS pixel widths from 200 to 3840, e.g. --widths 320,390,1280");
+                process.exitCode = 2;
+                return;
+            }
+        }
+        else if (a === "--ignore")
+            (argv[++i] ?? "").split(",").filter(Boolean).forEach((id) => skip.add(id.trim()));
+        else if (a.startsWith("--")) {
+            console.error(`Unknown option for scan: ${a}`);
+            process.exitCode = 2;
+            return;
+        }
+        else
+            paths.push(a);
+    }
+    if (opts.list)
+        return listRules(opts.json);
+    if (opts.hook) {
+        // A hook must never block an edit by crashing: anything unexpected ends quietly with exit 0.
+        const file = await hookFile();
+        if (!file || !existsSync(file) || !scannable(file))
+            return;
+        const { findings } = await scanPaths([file], skip);
+        if (!findings.length)
+            return;
+        console.error(`RYUX scan found ${findings.length} issue${findings.length === 1 ? "" : "s"} in the file you just edited. Fix each fail; for each warn, fix it or add a ryux-ignore comment with the reason.\n${report(findings, 1)}`);
+        process.exitCode = 2;
+        return;
+    }
+    const urls = paths.filter(isUrl);
+    const local = paths.filter((t) => !isUrl(t));
+    const targets = local.length || urls.length ? local : ["."];
+    const missing = targets.filter((t) => !existsSync(t));
+    if (missing.length) {
+        console.error(`Not found: ${missing.join(", ")}`);
+        process.exitCode = 2;
+        return;
+    }
+    const { files, findings } = targets.length ? await scanPaths(targets, skip) : { files: 0, findings: [] };
+    if (urls.length) {
+        try {
+            findings.push(...(await scanPages(urls, widths)).filter((f) => !skip.has(f.rule)));
+        }
+        catch (err) {
+            console.error(err instanceof Error ? err.message : err);
+            process.exitCode = 1;
+            return;
+        }
+    }
+    const ok = !findings.some((f) => f.level === "fail");
+    if (!ok)
+        process.exitCode = 1;
+    if (opts.json) {
+        console.log(JSON.stringify({ ok, cli: VERSION, files, pages: urls.length, widths: urls.length ? widths : [], findings }, null, 2));
+        return;
+    }
+    console.log(report(findings, files, urls.length));
+}

package/dist/intelligence/analyze.js

@@ -55,8 +55,10 @@ Cover what the captures show; skip what they do not, and say it was not visible.
 | **Imagery and motion** | art direction (product UI, photography, illustration, 3D) and its style; each visual's job; composition (where the focal point sits, the space kept for copy); motion character and level (L1 to L5) when motion was captured |
 | **Design language** | the visual language in 3 to 5 traits, each tied to evidence; component patterns; the spacing and typography systems; interaction patterns |
 
-Also note content and tone (natural Indonesian or translated, how money and dates are written) and
-local patterns (QRIS, virtual accounts, OTP, addresses, paylater, e-KYC).
+Also note content and tone (natural Indonesian or translated, how money and dates are written,
+"kamu" or "Anda") and local patterns (QRIS, virtual accounts, OTP, addresses, paylater, e-KYC). When
+there is enough copy, place the voice on the four RX-CD-11 scales with the screens it comes from;
+it is observed, not the brand's rule until the user confirms it.
 
 ### 4. Patterns and evidence
 

package/dist/intelligence/content.js

@@ -81,7 +81,7 @@ export const RULES = [
             level: "required",
             gate: "hard",
             do: "Give each screen one clear, dominant goal. When the task has a clear next step (a form, checkout, a confirmation), give it one primary action and make secondary actions look secondary.",
-            dont: "Put two equal-weight calls to action side by side, or leave the screen's goal unclear.",
+            dont: "Put two equal-weight calls to action side by side.",
             notWhen: "Monitoring and configuration screens (dashboards, settings) need a clear goal but not a single dominant action; do not invent one to satisfy this rule.",
             why: "A single clear path shortens the decision and the task.",
             basis: "Hick's law (Hick 1952; Hyman 1953): more options, longer decisions; NNGroup visual hierarchy",
@@ -661,13 +661,13 @@ export const RULES = [
             num: 11,
             title: "Tone fits the moment, voice stays",
             level: "preferred",
-            do: "Set a tone profile once, from the brand and the users, on four scales: formal to casual, serious to funny, respectful to irreverent, matter-of-fact to enthusiastic; add a few tone words and the anti-tone words to avoid (\"hangat, tidak sok akrab\").\n  - Keep the voice the same everywhere and shift the tone with the user's state: matter-of-fact and serious for errors, money, and waiting; brief for success, where a check mark already says it worked (\"Alamat disimpan\", without \"berhasil\" unless the voice wants the warmth); warmer only in onboarding and empty moments.\n  - Add personality only where it costs no clarity or length: clarity first, concision second, character third.",
+            do: "Set a tone profile once, from the brand and the users, on four scales: formal to casual, serious to funny, respectful to irreverent, matter-of-fact to enthusiastic; add a few tone words and the anti-tone words to avoid (\"hangat, tidak sok akrab\").\n  - Take it from the Voice and tone field in DESIGN.md when it is set. When it is blank, infer it from the product's existing copy or brand docs, label it inferred in Assumptions, and keep it out of DESIGN.md until the user confirms it: copy that is live is observed, not a brand rule.\n  - Keep the voice the same everywhere and shift the tone with the user's state: matter-of-fact and serious for errors, money, and waiting; brief for success, where a check mark already says it worked (\"Alamat disimpan\", without \"berhasil\" unless the voice wants the warmth); warmer only in onboarding and empty moments.\n  - Add personality only where it costs no clarity or length: clarity first, concision second, character third.",
             dont: "Joke in an error or a payment failure, cheer on a routine save, or switch between \"kamu\" and \"Anda\" across screens.",
             why: "The same words feel caring in one moment and careless in another; tone measurably changes how users judge a product.",
             basis: "NNGroup tone-of-voice dimensions (four dimensions; tested tone profiles); NNGroup 3 C's of informational microcopy",
             notWhen: "the brand guide already defines the tone; follow it",
             tradeoff: "a sober tone in serious moments gives up some brand flavour",
-            check: "review",
+            check: "review against the Voice and tone field in DESIGN.md; a profile taken from existing copy is labeled inferred",
         },
         {
             num: 12,
@@ -814,8 +814,8 @@ export const RULES = [
             title: "Detail craft",
             level: "preferred",
             gate: "lock",
-            do: "Center icons on the optical middle of the text beside them and size them to its line-height; match icon stroke to the type weight; right-align (or decimal-align) number columns; take borders, dividers, radii, and shadows from a small token set; truncate long text on purpose, with the full value still reachable (a tooltip, a detail view, or wrapping).",
-            dont: "Let icons sit high or low against their labels, mix stroke weights, center amounts in a table, or invent a one-off shadow for one card.",
+            do: "Center icons on the optical middle of the text beside them and size them to its line-height; take every icon from one set and match its stroke to the type weight; right-align (or decimal-align) number columns; take borders, dividers, radii, and shadows from a small token set; truncate long text on purpose, with the full value still reachable (a tooltip, a detail view, or wrapping).",
+            dont: "Let icons sit high or low against their labels, mix icon sets or stroke weights, center amounts in a table, or invent a one-off shadow for one card.",
             why: "Each detail is small; together they are what makes a screen look made rather than generated.",
             basis: "Bringhurst (figures and alignment); Apple HIG and Material iconography (optical size and alignment); owner review 2026-10-17: wrong tab icons in withryux.pen",
             check: "render inspection at 390 and 1280: icon center within 2 px of the text center; column alignment",
@@ -865,6 +865,7 @@ export const RULES = [
             num: 11,
             title: "Motion earns its level",
             level: "contextual",
+            gate: "lock",
             when: "the design adds motion or transitions",
             do: "Classify each motion: L1 state feedback, L2 component transition, L3 page transition, L4 storytelling, L5 decorative; the higher the level, the stronger the reason it needs.\n  - Weigh how often people see it: a surface opened many times a day (command palette, shortcut, core navigation, list selection) appears and closes without movement, at most a fade too short to notice; standard transitions belong to occasional surfaces (modal, drawer, toast), and expression to rare or first-time moments.\n  - Take timing and easing from one motion personality, define them once as motion tokens, animate transform and opacity rather than layout properties, and honor reduced motion (RX-A11Y-08).\n  - Anything that opens and closes (menu, popover, dialog, drawer) uses transitions that can reverse halfway, so a close or reopen mid-animation turns back from where it is, and it closes no slower than it opened.",
             dont: "Animate everything, give a surface people open many times a day an entrance they must sit through, play an open-only keyframe animation on something people can close or reopen at any moment, use one generic duration and easing (transition: all 0.3s) everywhere, let decorative motion delay content or input, or move data the user is reading (a balance, an amount, a table value) for effect.",
@@ -1294,6 +1295,18 @@ export const RULES = [
             basis: `pattern also in ${AS} R-33; written for RYUX`,
             check: "review the diff",
         },
+        {
+            num: 16,
+            title: "The build passes",
+            level: "required",
+            gate: "hard",
+            do: "Before handoff, run the checks the repo already has (build, typecheck, lint, tests) and fix what fails. Report each one you ran and its result; a check you could not run is named, and the work is not called done.",
+            dont: "Hand off code that does not build or typecheck, silence an error to make it pass (a type cast, a disabled rule, a skipped test), or call it done without running the checks.",
+            notWhen: "design-only work with no code; then CODE QUALITY is N/A",
+            why: "A build that fails cannot be reviewed, rendered, or shipped; every other check in the Delivery Gate depends on it.",
+            basis: "Continuous integration practice; owner review 2026-10-25: build failure belongs with the checks that cannot be argued",
+            check: "run the repo's build, typecheck, lint, and tests; fails on any error",
+        },
     ]),
     ...skill("visual-qa", [
         {
@@ -1337,6 +1350,18 @@ export const RULES = [
             basis: "ryux visual QA loop; ryux evidence principle",
             check: "screenshot comparison, search_screens",
         },
+        {
+            num: 8,
+            title: "The primary task completes",
+            level: "required",
+            gate: "hard",
+            do: "In the running build or a clickable prototype, do the screen's primary task from start to result as a user would (tap, type, submit), then one failure path (invalid input or a failed request). Name the path you ran.",
+            dont: "Hand off a primary flow with a dead end: a button that does nothing, a submit that never resolves, a step that cannot be reached, or an error with no way back.",
+            notWhen: "static mockups with no interaction; then say the flow was not run and VISUAL QA is NOT VERIFIED",
+            why: "A broken primary action fails the one thing the screen exists for, whatever else is right.",
+            basis: "Usability testing practice (task completion); owner review 2026-10-25: a broken main interaction belongs with the checks that cannot be argued",
+            check: "run the primary task and one failure path in the render; fails on any dead end",
+        },
     ]),
     ...skill("anti-slop", [
         {
@@ -1402,12 +1427,11 @@ export const RULES = [
             num: 6,
             title: "Complexity with a reason",
             level: "required",
-            gate: "hard",
             do: "Remove elements, options, states, code paths, abstractions, and dependencies that serve no stated need. Complexity that cannot be removed is carried by the product (defaults, formatting, calculation), not handed to the user.",
             dont: "Add settings, sections, abstractions, or packages \"for later\", or features because similar products have them.",
             why: "Unneeded complexity costs every user and every future change.",
             basis: "Nielsen heuristic 8; Tesler's law of conserved complexity (Tesler, 1980s): some complexity cannot be removed, only moved; clean-code practice",
-            check: "list each element, option, state, and dependency the work added and the need it serves; fails on any without one",
+            check: "list each element, option, state, and dependency the work added and the need it serves; fails on any without one or a written reason",
             formerly: ["RX-K-05"],
         },
         {
@@ -1538,10 +1562,11 @@ export const HARD_GATES = [
     { item: "Missing critical states", rules: ["RX-EC-01"] },
     { item: "Broken responsive behavior", rules: ["RX-RD-01"] },
     { item: "Accessibility failures", rules: ["RX-A11Y-01", "RX-A11Y-02", "RX-A11Y-03", "RX-A11Y-04"] },
-    { item: "Unclear goal or competing actions", rules: ["RX-PR-03"] },
-    { item: "Unexplained interaction behavior", rules: ["RX-IX-01", "RX-IX-12"] },
+    { item: "Competing primary actions", rules: ["RX-PR-03"] },
+    { item: "Unexplained interaction behavior", rules: ["RX-IX-01"] },
     { item: "Duplicate components", rules: ["RX-DS-01"] },
-    { item: "Unnecessary complexity", rules: ["RX-AS-06"] },
+    { item: "Build or typecheck fails", rules: ["RX-FE-16"] },
+    { item: "Primary task cannot be completed", rules: ["RX-QA-08"] },
 ];
 // Brief item: consistency that must hold across the product.
 export const QUALITY_LOCKS = [
@@ -1554,6 +1579,8 @@ export const QUALITY_LOCKS = [
     { item: "Responsive behavior", rules: ["RX-RD-06"] },
     { item: "Visual hierarchy", rules: ["RX-UI-01"] },
     { item: "Radius", rules: ["RX-UI-03", "RX-DS-03"] },
+    { item: "Icons", rules: ["RX-UI-15", "RX-UI-20"] },
+    { item: "Motion", rules: ["RX-UI-11"] },
 ];
 // Contextual activation: load only what the task needs (core is always loaded).
 export const ACTIVATION = [

package/dist/intelligence/guides.js

@@ -44,9 +44,9 @@ export const CORE_WORKFLOW = `One workflow, six stages; each entry point runs th
    structure, not paint; reference screens through the ryux MCP when connected. A small change skips it.
 4. **Evaluate and select**: rate the alternatives against the Frame criteria with evidence
    (RX-PR-09, RX-PR-10); the user picks from options (capabilities/design.md); write the Decision Receipt.
-5. **Build and critique**: design or implement the choice, render, inspect, and fix; Reconsider an
-   unchosen alternative when a finding contradicts the choice, and say why.
+5. **Build and critique**: design or implement the choice, render, inspect, and fix.
 6. **Verify and deliver**: Hard Gates, the Delivery Gate, honest claims, and a user test plan (RX-UX-12).
+   In 5 or 6, a finding rooted in the frame or the choice goes back to stage 2 or 3 (Reconsider an unchosen alternative), with the reason; it is not patched in the build.
 
 Analyze runs 1. Design runs 1-6. Build runs 1, 5, and 6 (2-4 through Design when no design exists).
 Critique runs 1 and the critique half of 5. QA runs 6. Never go from "generate" straight to "done".`;
@@ -73,17 +73,22 @@ The six stages of the core workflow (SKILL.md), as Design runs them.
    counts toward the three) instead of choosing it yourself. **No DESIGN.md and no product docs is the
    case where these questions matter most, never a reason to skip them:** ask, then wait for the
    answer before designing. Complete context means no questions.
+   **Voice and tone** is not asked by default: when the field is blank, infer it from the product's
+   existing copy or brand docs, label it inferred, and continue (RX-CD-11). Ask only when there is
+   no source at all and the work is mostly copy (onboarding, marketing, error and success messages);
+   it counts toward the three.
    **Ask as choices.** When you ask, or the user picks (stage 4, Reconsider), use the agent's
    question or choice tool if it has one: two to four options per question, the recommended one
    first and labeled, and room for the user's own answer. Without such a tool, write numbered
    options with the recommendation first, so the user can answer with a number. Never ask what the prompt, DESIGN.md, or the
    product docs already answer. For the rest, make the smallest reasonable assumption, write it
    down, and continue (RX-PR-01, RX-PR-02).
-   **Record direction answers.** When the user answers a UI or motion direction question, write the
-   answer into the UI direction or Motion direction field of the RYUX project context in DESIGN.md:
+   **Record direction answers.** When the user answers a UI direction, motion direction, or voice
+   question, or confirms an inferred voice, write the answer into the UI direction, Motion direction,
+   or Voice and tone field of the RYUX project context in DESIGN.md:
    between \`<!-- ryux-context:start -->\` and \`<!-- ryux-context:end -->\`, one line per field
    (\`- **UI direction**: Calm, trustworthy\`). If DESIGN.md or the block does not exist, create it
-   with those two fields. Change only those field lines; leave every other line as it is. Your own
+   with the fields answered. Change only those field lines; leave every other line as it is. Your own
    assumptions do not go into DESIGN.md.
    **What exists.** When there is a screen, product, or design system already, read its
    analysis or run Analyze first (capabilities/analyze.md). Existing screens, components, and any
@@ -305,7 +310,8 @@ workflow (SKILL.md); Frame, Explore, and Evaluate happen in Design.
    When anything animates, run the motion passes in capabilities/qa.md as well. Run the counts of
    RX-AS-10 on the render and report them in the gate.
 7. **Close with the Delivery Gate.** CODE QUALITY and VISUAL QA need real checks (typecheck,
-   tests, render), or say what was not run. For a new flow or a consequential change, add the
+   tests, render), or say what was not run. Run \`npx @ryuxdsgn/design-intelligence scan <changed
+   paths>\` as well: fix every fail, and fix each warn or give the reason it stays. For a new flow or a consequential change, add the
    usability test plan (RX-UX-12) unless the design already has one.`;
 export const CORE_EVIDENCE = `Say where every claim comes from:
 
@@ -332,8 +338,7 @@ compliance, product or competitor facts, screenshots, or references (RX-PR-02, R
 
 Record a source as \`{ type: observed | inferred | knowledge, origin, reference }\`, for example
 \`{ knowledge, ryux-knowledge, scr_123 }\` from the ryux MCP, or \`{ observed, screenshot, hero.png }\`.
-Optional sources (the ryux MCP, Figma, a browser, screenshots, other reference libraries) add
-evidence when connected; none is required.`;
+Optional sources (the ryux MCP, Figma, a browser, screenshots, other reference libraries) add evidence when connected; none is required.`;
 export const CORE_HONESTY = `Report what was checked, how, and what was not available. Do not claim "pixel perfect",
 "fully accessible", "production ready", "senior-level", or "UX optimized" without evidence. Say
 "Keyboard and focus checked by hand; no automated accessibility test was available" instead.
@@ -761,6 +766,9 @@ render, report these as NOT VERIFIED.
 **Render with what is available**, in this order: the project's own preview or test setup;
 \`npx playwright screenshot --viewport-size=1440,900 <url>\` (and 390 wide for mobile); a browser
 tool; a design-tool export such as pen.dev \`Export\`. If none is available, say so in the gate.
+For a build that runs, also measure it: \`npx @ryuxdsgn/design-intelligence scan <url>\` checks
+sideways scroll, contrast, target size, and colliding text at 320, 390, and 1280 px (it needs
+Playwright in the project). Report its fails in the gate; it does not replace looking at the render.
 
 ${UNTRUSTED_CONTENT}
 

package/dist/render.js

@@ -1,5 +1,6 @@
 import { ACTIVATION, GATE_AREAS, GROUPS, HARD_GATES, LEVEL_LABEL, PURPOSE_GATES, QUALITY_LOCKS, RETIRED, RULES, SKILLS, } from "./intelligence/content.js";
 import { VERSION } from "./product.js";
+import { DETECTORS, RENDER_CHECKS } from "./scan.js";
 import { CORE_CAPABILITIES, CORE_DECISION_RECORD, CORE_EVIDENCE, CORE_HONESTY, CORE_POSITIONING, CORE_PRINCIPLE, CORE_WORKFLOW, BUILD_BODY, DESIGN_BODY, GATE_RULES, GUIDES, } from "./intelligence/guides.js";
 import { CRITIQUE_BODY } from "./intelligence/critique.js";
 import { ANALYZE_BODY } from "./intelligence/analyze.js";
@@ -21,12 +22,18 @@ function ruleBlock(r) {
         lines.push(`- Trade-off: ${r.tradeoff}`);
     if (r.check)
         lines.push(`- Check: ${r.check}`);
+    const machine = DETECTORS.filter((d) => d.rule === r.id);
+    if (machine.length)
+        lines.push(`- Machine check: \`ryux scan\` flags ${machine.map((d) => `${d.looksFor} (${d.level})`).join("; ")}`);
+    const measured = RENDER_CHECKS.filter((d) => d.rule === r.id);
+    if (measured.length)
+        lines.push(`- Measured: \`ryux scan <url>\` flags ${measured.map((d) => `${d.looksFor} (${d.level})`).join("; ")}`);
     return lines.join("\n");
 }
 const LEVELS = `- **[Required]**: applies within its stated scope; an exception needs a written reason.
 - **[Preferred]**: the default; break it only with a short written reason.
 - **[Contextual]**: applies only when its "When" situation is present.
-- **[Hard Gate]**: a Required rule with no exceptions. Fix it before declaring the work complete.
+- **[Hard Gate]**: a Required rule with no exceptions. Fix it before declaring the work complete. Kept for failures a check can show (a run, a count, a measurement, a source); a judgment call is a Required rule and goes to Critique.
 - **[Quality Lock]**: consistency that must hold across the product.`;
 export function activationTable() {
     const rows = ACTIVATION.map((a) => `| ${a.task} | ${a.skills.map((s) => `\`${modulePath(s)}\``).join(", ")} |`);

package/dist/scan.js

@@ -0,0 +1,343 @@
+// Deterministic detectors for RYUX rules a machine can check in source code. Pure: takes file
+// contents, returns findings, no LLM and no network. Each detector names the RX rule it checks; the
+// rule text stays in intelligence/content.ts. "fail" is for a pattern that is wrong wherever it
+// appears; "warn" is for a signal a person or agent should look at.
+/** What `ryux scan <url>` measures on the rendered page (cli/page-probe.ts), for --list-rules and the
+ *  rule text. */
+export const RENDER_CHECKS = [
+    { rule: "RX-RD-01", level: "fail", looksFor: "a page that scrolls sideways at a scanned width, naming the widest elements" },
+    { rule: "RX-A11Y-01", level: "fail", looksFor: "text under 4.5:1 contrast (3:1 when large) on a solid background; text over images or gradients is skipped" },
+    { rule: "RX-A11Y-02", level: "fail", looksFor: "controls under 24x24px that are crowded by neighbours (warn when spaced as WCAG 2.5.8 allows); rendered text under 12px (warn)" },
+    { rule: "RX-QA-03", level: "warn", looksFor: "text boxes of unrelated elements that overlap" },
+    { rule: "RX-QA-08", level: "warn", looksFor: "script errors thrown while the page loads" },
+];
+const MARKUP = ["html", "htm", "jsx", "tsx", "vue", "svelte", "astro"];
+const STYLE = ["css", "scss", "sass", "less"];
+const SCRIPT = ["js", "mjs", "cjs", "ts"];
+const CODE = [...MARKUP, ...SCRIPT];
+/** Every extension `ryux scan` reads. Markdown is left out: docs quote wrong examples on purpose. */
+export const SCAN_EXTS = [...MARKUP, ...STYLE, ...SCRIPT];
+const short = (s) => {
+    const t = s.replace(/\s+/g, " ").trim();
+    return t.length > 48 ? `${t.slice(0, 45)}...` : t;
+};
+/** Every match of each pattern, as hits with the message built from the matched text. */
+function matches(text, patterns) {
+    const hits = [];
+    for (const [re, message] of patterns) {
+        for (const m of text.matchAll(new RegExp(re.source, re.flags.includes("g") ? re.flags : `${re.flags}g`))) {
+            const msg = message(m);
+            if (msg)
+                hits.push({ index: m.index, length: m[0].length, message: msg });
+        }
+    }
+    return hits;
+}
+/** The end of the tag that opens at `start` (index of "<"), skipping ">" inside quotes and {...}. */
+function tagEnd(text, start) {
+    let quote = "";
+    let depth = 0;
+    for (let i = start + 1; i < text.length; i++) {
+        const c = text[i];
+        if (quote) {
+            if (c === quote)
+                quote = "";
+        }
+        else if (c === '"' || c === "'" || c === "`")
+            quote = c;
+        else if (c === "{")
+            depth++;
+        else if (c === "}")
+            depth = Math.max(0, depth - 1);
+        else if (c === ">" && depth === 0)
+            return i;
+    }
+    return -1;
+}
+/** Each opening tag of the given names, with its attribute text. */
+function tags(text, names) {
+    const out = [];
+    for (const m of text.matchAll(new RegExp(`<(${names})(?=[\\s/>])`, "g"))) {
+        const end = tagEnd(text, m.index);
+        if (end < 0)
+            continue;
+        out.push({ index: m.index, length: end - m.index + 1, name: m[1], attrs: text.slice(m.index + m[0].length, end) });
+    }
+    return out;
+}
+const RUPIAH_FIX = "write Rp1.250.000 (Rp right before the number, dots for thousands, no decimals)";
+const px = (v) => Number.parseFloat(v);
+export const DETECTORS = [
+    {
+        rule: "RX-CD-02",
+        level: "fail",
+        looksFor: "Rupiah written as Rp 1.000, Rp. 1.000, Rp1,000, Rp1.000,00, Rp1000, IDR 1000, or Rp followed by a space before a value",
+        exts: SCAN_EXTS,
+        find: ({ text }) => matches(text, [
+            [/\bRp\.?[ \u00a0]*\d[\d.,]*/, (m) => (/^Rp\d{1,3}(?:(?:\.\d{3})*|,\d{1,2})$/.test(m[0].replace(/[.,]$/, "")) && !/,00$/.test(m[0]) ? null : `"${short(m[0])}": ${RUPIAH_FIX}`)],
+            [/\bRp[ \u00a0]+(?:\{|\$\{)/, (m) => `"${short(m[0])}...": Rupiah with a space before the value; ${RUPIAH_FIX}`],
+            [/["'`]Rp\.?[ \u00a0]["'`]/, (m) => `${short(m[0])}: a Rupiah prefix with a space; ${RUPIAH_FIX}`],
+            [/\bIDR[ \u00a0]?\d[\d.,]*/, (m) => `"${short(m[0])}": ${RUPIAH_FIX}`],
+        ]),
+    },
+    {
+        rule: "RX-FE-12",
+        level: "warn",
+        looksFor: "Intl currency style with IDR, which prints Rp 1.250.000,00 (a space, and decimals unless set to 0)",
+        exts: CODE,
+        find: ({ text }) => matches(text, [
+            [/currency\s*:\s*["'`]IDR["'`]/, () => "Intl currency style writes a space after Rp (and ,00 unless maximumFractionDigits is 0): format with id-ID grouping and prepend Rp"],
+        ]),
+    },
+    {
+        rule: "RX-CD-09",
+        level: "warn",
+        looksFor: "dates as 10/02/2026 and times as 2:30 PM in copy",
+        exts: CODE,
+        find: ({ text }) => matches(text, [
+            [/(?<![\d/])\d{1,2}\/\d{1,2}\/\d{4}(?![\d/])/, (m) => `"${m[0]}": in Indonesian copy write 2 Okt 2026 (other markets follow their locale)`],
+            [/\b\d{1,2}[:.]\d{2}\s?(?:AM|PM|am|pm)\b/, (m) => `"${m[0]}": in Indonesian copy write 14.30 in 24-hour form (other markets follow their locale)`],
+        ]),
+    },
+    {
+        rule: "RX-AS-03",
+        level: "fail",
+        looksFor: "lorem ipsum filler",
+        exts: CODE,
+        find: ({ text }) => matches(text, [[/\blorem ipsum\b/i, () => "lorem ipsum: use realistic sample content from the brief, labeled as sample data"]]),
+    },
+    {
+        rule: "RX-AS-03",
+        level: "warn",
+        looksFor: "placeholder content: John Doe, Jane Doe, [DATA], [TBD], XXXX",
+        exts: CODE,
+        find: ({ text }) => matches(text, [
+            [/\b(?:John|Jane) Doe\b/, (m) => `"${m[0]}": a placeholder person; use realistic sample data and label it, or the real name`],
+            [/\[(?:REAL DATA|DATA|TBD|TODO|PLACEHOLDER)\]/i, (m) => `"${m[0]}": a placeholder where sample data would do; keep a visible placeholder only for an asset that does not exist yet`],
+            [/(?<![A-Za-z])X{4,}(?![A-Za-z])/, (m) => `"${m[0]}": placeholder characters; use realistic sample data, labeled`],
+        ]),
+    },
+    {
+        rule: "RX-AS-04",
+        level: "warn",
+        looksFor: "urgency copy (only 2 left, hurry, offer ends tonight, hanya tersisa 2, buruan, stok terbatas)",
+        exts: CODE,
+        find: ({ text }) => matches(text, [
+            [
+                /\bonly \d+ (?:left|remaining)\b|\b(?:offer|sale|deal|promo) ends (?:tonight|today|soon)\b|\bhurry\b|\blimited time only\b|\bdon'?t miss out\b|\bhanya tersisa \d+|\btinggal \d+ lagi\b|\bburuan\b|\b(?:promo|diskon|penawaran) berakhir (?:malam ini|hari ini|segera)\b|\bjangan sampai kehabisan\b|\bstok terbatas\b/i,
+                (m) => `"${m[0]}": urgency copy; keep it only when the deadline or quota is real, stated as a plain fact`,
+            ],
+        ]),
+    },
+    {
+        rule: "RX-A11Y-02",
+        level: "fail",
+        looksFor: "zoom turned off: user-scalable=no, maximum-scale=1, userScalable: false, maximumScale: 1",
+        exts: CODE,
+        find: ({ text }) => matches(text, [
+            [/user-scalable\s*=\s*["']?(?:no|0)\b|maximum-scale\s*=\s*["']?1(?:\.0+)?(?![\d.])|userScalable\s*:\s*false|maximumScale\s*:\s*1(?![\d.])/i, (m) => `"${m[0]}": people must be able to zoom; remove it`],
+        ]),
+    },
+    {
+        rule: "RX-A11Y-02",
+        level: "warn",
+        looksFor: "text set below 12px (CSS font-size, Tailwind text-[Npx], fontSize in style objects)",
+        exts: [...MARKUP, ...STYLE, ...SCRIPT],
+        find: ({ text }) => matches(text, [
+            [/font-size\s*:\s*(\d+(?:\.\d+)?)px|\btext-\[(\d+(?:\.\d+)?)px\]|fontSize\s*:\s*["'`]?(\d+(?:\.\d+)?)(?:px)?["'`]?(?=\s*[,}])/, (m) => {
+                    const v = px(m[1] ?? m[2] ?? m[3]);
+                    return v < 12 ? `${v}px text: body text is 14 to 16px on mobile; below 12px is hard to read` : null;
+                }],
+        ]),
+    },
+    {
+        rule: "RX-A11Y-03",
+        level: "fail",
+        looksFor: "a positive tabindex, which takes the element out of the visual focus order",
+        exts: MARKUP,
+        find: ({ text }) => matches(text, [[/\btab[iI]ndex\s*=\s*(?:["']|\{\s*)?([1-9]\d*)/, (m) => `tabindex ${m[1]}: keep focus order the same as the visual order; use 0 or the DOM order`]]),
+    },
+    {
+        rule: "RX-A11Y-03",
+        level: "warn",
+        looksFor: "focus outlines removed on a control (a button, link, input, or :focus rule) with no focus-visible replacement",
+        exts: [...MARKUP, ...STYLE],
+        find: ({ ext, text }) => {
+            const removed = /outline\s*:\s*["']?(?:none|0)\b|\boutline-none\b/;
+            const replaced = /focus-visible|focus:(?:ring|border|shadow|bg|underline|outline-(?!none))/;
+            const message = "focus outline removed on a control with no focus-visible style: show a visible focus indicator";
+            if (STYLE.includes(ext)) {
+                if (replaced.test(text))
+                    return [];
+                const hits = [];
+                for (const m of text.matchAll(/([^{}]+)\{([^}]*)\}/g)) {
+                    const target = /(?:^|[\s,>+~])(?:button|a|input|select|textarea|summary)\b|:focus(?!-visible|-within)|\[role|\.btn|\*/.test(m[1]);
+                    const r = removed.exec(m[2]);
+                    if (target && r)
+                        hits.push({ index: m.index + m[1].length + 1 + r.index, length: r[0].length, message });
+                }
+                return hits;
+            }
+            return tags(text, "button|a|input|select|textarea|summary|div|span|li")
+                .filter((t) => {
+                if (!removed.test(t.attrs) || replaced.test(t.attrs) || /\btab[iI]ndex\s*=\s*(?:["']|\{\s*)?-1/.test(t.attrs))
+                    return false;
+                return !/^(?:div|span|li)$/.test(t.name) || /\brole\s*=\s*["']?(?:button|link|tab|menuitem|option|checkbox|switch)|(?:^|\s)(?:onClick|onclick|@click|on:click)\s*=/.test(t.attrs);
+            })
+                .map((t) => ({ index: t.index, length: t.length, message }));
+        },
+    },
+    {
+        rule: "RX-A11Y-04",
+        level: "fail",
+        looksFor: "<img> with no alt attribute",
+        exts: MARKUP,
+        find: ({ text }) => tags(text, "img")
+            .filter((t) => !/\balt\s*=/.test(t.attrs) && !/\{\s*\.\.\./.test(t.attrs))
+            .map((t) => ({ index: t.index, length: t.length, message: 'an <img> with no alt: describe meaningful images, use alt="" for decorative ones' })),
+    },
+    {
+        rule: "RX-A11Y-04",
+        level: "warn",
+        looksFor: "a clickable <div> or <span> with no role",
+        exts: MARKUP,
+        find: ({ text }) => tags(text, "div|span")
+            .filter((t) => /(?:^|\s)(?:onClick|onclick|@click|v-on:click|on:click)\s*=/.test(t.attrs) && !/\brole\s*=/.test(t.attrs))
+            .map((t) => ({ index: t.index, length: t.length, message: `a clickable <${t.name}>: use a <button> or <a> so it works from the keyboard and has a role` })),
+    },
+    {
+        rule: "RX-A11Y-04",
+        level: "warn",
+        looksFor: "an icon-only <button> with no accessible name",
+        exts: MARKUP,
+        find: ({ text }) => tags(text, "button").flatMap((t) => {
+            if (/\baria-label(?:ledby)?\s*=|\btitle\s*=|\{\s*\.\.\./.test(t.attrs))
+                return [];
+            const close = text.indexOf("</button>", t.index + t.length);
+            if (close < 0)
+                return [];
+            const inner = text.slice(t.index + t.length, close);
+            const icon = /<svg\b|<i\b|<[A-Z]\w*/.test(inner);
+            const named = /\balt\s*=\s*["'][^"']+["']|\baria-label\s*=/.test(inner);
+            const words = inner.replace(/<[^>]*>/g, "").trim();
+            return icon && !named && !words ? [{ index: t.index, length: t.length, message: "an icon-only <button> with no name: add aria-label or visually hidden text" }] : [];
+        }),
+    },
+    {
+        rule: "RX-A11Y-04",
+        level: "warn",
+        looksFor: "a heading that skips a level (h2 straight to h4)",
+        exts: MARKUP,
+        find: ({ text }) => {
+            const hits = [];
+            let prev = 0;
+            for (const m of text.matchAll(/<h([1-6])(?=[\s>])/g)) {
+                const level = Number(m[1]);
+                if (prev && level > prev + 1)
+                    hits.push({ index: m.index, length: m[0].length, message: `h${prev} then h${level}: headings skip a level; use h${prev + 1}` });
+                prev = level;
+            }
+            return hits;
+        },
+    },
+    {
+        rule: "RX-A11Y-08",
+        level: "warn",
+        looksFor: "animation in a folder where nothing handles prefers-reduced-motion",
+        exts: [...MARKUP, ...STYLE, ...SCRIPT],
+        folder: true,
+        find: ({ text }, ctx) => {
+            if (ctx.reducedMotion !== false)
+                return [];
+            const m = /@keyframes\b|\banimation\s*:|\banimate-[a-z]|<motion\.\w+/.exec(text);
+            return m ? [{ index: m.index, length: m[0].length, message: `"${m[0]}" and nothing in the scanned folder handles prefers-reduced-motion: replace large movement with a fade or a cut when it is set` }] : [];
+        },
+    },
+    {
+        rule: "RX-DS-03",
+        level: "warn",
+        looksFor: "three or more one-off hex colors in a file that is not a token or theme file",
+        exts: [...MARKUP, ...STYLE, ...SCRIPT],
+        find: ({ path, text }) => {
+            if (/token|theme|colou?r|palette|tailwind\.config/i.test(path))
+                return [];
+            const lines = text.split("\n");
+            let offset = 0;
+            const found = [];
+            for (const line of lines) {
+                if (!/--[\w-]+\s*:/.test(line)) {
+                    for (const m of line.matchAll(/(?<=[:(,[]\s*|["'`])(?<!(?:fill|stroke|stop-color)=["'])#(?:[0-9a-fA-F]{8}|[0-9a-fA-F]{6}|[0-9a-fA-F]{3,4})\b/g)) {
+                        found.push({ index: offset + m.index, value: m[0].toLowerCase() });
+                    }
+                }
+                offset += line.length + 1;
+            }
+            const distinct = [...new Set(found.map((f) => f.value))];
+            if (distinct.length < 3)
+                return [];
+            return [{ index: found[0].index, length: found[0].value.length, message: `${distinct.length} one-off colors (${distinct.slice(0, 3).join(", ")}${distinct.length > 3 ? ", ..." : ""}): use the color tokens, or define them by role` }];
+        },
+    },
+];
+/** Blank out comments (keeping length and line breaks) so commented-out code is not scanned. */
+export function stripComments(raw, ext) {
+    const blank = (s) => s.replace(/[^\n]/g, " ");
+    let text = raw.replace(/\/\*[\s\S]*?\*\//g, blank).replace(/<!--[\s\S]*?-->/g, blank);
+    if (ext !== "css") {
+        text = text.replace(/(^|[^:\\"'`])(\/\/[^\n]*)/g, (_, pre, c) => pre + blank(c));
+    }
+    return text;
+}
+export function toSource(path, raw) {
+    const ext = path.slice(path.lastIndexOf(".") + 1).toLowerCase();
+    return { path, ext, raw, text: stripComments(raw, ext) };
+}
+/** Rules switched off by `ryux-ignore RX-..` (this line and the next) or `ryux-ignore-file RX-..`.
+ *  With no IDs, every rule is switched off there. */
+function ignores(raw) {
+    const file = new Set();
+    const lines = new Map();
+    raw.split("\n").forEach((line, i) => {
+        const m = /ryux-ignore(-file)?((?:[\s,]+RX-[A-Z0-9]+-\d+)*)/.exec(line);
+        if (!m)
+            return;
+        const ids = m[2].match(/RX-[A-Z0-9]+-\d+/g) ?? ["*"];
+        if (m[1])
+            ids.forEach((id) => file.add(id));
+        else
+            for (const n of [i + 1, i + 2])
+                lines.set(n, new Set([...(lines.get(n) ?? []), ...ids]));
+    });
+    return { file, lines };
+}
+function lineCol(raw, index) {
+    const before = raw.slice(0, index);
+    const line = before.split("\n").length;
+    return { line, column: index - before.lastIndexOf("\n") };
+}
+/** Run every detector over the sources. Findings are ordered by file, then line. */
+export function scanSources(sources, opts) {
+    const ctx = opts.folder
+        ? { reducedMotion: sources.some((s) => /prefers-reduced-motion|motion-(?:reduce|safe):|useReducedMotion|reducedMotion/.test(s.text)) }
+        : {};
+    const findings = [];
+    for (const src of sources) {
+        const ign = ignores(src.raw);
+        for (const d of DETECTORS) {
+            if (!d.exts.includes(src.ext) || opts.skip?.has(d.rule) || ign.file.has(d.rule) || ign.file.has("*"))
+                continue;
+            if (d.folder && !opts.folder)
+                continue;
+            const seen = new Set();
+            for (const hit of d.find(src, ctx)) {
+                const { line, column } = lineCol(src.raw, hit.index);
+                const off = ign.lines.get(line);
+                if (seen.has(hit.index) || off?.has(d.rule) || off?.has("*"))
+                    continue;
+                seen.add(hit.index);
+                findings.push({ level: d.level, rule: d.rule, file: src.path, line, column, message: hit.message });
+            }
+        }
+    }
+    return findings.sort((a, b) => a.file.localeCompare(b.file) || a.line - b.line || a.column - b.column);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ryuxdsgn/design-intelligence",
-  "version": "2.15.0",
+  "version": "2.19.0",
   "description": "RYUX: design intelligence for AI agents and designers. One skill, five entry points: Analyze, Design, Build, Critique, and QA, for Claude Code, Codex, Cursor, Gemini CLI, OpenCode, Cline, Copilot, and more.",
   "type": "module",
   "bin": {