@godxjp/ui 19.1.0 → 19.3.1

package/scripts/ui-audit.mjs

@@ -1,20 +1,9 @@
 #!/usr/bin/env node
 /**
- * godxjp-ui audit — the design system's own linter for consumer UI code.
- *
- * Enforces the UI-standardization rules that ship with @godxjp/ui
- * (see the app's .claude/skills/frontend-design/rules/ui-standardization.md):
- * use the design system, never hand-roll. Inspired by `@google/design.md lint`
- * — structured, agent-readable findings.
- *
- * Runs from the CONSUMER's repo root and scans its hand-written UI
- * (components / pages / layouts) — never the framework or generated code.
- *
- * Usage (from the consuming app):
- *   node packages/godx-ui/scripts/ui-audit.mjs                 # human report; exit 1 on error
- *   node packages/godx-ui/scripts/ui-audit.mjs --format json
- *   node packages/godx-ui/scripts/ui-audit.mjs --quiet         # errors only
- *   node packages/godx-ui/scripts/ui-audit.mjs src/ui lib/     # custom scan dirs
+ * godxjp-ui audit — the design system's own linter for consumer UI code. Enforces the
+ * UI-standardization rules that ship with @godxjp/ui (see the app's
+ * .claude/skills/frontend-design/rules/ui-standardization.md): use the design system, never
+ * hand-roll.
  */
 import { readdirSync, readFileSync, statSync } from "node:fs";
 import { isAbsolute, join, relative } from "node:path";
@@ -54,6 +43,37 @@ const EMOJI_FLAG = /\p{Regional_Indicator}/u;
  *   CSS Logical Properties L1 (W3C) · HTML Living Standard (WHATWG).
  */
 const RULES = [
+  {
+    id: "no-utility-spacing",
+    scope: "consumer",
+    severity: "error",
+    // Any Tailwind spacing step on the consumer's own markup. Arbitrary values ([13px]) have their
+    // own rule; this is README rule 3, documented for a long time and never enforced: rhythm
+    // comes from Flex gap / ResponsiveGrid / PageContainer, never from gap-*/p-*/m-* utilities.
+    test: /\b(?:gap|gap-x|gap-y|p|px|py|pt|pb|ps|pe|pl|pr|m|mx|my|mt|mb|ms|me|ml|mr)-(?:\d+(?:\.\d+)?|px)\b/,
+    message:
+      "No Tailwind spacing utilities (gap-*/p-*/m-*) for layout — space siblings with <Flex gap> / <ResponsiveGrid>; sections of a page are spaced by <PageContainer> (docs/CONSUMER-RULES.md §3).",
+  },
+  {
+    id: "no-utility-layout",
+    scope: "consumer",
+    severity: "error",
+    // A hand-rolled flex/grid container. The primitives exist precisely so a row is <Flex>, a
+    // stack is <Flex direction="col">, a grid is <ResponsiveGrid> — token gaps, RTL, density.
+    test: /className=(?:"[^"]*|'[^']*|\{`[^`]*)(?<![\w-])(?:flex|inline-flex|grid|inline-grid)(?![\w-])/,
+    message:
+      'No hand-rolled flex/grid — use <Flex> (row), <Flex direction="col"> (stack) or <ResponsiveGrid> (docs/CONSUMER-RULES.md §3).',
+  },
+  {
+    id: "no-hand-rolled-surface",
+    scope: "consumer",
+    severity: "warn",
+    // rounded + border/bg on the consumer's own element = a fake Card / Badge / Avatar / ListRow
+    // that drifts from the real ones (a 38px account pill beside 32px controls).
+    test: /className=(?:"[^"]*|'[^']*|\{`[^`]*)\brounded(?:-(?:full|sm|md|lg|xl|2xl))?\b[^"'`]*\b(?:border|bg-)/,
+    message:
+      "Hand-rolled surface (rounded + border/bg) — use Card, Badge, Avatar, ListRow, Descriptions or EmptyState so height, padding and radius come from the tokens (docs/CONSUMER-RULES.md §4).",
+  },
   {
     id: "no-space-xy",
     severity: "error",
@@ -138,7 +158,6 @@ const RULES = [
   // Tailwind class; this catches one in a design-system KNOB the app sets itself
   // (`style={{ "--card-space-inset": "13px" }}`), which is the sanctioned per-instance override
   // route and therefore the one place an app can silently leave the scale. Framework-side the same
-  // check runs over `src/tokens/**` as `pnpm check:token-scale-bypass` (gh#332).
   //
   // Only axes that HAVE named steps are flagged — space, font-size, radius, icon-size. width /
   // height / size / offset have no scale yet, so a number there is the only thing to write and is
@@ -333,26 +352,30 @@ const RULES = [
  * so the executable rules and the agent-facing docs never drift.
  */
 if (args.includes("--rules")) {
-  process.stdout.write(
-    JSON.stringify(
-      RULES.map((r) => ({
-        id: r.id,
-        severity: r.severity,
-        standard: r.standard ?? null,
-        message: r.message,
-      })),
-      null,
-      2,
-    ) + "\n",
+  await new Promise((resolve) =>
+    process.stdout.write(
+      JSON.stringify(
+        RULES.map((r) => ({
+          id: r.id,
+          severity: r.severity,
+          standard: r.standard ?? null,
+          message: r.message,
+        })),
+        null,
+        2,
+      ) + "\n",
+      resolve,
+    ),
   );
+  // Exit only once the pipe has drained (a bare process.exit() cut a 367 KB report at 64 KB),
+  // and never fall through to the scan, whose summary line would corrupt the JSON.
   process.exit(0);
 }
 
 /**
  * Blank out `//` line comments and block comments (incl. JSDoc) — replacing them with spaces and
  * preserving newlines so line numbers stay accurate — while KEEPING string/template literals (the
- * className values we actually want to scan). Prevents false positives like a doc-comment that
- * literally says "Never a raw <input>".
+ * className values we actually want to scan).
  */
 function stripComments(src) {
   let out = "";
@@ -464,6 +487,25 @@ const CARD_FLUSH =
 const BARE_FIELD =
   /<(?:label|Label)\b[^>]*>[\s\S]{0,240}?<\/(?:label|Label)>\s*<(?:Input|Select|Textarea|NumberInput|SearchInput|SearchSelect|DatePicker|DateRangePicker|TimePicker|MonthPicker|MonthRangePicker|Cascader|TreeSelect|input)\b/g;
 
+// Two <Card> siblings written back to back at the same indentation with nothing between them.
+// Direct children of PageContainer are spaced by the page; anywhere else they touch.
+const SIBLING_CARDS = /^([ \t]*)<\/Card>\s*\n\1<Card\b/gm;
+
+/**
+ * `scope: "consumer"` rules ban utilities on a CONSUMER's own markup. Inside the library repo the
+ * utilities are the design system itself (that is where `flex`/`gap-*` are supposed to live), so
+ * those rules are skipped when the CWD package is @godxjp/ui — unless `--consumer` forces them.
+ */
+const SELF = (() => {
+  try {
+    return JSON.parse(readFileSync(join(CWD, "package.json"), "utf8")).name === "@godxjp/ui";
+  } catch {
+    return false;
+  }
+})();
+const ACTIVE_RULES =
+  SELF && !args.includes("--consumer") ? RULES.filter((r) => r.scope !== "consumer") : RULES;
+
 const findings = [];
 for (const dir of SCAN_DIRS) {
   for (const file of walk(isAbsolute(dir) ? dir : join(CWD, dir))) {
@@ -473,7 +515,7 @@ for (const dir of SCAN_DIRS) {
     const scanContent = stripComments(content); // comments blanked; strings + line numbers kept
     const scanLines = scanContent.split("\n");
     scanLines.forEach((line, i) => {
-      for (const rule of RULES) {
+      for (const rule of ACTIVE_RULES) {
         if (
           rule.test.test(line) &&
           !isSuppressed(rule.id, origLines[i], origLines[i - 1]) &&
@@ -505,6 +547,25 @@ for (const dir of SCAN_DIRS) {
         snippet: match[0].replace(/\s+/g, " ").slice(0, 120),
       });
     }
+    if (
+      !(SELF && !args.includes("--consumer")) &&
+      !/<(?:Flex|ResponsiveGrid|PageContainer)\b/.test(scanContent)
+    ) {
+      for (const match of scanContent.matchAll(SIBLING_CARDS)) {
+        const lineNo = scanContent.slice(0, match.index).split("\n").length + 1;
+        if (isSuppressed("sibling-cards-need-flex", origLines[lineNo - 1], origLines[lineNo - 2]))
+          continue;
+        findings.push({
+          file: rel,
+          line: lineNo,
+          rule: "sibling-cards-need-flex",
+          severity: "warn",
+          message:
+            'Adjacent <Card> siblings with no layout owner — wrap them in <Flex direction="col" gap="lg"> or <ResponsiveGrid> (inside PageContainer the page spaces them for you).',
+          snippet: match[0].replace(/\s+/g, " ").slice(0, 120),
+        });
+      }
+    }
     for (const match of scanContent.matchAll(BARE_FIELD)) {
       const lineNo = scanContent.slice(0, match.index).split("\n").length;
       if (
@@ -560,4 +621,5 @@ if (asJson) {
   }
 }
 
-process.exit(errors.length > 0 ? 1 : 0);
+// See the note above --rules: exitCode, so a large JSON report drains fully.
+process.exitCode = errors.length > 0 ? 1 : 0;

package/scripts/visual-audit-rules.mjs

@@ -1,12 +1,8 @@
 /**
  * Visual-audit decision logic — PURE functions, zero browser/DOM dependency.
- *
- * `scripts/visual-audit.mjs` collects measurements from a REAL rendered page
- * (Playwright) and feeds them here; the browser glue stays thin and these rules
- * are fully unit-testable without a browser. The same functions are injected into
- * the page for in-browser heuristics.
- *
- * Each rule cites the international standard it enforces — see VISUAL_RULES.
+ * `scripts/visual-audit.mjs` collects measurements from a REAL rendered page (Playwright) and
+ * feeds them here; the browser glue stays thin and these rules are fully unit-testable without a
+ * browser.
  */
 
 /** Catalog (agent-facing mirror lives in mcp/src/data/visual-rules.ts; kept in sync by a guard). */
@@ -39,6 +35,34 @@ export const VISUAL_RULES = [
     standard: "Unicode UTS #51 · WCAG 2.2 SC 1.1.1",
     fix: "Remove emoji from rendered product text; use quiet i18n copy + a Lucide icon + a Badge tone for status.",
   },
+  {
+    id: "css-layers-missing",
+    severity: "error",
+    category: "layout",
+    standard: "@godxjp/ui styles contract (styles / styles/core are the only entries)",
+    fix: "A component rendered without its layer: import `@godxjp/ui/styles` (or `styles/core` without fonts) instead of cherry-picking *-layout.css files. Naked menus and unsized Select rows are this.",
+  },
+  {
+    id: "control-height-mismatch",
+    severity: "error",
+    category: "layout",
+    standard: "@godxjp/ui control tier (--control-height) · Nielsen consistency heuristic",
+    fix: "Every control in one row (Flex row, PageContainer extra, footer) must share --control-height. Replace the odd one with the real primitive (Avatar/Button/Badge) instead of a hand-rolled pill; never restyle a control's height.",
+  },
+  {
+    id: "sibling-card-gap",
+    severity: "error",
+    category: "layout",
+    standard: "@godxjp/ui spacing scale (docs/SPACING.md)",
+    fix: 'Adjacent Cards must be separated by at least one space step — wrap them in <Flex direction="col" gap> / <ResponsiveGrid>, or put them directly in PageContainer, which spaces them.',
+  },
+  {
+    id: "row-content-starved",
+    severity: "warn",
+    category: "layout",
+    standard: "WCAG 2.2 SC 1.4.10 reflow (content must not be clipped to hide it)",
+    fix: 'Text in a control row is truncated to a few characters because a sibling takes the whole width (a w-full SelectTrigger). Give the Select width="auto" or move it out of the row.',
+  },
   {
     id: "alert-controls-misplaced",
     severity: "warn",
@@ -114,6 +138,26 @@ export function alertControlIssues(m) {
   return issues;
 }
 
+/** Layers whose probe rule did not resolve. @param {{layer:string, ok:boolean}[]} probes */
+export function missingCssLayers(probes) {
+  return probes.filter((p) => !p.ok).map((p) => p.layer);
+}
+
+/** Rows whose controls disagree on height. @param {{name:string, heights:number[]}[]} rows */
+export function controlHeightMismatches(rows) {
+  return rows.filter((r) => new Set(r.heights).size > 1);
+}
+
+/** Adjacent card pairs closer than the minimum gap. @param {{gap:number}[]} pairs */
+export function tightCardPairs(pairs, min = 8) {
+  return pairs.filter((p) => p.gap < min);
+}
+
+/** Row texts squeezed below a readable width by a sibling. @param {{text:string, visible:number, needed:number}[]} texts */
+export function starvedRowTexts(texts) {
+  return texts.filter((t) => t.needed > 40 && t.visible < Math.min(t.needed, 60));
+}
+
 export function findVisualRule(id) {
   return VISUAL_RULES.find((r) => r.id === id);
 }

package/scripts/visual-audit.mjs

@@ -1,36 +1,7 @@
 #!/usr/bin/env node
 /**
- * godxjp-ui VISUAL audit — the runtime counterpart to the static ui-audit.mjs.
- *
- * Static audit (ui-audit.mjs) reads SOURCE with regexes — zero deps, fast, runs on
- * every save. This audit drives a REAL browser (Playwright) over the running app and
- * runs axe-core + computed-style/layout heuristics, catching what source can't see:
- * colour contrast, target size, OKLCH chroma of a rendered accent, emoji that survived
- * to the DOM, and a mis-laid-out notification banner. Warnings by default (agent
- * guidance) — pass --strict to exit non-zero. Run it BEFORE an AI/human visual review.
- *
- * Playwright + @axe-core/playwright are OPTIONAL peer deps — installed only by apps that
- * run this audit, so the static audit and the library stay browser-free.
- *
- * TESTED peer range (see TESTED_VERSIONS + README "Runtime visual audit"):
- *   playwright               >=1.55 <2   (tested 1.61.1)
- *   @axe-core/playwright     >=4.10 <5   (tested 4.12.1)
- *   axe-core                 >=4.10 <5   (tested 4.12.1)
- *
- * Usage (from the consuming app, against its running dev/preview server):
- *   node node_modules/@godxjp/ui/scripts/visual-audit.mjs http://localhost:5173 /invoices /settings
- *   node node_modules/@godxjp/ui/scripts/visual-audit.mjs http://localhost:5173 --format json
- *   node node_modules/@godxjp/ui/scripts/visual-audit.mjs --strict http://localhost:5173   # CI gate
- *   PLAYWRIGHT_CHROMIUM_EXECUTABLE=/usr/bin/chromium node …/visual-audit.mjs http://…       # system browser
- *
- * JSON contract (--format json ALWAYS emits valid JSON, even on bootstrap failure):
- *   { status: "ok" | "partial" | "error",
- *     tool: <TESTED_VERSIONS>,
- *     summary: { errors, warnings, pages, infrastructureErrors } | null,
- *     findings: [ … product findings … ],
- *     errors:   [ … infrastructure errors (bootstrap / navigate / analyze) … ] }
- *   `status: "ok"` ONLY when every page was audited with zero infrastructure errors —
- *   so a tool/bootstrap failure can NEVER be misread as "zero violations".
+ * godxjp-ui VISUAL audit — the runtime counterpart to the static ui-audit.mjs. Static audit
+ * (ui-audit.mjs) reads SOURCE with regexes — zero deps, fast, runs on every save.
  */
 import { pathToFileURL } from "node:url";
 import {
@@ -40,14 +11,15 @@ import {
   isUndersizedTarget,
   hasEmoji,
   alertControlIssues,
+  missingCssLayers,
+  controlHeightMismatches,
+  tightCardPairs,
+  starvedRowTexts,
 } from "./visual-audit-rules.mjs";
 
 /**
- * Peer versions this audit is tested against. Surfaced in the JSON `tool` field, the
- * README, and the MCP `list_visual_checks` command so agents pin a compatible range.
- * Playwright 1.55+ is required for the `browser.newContext()` / `context.newPage()`
- * flow that @axe-core/playwright 4.10+ expects (older `browser.newPage()` throws
- * "Please use browser.newContext()").
+ * Peer versions this audit is tested against. Surfaced in the JSON `tool` field, the README, and
+ * the MCP `list_visual_checks` command so agents pin a compatible range.
  */
 export const TESTED_VERSIONS = {
   playwright: { range: ">=1.55 <2", tested: "1.61.1" },
@@ -68,10 +40,8 @@ export function buildFinding(ruleId, url, message) {
 }
 
 /**
- * Assemble the machine-readable result (pure). `findings` are PRODUCT results; `errors`
- * are INFRASTRUCTURE failures (a page that would not load, axe that would not inject).
- * `status` is "ok" only when no infra error occurred, "error" when nothing could be
- * audited, "partial" when some pages ran and some failed.
+ * Assemble the machine-readable result (pure). `findings` are PRODUCT results; `errors` are
+ * INFRASTRUCTURE failures (a page that would not load, axe that would not inject).
  */
 export function buildResult({ findings = [], errors = [], pages = 0 } = {}) {
   const productErrors = findings.filter((f) => f.severity === "error");
@@ -93,11 +63,7 @@ export function buildResult({ findings = [], errors = [], pages = 0 } = {}) {
   };
 }
 
-/**
- * Assemble a BOOTSTRAP failure result (pure) — missing peers, no browser, bad args.
- * `summary` is null (never `{ warnings: 0 }`) so a consumer cannot read a bootstrap
- * failure as a clean pass.
- */
+/** Assemble a BOOTSTRAP failure result (pure) — missing peers, no browser, bad args. */
 export function buildBootstrapError(message, hint) {
   return {
     status: "error",
@@ -195,7 +161,80 @@ function collectInPage() {
     });
   }
 
-  return { accents, targets, text, alerts };
+  // Layer completeness — one probe per layer, each checks a rule only that layer sets.
+  const probe = (layer, className, prop, bad) => {
+    const el = document.createElement("div");
+    el.className = className;
+    el.style.position = "absolute";
+    el.style.visibility = "hidden";
+    document.body.appendChild(el);
+    const v = getComputedStyle(el)[prop];
+    el.remove();
+    return { layer, ok: v !== bad && v !== "" };
+  };
+  const layers = [
+    probe("control", "ui-button", "borderRadius", "0px"),
+    probe("navigation-layout", "ui-dropdown-menu-content", "borderTopWidth", "0px"),
+    probe("card-layout", "ui-card", "borderTopWidth", "0px"),
+    probe("layout", "ui-page-container", "display", "block"),
+    probe("dialog-layout", "ui-dialog-content", "position", "static"),
+    probe("form-layout", "ui-form-field", "display", "inline"),
+  ];
+  // Control rows — every control in a row shares the control tier height.
+  const rows = [];
+  for (const row of document.querySelectorAll(
+    ".ui-flex[data-direction=row], .ui-page-header-extra, .ui-page-footer .ui-flex, [data-slot=card-bar]",
+  )) {
+    if (!visible(row)) continue;
+    const controls = [...row.children].filter(
+      (c) =>
+        visible(c) &&
+        (c.matches(
+          "button, [role=combobox], [role=button], input, [data-slot=avatar], .ui-control, .ui-button",
+        ) ||
+          c.querySelector(":scope > button, :scope > [role=combobox]")),
+    );
+    if (controls.length < 2) continue;
+    rows.push({
+      name: (row.className || row.tagName).toString().slice(0, 40),
+      heights: controls.map((c) => Math.round(c.getBoundingClientRect().height)),
+    });
+  }
+  // Sibling cards — the gap between consecutive cards in one parent.
+  const cardPairs = [];
+  const seen = new Set();
+  for (const card of document.querySelectorAll(".ui-card, [data-slot=card]")) {
+    const parent = card.parentElement;
+    if (!parent || seen.has(parent)) continue;
+    seen.add(parent);
+    const cards = [...parent.children].filter(
+      (c) => c.matches(".ui-card, [data-slot=card]") && visible(c),
+    );
+    for (let i = 1; i < cards.length; i++) {
+      const a = cards[i - 1].getBoundingClientRect();
+      const b = cards[i].getBoundingClientRect();
+      const gap =
+        b.top >= a.bottom - 1 ? Math.round(b.top - a.bottom) : Math.round(b.left - a.right);
+      cardPairs.push({ gap });
+    }
+  }
+  // Starved text — a text node in a control row squeezed far below what it needs.
+  const rowTexts = [];
+  for (const row of document.querySelectorAll(
+    ".ui-flex[data-direction=row], .ui-page-footer .ui-flex",
+  )) {
+    for (const t of row.querySelectorAll("[data-slot=text], span, label")) {
+      if (!visible(t) || t.children.length) continue;
+      const cs = getComputedStyle(t);
+      if (cs.overflow !== "hidden" && cs.textOverflow !== "ellipsis") continue;
+      rowTexts.push({
+        text: (t.textContent || "").trim().slice(0, 30),
+        visible: Math.round(t.clientWidth),
+        needed: Math.round(t.scrollWidth),
+      });
+    }
+  }
+  return { accents, targets, text, alerts, layers, rows, cardPairs, rowTexts };
 }
 /* c8 ignore stop */
 
@@ -223,7 +262,6 @@ async function loadDeps() {
 /**
  * Drive the browser over every target and gather findings + infra errors. Cleanup
  * (page/context/browser) is guaranteed via finally on BOTH success and failure.
- * A launch failure is re-tagged as a bootstrap error so it surfaces as `status:error`.
  */
 /* c8 ignore start — the browser-driving glue; exercised by scripts/visual-audit-smoke.mjs in CI. */
 async function audit(targets, { chromium, AxeBuilder }) {
@@ -296,6 +334,39 @@ async function audit(targets, { chromium, AxeBuilder }) {
             buildFinding("emoji-rendered", url, `emoji rendered in product text: ${found}`),
           );
         }
+        for (const layer of missingCssLayers(m.layers || []))
+          findings.push(
+            buildFinding(
+              "css-layers-missing",
+              url,
+              `component layer "${layer}" is not loaded — its rules do not resolve`,
+            ),
+          );
+        for (const r of controlHeightMismatches(m.rows || []))
+          findings.push(
+            buildFinding(
+              "control-height-mismatch",
+              url,
+              `row "${r.name}" mixes control heights ${[...new Set(r.heights)].join("/")}px`,
+            ),
+          );
+        const tight = tightCardPairs(m.cardPairs || []);
+        if (tight.length)
+          findings.push(
+            buildFinding(
+              "sibling-card-gap",
+              url,
+              `${tight.length} adjacent Card pair(s) closer than 8px (min gap ${Math.min(...tight.map((p) => p.gap))}px)`,
+            ),
+          );
+        for (const t of starvedRowTexts(m.rowTexts || []))
+          findings.push(
+            buildFinding(
+              "row-content-starved",
+              url,
+              `text "${t.text}" squeezed to ${t.visible}px of ${t.needed}px by a sibling in its row`,
+            ),
+          );
         m.alerts.forEach((al, i) => {
           for (const issue of alertControlIssues(al))
             findings.push(