@godxjp/ui 13.17.4 → 14.0.1

package/scripts/ui-audit.mjs

@@ -17,7 +17,7 @@
  *   node packages/godx-ui/scripts/ui-audit.mjs src/ui lib/     # custom scan dirs
  */
 import { readdirSync, readFileSync, statSync } from "node:fs";
-import { join, relative } from "node:path";
+import { isAbsolute, join, relative } from "node:path";
 
 const CWD = process.cwd();
 const args = process.argv.slice(2);
@@ -31,7 +31,23 @@ const SCAN_DIRS = dirArgs.length
 const PALETTE =
   "red|orange|amber|yellow|lime|green|emerald|teal|cyan|sky|blue|indigo|violet|purple|fuchsia|pink|rose|gray|grey|slate|zinc|neutral|stone";
 
-/** @type {{id:string, severity:'error'|'warn', test:RegExp, message:string}[]} */
+/**
+ * Emoji in product text — Unicode "Extended_Pictographic" set (UTS #51). Catches
+ * ✅🎉🔥🚀 etc. but NOT typographic punctuation (· — × ✓), which have their own rules.
+ */
+const EMOJI = /\p{Extended_Pictographic}/u;
+/** Regional-indicator pairs = emoji flags (🇯🇵) — broken on Win/Linux; use Intl.DisplayNames. */
+const EMOJI_FLAG = /\p{Regional_Indicator}/u;
+
+/**
+ * @type {{id:string, severity:'error'|'warn', test:RegExp, message:string, standard?:string}[]}
+ *
+ * `standard` cites the international spec a rule enforces, so a finding is auditable
+ * against a real norm rather than house taste alone:
+ *   WCAG 2.2 (W3C Rec) · WAI-ARIA 1.2 + APG (W3C) · ECMA-402 Intl (TC39) ·
+ *   Unicode UTS #51 emoji · BCP-47 · ISO 4217 / 3166 / 8601 · IANA tz ·
+ *   CSS Logical Properties L1 (W3C) · HTML Living Standard (WHATWG).
+ */
 const RULES = [
   {
     id: "no-space-xy",
@@ -177,8 +193,118 @@ const RULES = [
     message:
       "Prefer semantic tokens (text-primary-foreground, bg-background…) over raw white/black (rules §4).",
   },
+
+  // ─── International-standard a11y / i18n / RTL rules (WARN — guide the agent, never block) ───
+  {
+    id: "no-emoji-in-ui",
+    severity: "warn",
+    test: EMOJI,
+    standard: "Unicode UTS #51 (emoji) · WCAG 2.2 SC 1.1.1",
+    message:
+      "No emoji in product UI (✅🎉🔥…). State the fact quietly in i18n-keyed copy; use a Lucide icon for affordance and a Badge `tone` for status. Emoji break on Win/Linux and pollute the accessible name.",
+  },
+  {
+    id: "no-emoji-flag",
+    severity: "warn",
+    test: EMOJI_FLAG,
+    standard: "ISO 3166-1 · ECMA-402 Intl.DisplayNames · Unicode UTS #51",
+    message:
+      "No emoji flags (🇯🇵) — they render inconsistently across OSes. Derive country names from Intl.DisplayNames(locale, { type: 'region' }) keyed by ISO 3166-1 alpha-2.",
+  },
+  {
+    id: "no-physical-direction",
+    severity: "warn",
+    // Physical-edge utilities break RTL. Logical equivalents: ms-/me-/ps-/pe-, start-/end-,
+    // text-start/end, border-s/e, rounded-s/e. `-mx-`/`-px-` (both edges) are RTL-safe → not matched.
+    test: /\b-?(ml|mr|pl|pr|left|right)-(?:\d|\[|auto|px|full)|\b(?:rounded-[tb]?[lr]|border-[lr]|text-(?:left|right))\b/,
+    standard: "W3C CSS Logical Properties & Values L1 · WCAG 2.2 (1.3.2 / reflow)",
+    message:
+      "Use LOGICAL direction utilities for RTL safety: ms-/me-/ps-/pe-, start-/end-, text-start/end, border-s/e, rounded-s/e — not physical ml-/mr-/pl-/pr-/left-/right-/text-left|right.",
+  },
+  {
+    id: "icon-button-needs-name",
+    severity: "warn",
+    // An icon-only Button (size="icon") with no author-supplied accessible name. A combobox/icon
+    // button's name is computed from author (aria-label / aria-labelledby / title), not glyph content.
+    test: /<Button\b(?=[^>]*\bsize=["']icon["'])(?![^>]*\b(?:aria-label|aria-labelledby|title)=)[^>]*>/,
+    standard: "WCAG 2.2 SC 4.1.2 · 1.1.1 · WAI-ARIA 1.2",
+    message:
+      "Icon-only <Button size=\"icon\"> needs an accessible name — add aria-label={t('…')}. The icon is decorative (aria-hidden); the name comes from the author, not the glyph.",
+  },
+  {
+    id: "img-needs-alt",
+    severity: "warn",
+    test: /<img\b(?![^>]*\balt=)[^>]*>/,
+    standard: "WCAG 2.2 SC 1.1.1 · HTML Living Standard (WHATWG)",
+    message:
+      'Every <img> needs an alt attribute (alt="" for purely decorative images). Prefer the <Avatar>/<AspectRatio> primitives for product imagery.',
+  },
+  {
+    id: "no-positive-tabindex",
+    severity: "warn",
+    test: /tab[Ii]ndex=(?:["']?[1-9]|\{[1-9])/,
+    standard: "WCAG 2.2 SC 2.4.3 · WAI-ARIA APG",
+    message:
+      "No positive tabIndex — it breaks the natural focus order. Use tabIndex={0} (focusable) or {-1} (programmatic) only; manage roving focus via the primitive.",
+  },
+  {
+    id: "hardcoded-currency",
+    severity: "warn",
+    // A currency glyph glued to an interpolation in JSX text: `>¥{amount}` / `>{x}円`.
+    test: /(?:>[\s]*[¥$€£₫]\s*\{)|(?:\}\s*円)/,
+    standard: "ISO 4217 · ECMA-402 Intl.NumberFormat",
+    message:
+      "Don't hand-format currency (¥{amount}). Use Intl.NumberFormat(locale, { style: 'currency', currency }) — ISO 4217 code drives the symbol and minor units per locale.",
+  },
+  {
+    id: "raw-intl-date",
+    severity: "warn",
+    test: /\.toLocale(?:Date|Time)?String\(\s*\)|new Date\([^)]*\)\.(?:getMonth|getDate|getFullYear)\(\)\s*\+/,
+    standard: "ISO 8601 · IANA tz database · ECMA-402 Intl.DateTimeFormat",
+    message:
+      "Don't hand-build or locale-default dates. Use formatDate from @godxjp/ui/datetime (Intl.DateTimeFormat + IANA timezone + ISO-8601), which respects the AppProvider locale/timezone.",
+  },
+  {
+    id: "hand-rolled-close-glyph",
+    severity: "warn",
+    // A literal close glyph as JSX text — almost always a hand-rolled dismiss that should be a slot.
+    test: />\s*[✕✖×╳]\s*</,
+    standard: "WAI-ARIA 1.2 (dialog) · WCAG 2.2 SC 4.1.2 · @godxjp/ui Alert/Dialog anatomy",
+    message:
+      "Don't hand-roll a ✕ close. Pass onDismiss to <Alert> (renders the × top-right with an aria-label), or use <Dialog>/<Sheet> which ship their own labelled close. A bare glyph has no accessible name.",
+  },
+  {
+    id: "no-em-dash-in-copy",
+    severity: "warn",
+    // Em-dash (U+2014) in JSX text — dxs-kintai uses the middot `·` for JP/EN pairs and calm copy.
+    test: /[A-Za-z0-9぀-ヿ一-鿿]\s*—\s*[A-Za-z0-9぀-ヿ一-鿿]/,
+    standard: "@godxjp/ui dxs-kintai typography (best-ux) · Unicode punctuation",
+    message:
+      "No em-dash (—) in product copy. Use a middot `·` for JP/EN label pairs, or restructure into two calm sentences. Keep copy factual and quiet.",
+  },
 ];
 
+/**
+ * `--rules` — print the full rule catalog (id · severity · standard · message) as JSON and exit.
+ * The single source of truth other tooling (the MCP `list_audit_rules`, the sync guard) reads,
+ * 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",
+  );
+  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
@@ -242,6 +368,15 @@ function isSuppressed(ruleId, sameLine, prevLine) {
 }
 
 function walk(dir, acc = []) {
+  // Accept a FILE path directly (the per-file editor hook passes one), not just a directory.
+  try {
+    if (statSync(dir).isFile()) {
+      if (dir.endsWith(".tsx") || dir.endsWith(".ts")) acc.push(dir);
+      return acc;
+    }
+  } catch {
+    return acc;
+  }
   let entries;
   try {
     entries = readdirSync(dir);
@@ -266,9 +401,17 @@ function walk(dir, acc = []) {
 const CARD_FLUSH =
   /<Card(?![^>]*\bp-0\b)(?:\s[^>]*)?>\s*<(?!CardContent|CardHeader|CardCover|CardFooter|\/Card)/g;
 
+// Structural: a bare <label>/<Label> paired with a TEXT control (its sibling) instead of a
+// <FormField>. FormField OWNS the label↔control association (htmlFor/id), aria-describedby/
+// error wiring, AND the field rhythm (label gap + field spacing) — a hand-rolled Label+Input
+// loses all of it (the cramped login-form failure mode). Checkbox/Radio/Switch use Field/Label
+// legitimately, so they are NOT matched. Whole-file pass (the pair spans lines).
+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;
+
 const findings = [];
 for (const dir of SCAN_DIRS) {
-  for (const file of walk(join(CWD, dir))) {
+  for (const file of walk(isAbsolute(dir) ? dir : join(CWD, dir))) {
     const rel = relative(CWD, file);
     const content = readFileSync(file, "utf8");
     const origLines = content.split("\n");
@@ -282,6 +425,7 @@ for (const dir of SCAN_DIRS) {
             line: i + 1,
             rule: rule.id,
             severity: rule.severity,
+            standard: rule.standard,
             message: rule.message,
             snippet: (origLines[i] ?? line).trim().slice(0, 120),
           });
@@ -302,6 +446,23 @@ for (const dir of SCAN_DIRS) {
         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 (
+        isSuppressed("bare-control-needs-formfield", origLines[lineNo - 1], origLines[lineNo - 2])
+      )
+        continue;
+      findings.push({
+        file: rel,
+        line: lineNo,
+        rule: "bare-control-needs-formfield",
+        severity: "warn",
+        standard: "WCAG 2.2 SC 1.3.1 · 3.3.2 · @godxjp/ui FormField (cardinal rule 227)",
+        message:
+          "A bare <Label>/<label> paired with a control — wrap the field in <FormField label=…>. FormField owns the label↔control id wiring, aria-describedby/error, AND the field rhythm (label gap + field spacing); a hand-rolled Label+Input loses all of it (the cramped/mis-spaced form).",
+        snippet: match[0].replace(/\s+/g, " ").slice(0, 120),
+      });
+    }
   }
 }
 
@@ -329,6 +490,7 @@ if (asJson) {
     const tag = f.severity === "error" ? `${C.red}error${C.reset}` : `${C.yellow}warn ${C.reset}`;
     console.log(`${tag} ${C.bold}${f.file}:${f.line}${C.reset}  ${C.dim}[${f.rule}]${C.reset}`);
     console.log(`      ${f.message}`);
+    if (f.standard) console.log(`      ${C.dim}standard: ${f.standard}${C.reset}`);
     console.log(`      ${C.dim}${f.snippet}${C.reset}`);
   }
   console.log(

package/scripts/visual-audit-rules.mjs

@@ -0,0 +1,119 @@
+/**
+ * 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.
+ */
+
+/** Catalog (agent-facing mirror lives in mcp/src/data/visual-rules.ts; kept in sync by a guard). */
+export const VISUAL_RULES = [
+  {
+    id: "axe-violations",
+    severity: "warn",
+    category: "a11y",
+    standard: "WCAG 2.2 A/AA · WAI-ARIA 1.2 (axe-core engine)",
+    fix: "Fix each axe violation at its node — contrast (1.4.3), name/role/value (4.1.2), ARIA, landmarks. axe runs on the REAL DOM, catching what static analysis cannot.",
+  },
+  {
+    id: "target-size-min",
+    severity: "warn",
+    category: "a11y",
+    standard: "WCAG 2.2 SC 2.5.8 (24×24 AA) · 2.5.5 (44×44 AAA)",
+    fix: "Interactive targets must be ≥24×24 CSS px. Size controls from the --control-height tier; don't shrink icon buttons below it.",
+  },
+  {
+    id: "oversaturated-accent",
+    severity: "warn",
+    category: "color",
+    standard: "@godxjp/ui dxs-kintai 渋み (OKLCH chroma ≤ 0.18)",
+    fix: "Desaturate brand/primary surfaces — keep OKLCH chroma ≤ 0.18. Read --primary tokens; never paint a full-width bar in raw vivid blue.",
+  },
+  {
+    id: "emoji-rendered",
+    severity: "warn",
+    category: "i18n",
+    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: "alert-controls-misplaced",
+    severity: "warn",
+    category: "layout",
+    standard: "@godxjp/ui Alert anatomy · WAI-ARIA 1.2 · WCAG 2.2 SC 4.1.2",
+    fix: "Use <Alert>: ONE leading tone icon, <Alert.Actions> normal-width trailing-right, onDismiss × top-right, ONE horizontal row — never a vertical stack with a full-width action bar or a centered ✕.",
+  },
+];
+
+/** sRGB channel (0–255) → linear-light component. */
+function srgbToLinear(c) {
+  const x = c / 255;
+  return x <= 0.04045 ? x / 12.92 : Math.pow((x + 0.055) / 1.055, 2.4);
+}
+
+/**
+ * OKLCH chroma of an sRGB color — the perceptual saturation the 渋み rule bounds.
+ * sRGB → linear → OKLab (Björn Ottosson) → chroma = hypot(a, b).
+ * @param {{r:number,g:number,b:number}} rgb 0–255 channels
+ * @returns {number} OKLCH chroma (~0 grey … ~0.37 max sRGB)
+ */
+export function oklchChroma({ r, g, b }) {
+  const lr = srgbToLinear(r);
+  const lg = srgbToLinear(g);
+  const lb = srgbToLinear(b);
+  const l = 0.4122214708 * lr + 0.5363325363 * lg + 0.0514459929 * lb;
+  const m = 0.2119034982 * lr + 0.6806995451 * lg + 0.1073969566 * lb;
+  const s = 0.0883024619 * lr + 0.2817188376 * lg + 0.6299787005 * lb;
+  const l_ = Math.cbrt(l);
+  const m_ = Math.cbrt(m);
+  const s_ = Math.cbrt(s);
+  const oa = 1.9779984951 * l_ - 2.428592205 * m_ + 0.4505937099 * s_;
+  const ob = 0.0259040371 * l_ + 0.7827717662 * m_ - 0.808675766 * s_;
+  return Math.hypot(oa, ob);
+}
+
+/** dxs-kintai restraint bound. A signal/brand surface above this chroma "screams". */
+export const CHROMA_LIMIT = 0.18;
+
+/** @returns {boolean} true when an accent surface exceeds the 渋み chroma limit. */
+export function isOversaturated(rgb, limit = CHROMA_LIMIT) {
+  return oklchChroma(rgb) > limit;
+}
+
+/** WCAG 2.2 SC 2.5.8 — a tappable target smaller than 24×24 CSS px. */
+export function isUndersizedTarget({ width, height }, min = 24) {
+  return width > 0 && height > 0 && (width < min || height < min);
+}
+
+/** Unicode UTS #51 — any emoji pictograph in rendered text (excludes · — × ✓). */
+const EMOJI_RE = /\p{Extended_Pictographic}/u;
+export function hasEmoji(text) {
+  return typeof text === "string" && EMOJI_RE.test(text);
+}
+
+/**
+ * Alert/banner anatomy — given measurements of a notification region, list the
+ * structural mistakes (the "stacked notification banner" tell).
+ *
+ * @param {{iconCount:number, actionWidthRatio:number, direction:'row'|'column',
+ *          hasDismiss:boolean, dismissCorner:'top-right'|'other'|null}} m
+ * @returns {string[]} human-readable issues (empty = correct anatomy)
+ */
+export function alertControlIssues(m) {
+  const issues = [];
+  if (m.iconCount > 1) issues.push("multiple icons — Alert takes ONE leading tone icon");
+  if (m.actionWidthRatio > 0.85)
+    issues.push("action is a full-width bar — use a normal-width Button in <Alert.Actions>");
+  if (m.direction === "column")
+    issues.push("controls stacked vertically — Alert is ONE horizontal row");
+  if (m.hasDismiss && m.dismissCorner !== "top-right")
+    issues.push("dismiss ✕ not in the top-right corner — pass onDismiss to <Alert>");
+  return issues;
+}
+
+export function findVisualRule(id) {
+  return VISUAL_RULES.find((r) => r.id === id);
+}

package/scripts/visual-audit.mjs

@@ -0,0 +1,261 @@
+#!/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.
+ *
+ * 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 --format json http://localhost:5173
+ *   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
+ */
+import {
+  VISUAL_RULES,
+  isOversaturated,
+  oklchChroma,
+  isUndersizedTarget,
+  hasEmoji,
+  alertControlIssues,
+} from "./visual-audit-rules.mjs";
+
+const args = process.argv.slice(2);
+const asJson = args.includes("--format") && args[args.indexOf("--format") + 1] === "json";
+const strict = args.includes("--strict");
+const listRules = args.includes("--rules");
+
+if (listRules) {
+  process.stdout.write(JSON.stringify(VISUAL_RULES, null, 2) + "\n");
+  process.exit(0);
+}
+
+const C = {
+  red: "\x1b[31m",
+  yellow: "\x1b[33m",
+  dim: "\x1b[2m",
+  bold: "\x1b[1m",
+  reset: "\x1b[0m",
+};
+
+const urls = args.filter((a, i) => !a.startsWith("--") && args[i - 1] !== "--format");
+if (urls.length === 0) {
+  console.error(
+    "usage: visual-audit.mjs [--format json] [--strict] <baseUrl> [route …]\n" +
+      "       (baseUrl is the running app; extra args are routes appended to it)",
+  );
+  process.exit(2);
+}
+const base = urls[0].replace(/\/$/, "");
+const routes = urls.length > 1 ? urls.slice(1) : ["/"];
+const targets = routes.map((r) =>
+  r.startsWith("http") ? r : `${base}${r.startsWith("/") ? r : `/${r}`}`,
+);
+
+/** Optional-peer loader — print a clear install hint instead of a stack trace. */
+async function loadDeps() {
+  try {
+    const [{ chromium }, axe] = await Promise.all([
+      import("playwright"),
+      import("@axe-core/playwright"),
+    ]);
+    return { chromium, AxeBuilder: axe.default ?? axe.AxeBuilder };
+  } catch {
+    console.error(
+      "visual-audit needs the optional peers `playwright` and `@axe-core/playwright`:\n" +
+        "  pnpm add -D playwright @axe-core/playwright\n" +
+        "  pnpm exec playwright install chromium\n" +
+        "(or set PLAYWRIGHT_CHROMIUM_EXECUTABLE to a system Chromium).",
+    );
+    process.exit(2);
+  }
+}
+
+/** Collect raw measurements from the rendered page; the PURE rules run back in node. */
+/* c8 ignore start — runs inside the browser, exercised in the consumer/CI env. */
+function collectInPage() {
+  const rgb = (s) => {
+    const m = s && s.match(/rgba?\(([^)]+)\)/);
+    if (!m) return null;
+    const [r, g, b, a = "1"] = m[1].split(",").map((x) => x.trim());
+    return { r: +r, g: +g, b: +b, a: +a };
+  };
+  const visible = (el) => {
+    const r = el.getBoundingClientRect();
+    const cs = getComputedStyle(el);
+    return r.width > 0 && r.height > 0 && cs.visibility !== "hidden" && cs.display !== "none";
+  };
+
+  // Accent surfaces — buttons / primary CTAs / banners whose background carries colour.
+  const accents = [];
+  for (const el of document.querySelectorAll(
+    "button, [role=button], a[class*=primary], [data-slot=alert], [class*=banner], [class*=notification]",
+  )) {
+    if (!visible(el)) continue;
+    const c = rgb(getComputedStyle(el).backgroundColor);
+    if (c && c.a > 0.5)
+      accents.push({ rgb: { r: c.r, g: c.g, b: c.b }, tag: el.tagName.toLowerCase() });
+  }
+
+  // Interactive targets — for the 24×24 minimum.
+  const targets = [];
+  for (const el of document.querySelectorAll(
+    "a[href], button, [role=button], input:not([type=hidden]), select, [tabindex]:not([tabindex='-1'])",
+  )) {
+    if (!visible(el)) continue;
+    const r = el.getBoundingClientRect();
+    const name = (el.getAttribute("aria-label") || el.textContent || "").trim().slice(0, 40);
+    targets.push({ width: Math.round(r.width), height: Math.round(r.height), name });
+  }
+
+  // Emoji that survived to the rendered DOM.
+  const text = document.body ? document.body.innerText : "";
+
+  // Notification banners — measure their anatomy.
+  const alerts = [];
+  for (const el of document.querySelectorAll(
+    "[role=alert], [role=status], [data-slot=alert], [class*=banner], [class*=notification]",
+  )) {
+    if (!visible(el)) continue;
+    const box = el.getBoundingClientRect();
+    const icons = el.querySelectorAll("svg, img").length;
+    const btns = [...el.querySelectorAll("button, [role=button], a[href]")];
+    const actionWidthRatio = btns.length
+      ? Math.max(...btns.map((b) => b.getBoundingClientRect().width)) / (box.width || 1)
+      : 0;
+    const cs = getComputedStyle(el);
+    const direction =
+      cs.display.includes("flex") && cs.flexDirection.startsWith("column")
+        ? "column"
+        : cs.display.includes("flex")
+          ? "row"
+          : "column";
+    const dismiss = btns.find((b) =>
+      /close|dismiss|閉じる|×|✕/i.test(b.getAttribute("aria-label") || b.textContent || ""),
+    );
+    let dismissCorner = null;
+    if (dismiss) {
+      const d = dismiss.getBoundingClientRect();
+      const nearTop = d.top - box.top < box.height * 0.4;
+      const nearRight = box.right - d.right < box.width * 0.25;
+      dismissCorner = nearTop && nearRight ? "top-right" : "other";
+    }
+    alerts.push({
+      iconCount: icons,
+      actionWidthRatio,
+      direction,
+      hasDismiss: !!dismiss,
+      dismissCorner,
+    });
+  }
+
+  return { accents, targets, text, alerts };
+}
+/* c8 ignore stop */
+
+async function run() {
+  const { chromium, AxeBuilder } = await loadDeps();
+  const browser = await chromium.launch({
+    executablePath: process.env.PLAYWRIGHT_CHROMIUM_EXECUTABLE || undefined,
+  });
+  const page = await browser.newPage({ viewport: { width: 1280, height: 900 } });
+  const findings = [];
+  const add = (ruleId, url, message) => {
+    const rule = VISUAL_RULES.find((r) => r.id === ruleId);
+    findings.push({
+      url,
+      rule: ruleId,
+      severity: rule?.severity ?? "warn",
+      standard: rule?.standard,
+      message,
+    });
+  };
+
+  for (const url of targets) {
+    try {
+      await page.goto(url, { waitUntil: "networkidle", timeout: 30_000 });
+    } catch (e) {
+      add("axe-violations", url, `could not load page: ${e.message}`);
+      continue;
+    }
+
+    // 1) axe-core — real WCAG/ARIA engine.
+    const { violations } = await new AxeBuilder({ page }).analyze();
+    for (const v of violations) {
+      add(
+        "axe-violations",
+        url,
+        `${v.id} (${v.impact}) — ${v.help} [${v.nodes.length} node(s)] ${v.helpUrl}`,
+      );
+    }
+
+    // 2) computed-style / layout heuristics via the PURE rules.
+    const m = await page.evaluate(collectInPage);
+    for (const a of m.accents) {
+      if (isOversaturated(a.rgb))
+        add(
+          "oversaturated-accent",
+          url,
+          `<${a.tag}> background OKLCH chroma ${oklchChroma(a.rgb).toFixed(3)} > 0.18 (rgb ${a.rgb.r},${a.rgb.g},${a.rgb.b})`,
+        );
+    }
+    for (const t of m.targets) {
+      if (isUndersizedTarget(t))
+        add(
+          "target-size-min",
+          url,
+          `target "${t.name || "(unnamed)"}" is ${t.width}×${t.height}px (< 24×24)`,
+        );
+    }
+    if (hasEmoji(m.text)) {
+      const found = (m.text.match(/\p{Extended_Pictographic}/gu) || []).slice(0, 8).join(" ");
+      add("emoji-rendered", url, `emoji rendered in product text: ${found}`);
+    }
+    m.alerts.forEach((al, i) => {
+      for (const issue of alertControlIssues(al))
+        add("alert-controls-misplaced", url, `banner #${i + 1}: ${issue}`);
+    });
+  }
+
+  await browser.close();
+  report(findings);
+}
+
+function report(findings) {
+  const errors = findings.filter((f) => f.severity === "error");
+  const warnings = findings.filter((f) => f.severity === "warn");
+  if (asJson) {
+    process.stdout.write(
+      JSON.stringify(
+        { summary: { errors: errors.length, warnings: warnings.length }, findings },
+        null,
+        2,
+      ) + "\n",
+    );
+  } else {
+    for (const f of findings) {
+      const tag = f.severity === "error" ? `${C.red}error${C.reset}` : `${C.yellow}warn ${C.reset}`;
+      console.log(`${tag} ${C.bold}${f.url}${C.reset}  ${C.dim}[${f.rule}]${C.reset}`);
+      console.log(`      ${f.message}`);
+      if (f.standard) console.log(`      ${C.dim}standard: ${f.standard}${C.reset}`);
+    }
+    console.log(
+      `\ngodxjp-ui visual-audit: ${C.red}${errors.length} error(s)${C.reset}, ${C.yellow}${warnings.length} warning(s)${C.reset} across ${targets.length} page(s).`,
+    );
+    if (findings.length === 0) console.log("✓ No visual/runtime a11y violations found.");
+  }
+  // Warnings never block; --strict turns any finding into a non-zero exit (CI gate).
+  process.exit(strict && findings.length > 0 ? 1 : errors.length > 0 ? 1 : 0);
+}
+
+run().catch((e) => {
+  console.error(`visual-audit failed: ${e.message}`);
+  process.exit(2);
+});