@godxjp/ui 13.17.4 → 14.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@godxjp/ui",
-  "version": "13.17.4",
+  "version": "14.0.0",
   "type": "module",
   "packageManager": "pnpm@10.29.1",
   "sideEffects": false,
@@ -8,7 +8,14 @@
   "files": [
     "dist",
     "scripts/ui-audit.mjs",
-    "README.md"
+    "README.md",
+    "scripts/visual-audit.mjs",
+    "scripts/visual-audit-rules.mjs",
+    "scripts/audit-hook.mjs",
+    "scripts/init-agent-kit.mjs",
+    "scripts/postinstall.mjs",
+    "scripts/_agent-setup.mjs",
+    "scripts/cli.mjs"
   ],
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -51,6 +58,10 @@
       "types": "./dist/components/data-grid/index.d.ts",
       "import": "./dist/components/data-grid/index.js"
     },
+    "./charts": {
+      "types": "./dist/components/charts/index.d.ts",
+      "import": "./dist/components/charts/index.js"
+    },
     "./ui": {
       "types": "./dist/components/ui/index.d.ts",
       "import": "./dist/components/ui/index.js"
@@ -266,8 +277,8 @@
     "test:watch": "vitest",
     "test:coverage": "vitest run --coverage",
     "check:example-imports": "node scripts/check-example-imports.mjs",
-    "verify": "pnpm typecheck && pnpm lint && pnpm format && pnpm build && pnpm preview:build && pnpm check:example-imports && pnpm check:core-isolation && pnpm check:prop-vocabulary && pnpm check:token-tiers && pnpm check:control-sizing && pnpm check:rtl && pnpm check:typography && pnpm check:mcp-token-sync && pnpm check:mcp-sync && pnpm check:mcp-orphans && pnpm test",
-    "verify:release": "pnpm typecheck && pnpm lint && pnpm build && pnpm preview:build && pnpm check:example-imports && pnpm check:core-isolation && pnpm check:prop-vocabulary && pnpm check:token-tiers && pnpm check:control-sizing && pnpm check:rtl && pnpm check:typography && pnpm check:mcp-token-sync && pnpm check:mcp-sync && pnpm check:mcp-orphans && pnpm check:mcp-prop-sync && pnpm test",
+    "verify": "pnpm typecheck && pnpm lint && pnpm format && pnpm build && pnpm preview:build && pnpm check:example-imports && pnpm check:core-isolation && pnpm check:prop-vocabulary && pnpm check:token-tiers && pnpm check:control-sizing && pnpm check:rtl && pnpm check:typography && pnpm check:mcp-token-sync && pnpm check:mcp-sync && pnpm check:mcp-orphans && pnpm check:audit-sync && pnpm test",
+    "verify:release": "pnpm typecheck && pnpm lint && pnpm build && pnpm preview:build && pnpm check:example-imports && pnpm check:core-isolation && pnpm check:prop-vocabulary && pnpm check:token-tiers && pnpm check:control-sizing && pnpm check:rtl && pnpm check:typography && pnpm check:mcp-token-sync && pnpm check:mcp-sync && pnpm check:mcp-orphans && pnpm check:audit-sync && pnpm check:mcp-prop-sync && pnpm test",
     "check:mcp-sync": "node scripts/check-mcp-sync.mjs",
     "check:mcp-orphans": "node scripts/check-mcp-orphans.mjs",
     "check:mcp-prop-sync": "node scripts/check-mcp-prop-sync.mjs",
@@ -286,7 +297,11 @@
     "audit": "node scripts/ui-audit.mjs",
     "build": "tsup && tsc -p tsconfig.build.json && node scripts/copy-styles.mjs",
     "dev": "node scripts/dev.mjs",
-    "prepublishOnly": "pnpm run build"
+    "prepublishOnly": "pnpm run build",
+    "check:audit-sync": "node scripts/check-audit-sync.mjs",
+    "visual-audit": "node scripts/visual-audit.mjs",
+    "postinstall": "node scripts/postinstall.mjs",
+    "init-agent": "node scripts/init-agent-kit.mjs"
   },
   "peerDependencies": {
     "@hookform/resolvers": "^5.2.0",
@@ -296,12 +311,28 @@
     "react-dom": ">=19.0.0",
     "react-hook-form": "^7.76.0",
     "react-router-dom": ">=7.0.0",
+    "recharts": "^2.13.0 || ^3.0.0",
     "tailwindcss": ">=4.0.0",
-    "zod": "^4.4.0"
+    "zod": "^4.4.0",
+    "playwright": "*",
+    "@axe-core/playwright": "*",
+    "axe-core": "*"
   },
   "peerDependenciesMeta": {
     "@tanstack/react-table": {
       "optional": true
+    },
+    "recharts": {
+      "optional": true
+    },
+    "playwright": {
+      "optional": true
+    },
+    "@axe-core/playwright": {
+      "optional": true
+    },
+    "axe-core": {
+      "optional": true
     }
   },
   "dependencies": {
@@ -348,6 +379,7 @@
     "vaul": "^1.1.2"
   },
   "devDependencies": {
+    "@axe-core/playwright": "^4.12.1",
     "@eslint/js": "^9.39.4",
     "@hookform/resolvers": "^5.2.2",
     "@tailwindcss/vite": "^4.2.4",
@@ -361,17 +393,20 @@
     "@types/react-dom": "^19.2.3",
     "@vitejs/plugin-react": "^6.0.1",
     "@vitest/coverage-v8": "^4.1.5",
+    "axe-core": "^4.12.1",
     "eslint": "^9.39.2",
     "eslint-plugin-react": "^7.37.5",
     "eslint-plugin-react-hooks": "^7.1.1",
     "globals": "^15.15.0",
     "jsdom": "^29.1.1",
+    "playwright": "^1.61.1",
     "prettier": "^3.6.2",
     "prettier-plugin-tailwindcss": "^0.6.14",
     "react": "^19.2.6",
     "react-dom": "^19.2.6",
     "react-hook-form": "^7.76.0",
     "react-router-dom": "^7.15.0",
+    "recharts": "^3.8.1",
     "tailwindcss": "^4.2.4",
     "tsup": "^8.5.1",
     "typescript": "^6.0.3",
@@ -382,7 +417,7 @@
     "zod": "^4.4.3"
   },
   "bin": {
-    "godxjp-ui-audit": "scripts/ui-audit.mjs"
+    "godxjp-ui": "scripts/cli.mjs"
   },
   "module": "./dist/index.js"
 }

package/scripts/_agent-setup.mjs

@@ -0,0 +1,145 @@
+/**
+ * Shared agent-setup helpers — used by both postinstall.mjs (auto, on install) and
+ * init-agent-kit.mjs (explicit, full kit). Every writer is IDEMPOTENT and
+ * NON-DESTRUCTIVE: it only creates a missing file or ADDS a missing key, never
+ * overwrites existing config.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+
+/** The godxjp-ui MCP server — pulled on demand via npx (no extra dependency to ship). */
+export const MCP_SERVER = { command: "npx", args: ["@godxjp/ui-mcp"] };
+export const MCP_KEY = "godx-ui";
+
+/** Commands wired into the consumer's .claude/settings.json. */
+export const AUDIT_HOOK_CMD = "node node_modules/@godxjp/ui/scripts/audit-hook.mjs";
+export const PRIMER_CMD = "cat .claude/godxjp-ui-workflow.md";
+
+/** The per-session workflow mandate the SessionStart hook injects into the agent. */
+export const WORKFLOW_MD = `# @godxjp/ui — mandatory workflow (read every session)
+
+You are building UI in an app that uses @godxjp/ui. Follow this EVERY time you create
+or change a component, page, or form — no exceptions.
+
+## Before writing UI
+1. **MCP-first.** Consult the godx-ui MCP: \`get_component <Name>\`, \`search_components\`,
+   \`list_audit_rules\`, \`list_visual_checks\`. Never guess a prop; never hand-roll what a
+   primitive already does.
+2. **Real primitives only.** No raw \`<input>/<select>/<button>/<textarea>/<table>\`, no
+   styled-div fakes. A labelled control ALWAYS goes in \`<FormField label=…>\` (it owns the
+   label↔control wiring, error/aria, AND the field rhythm). Never pair a bare \`<Label>\`
+   with an \`<Input>\`.
+3. **Tokens, not literals.** Semantic colour tokens (bg-primary, text-muted-foreground),
+   token spacing/size/radius/type — no raw palette (bg-blue-600), no hex, no arbitrary
+   \`[13px]\`. No emoji in product UI. Logical CSS (ms-/me-/ps-/pe-) for RTL.
+
+## After writing UI
+4. **Audit (runs automatically too).** \`node node_modules/@godxjp/ui/scripts/ui-audit.mjs\`
+   — fix every finding. A PostToolUse hook also runs it on each edit and feeds findings back.
+5. **Before a visual review**, run the runtime audit against the running app:
+   \`node node_modules/@godxjp/ui/scripts/visual-audit.mjs <url>\` (axe + contrast + layout).
+`;
+
+/** Delimited block appended to the consumer's CLAUDE.md — loaded into the agent's context
+ * every turn (the most reliable "ensure it reads the rules"). Markers keep it idempotent. */
+export const CLAUDE_MD_BLOCK = `<!-- godxjp-ui:start (managed by @godxjp/ui — edit .claude/godxjp-ui-workflow.md instead) -->
+## @godxjp/ui — mandatory UI workflow (do NOT skip)
+
+This app uses @godxjp/ui. EVERY time you build or change UI:
+
+1. **MCP-first.** Consult the \`godx-ui\` MCP — \`get_component\`, \`search_components\`,
+   \`list_audit_rules\`, \`list_visual_checks\`. Never guess a prop; never hand-roll what a
+   primitive already does.
+2. **Real primitives only.** No raw \`<input>/<select>/<button>/<textarea>/<table>\`. A labelled
+   control ALWAYS goes in \`<FormField label=…>\` — never a bare \`<Label>\`+\`<Input>\`. Semantic
+   tokens, not raw palette/hex/arbitrary values. No emoji in product UI. Logical CSS for RTL.
+3. **Scan after writing.** \`node node_modules/@godxjp/ui/scripts/ui-audit.mjs <files>\` and fix
+   every finding (a PostToolUse hook runs this automatically and feeds findings back). Before a
+   visual review: \`node node_modules/@godxjp/ui/scripts/visual-audit.mjs <url>\` (axe + layout).
+
+Full guide: \`.claude/godxjp-ui-workflow.md\`.
+<!-- godxjp-ui:end -->
+`;
+
+function readJson(path) {
+  try {
+    return JSON.parse(readFileSync(path, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+/** Ensure `.mcp.json` registers the godx-ui MCP server. Returns 'created' | 'added' | 'present'. */
+export function ensureMcpJson(root) {
+  const path = join(root, ".mcp.json");
+  const json = readJson(path) ?? {};
+  json.mcpServers = json.mcpServers ?? {};
+  if (json.mcpServers[MCP_KEY]) return "present";
+  const created = !existsSync(path);
+  json.mcpServers[MCP_KEY] = MCP_SERVER;
+  writeFileSync(path, JSON.stringify(json, null, 2) + "\n");
+  return created ? "created" : "added";
+}
+
+/** Ensure `.claude/settings.json` has the audit PostToolUse + workflow SessionStart hooks. */
+export function ensureClaudeHooks(root) {
+  const path = join(root, ".claude", "settings.json");
+  mkdirSync(dirname(path), { recursive: true });
+  const json = readJson(path) ?? {};
+  json.hooks = json.hooks ?? {};
+  const added = [];
+
+  const has = (arr, cmd) =>
+    (arr ?? []).some((g) => (g.hooks ?? []).some((h) => (h.command ?? "").includes(cmd)));
+
+  json.hooks.PostToolUse = json.hooks.PostToolUse ?? [];
+  if (!has(json.hooks.PostToolUse, "audit-hook.mjs")) {
+    json.hooks.PostToolUse.push({
+      matcher: "Write|Edit|MultiEdit",
+      hooks: [{ type: "command", command: AUDIT_HOOK_CMD }],
+    });
+    added.push("PostToolUse:auto-audit");
+  }
+
+  json.hooks.SessionStart = json.hooks.SessionStart ?? [];
+  if (!has(json.hooks.SessionStart, "godxjp-ui-workflow.md")) {
+    json.hooks.SessionStart.push({ hooks: [{ type: "command", command: PRIMER_CMD }] });
+    added.push("SessionStart:workflow-primer");
+  }
+
+  writeFileSync(path, JSON.stringify(json, null, 2) + "\n");
+  return added;
+}
+
+/** Write the workflow mandate the SessionStart hook reads (only if absent). */
+export function writeWorkflowMd(root) {
+  const path = join(root, ".claude", "godxjp-ui-workflow.md");
+  mkdirSync(dirname(path), { recursive: true });
+  if (existsSync(path)) return false;
+  writeFileSync(path, WORKFLOW_MD);
+  return true;
+}
+
+/** Append the godxjp-ui mandate to the consumer's CLAUDE.md (created if absent). Idempotent
+ * via the markers. Returns 'created' | 'appended' | 'present'. */
+export function ensureClaudeMd(root) {
+  const path = join(root, "CLAUDE.md");
+  const existing = existsSync(path) ? readFileSync(path, "utf8") : null;
+  if (existing?.includes("godxjp-ui:start")) return "present";
+  if (existing == null) {
+    writeFileSync(path, CLAUDE_MD_BLOCK);
+    return "created";
+  }
+  writeFileSync(path, existing.replace(/\s*$/, "") + "\n\n" + CLAUDE_MD_BLOCK);
+  return "appended";
+}
+
+/** True when setup should be SKIPPED (CI, opted out, or installing the library itself). */
+export function shouldSkip(root) {
+  if (process.env.CI || process.env.GODXJP_UI_SKIP_SETUP) return "ci-or-optout";
+  if (!root) return "no-consumer";
+  const pkg = readJson(join(root, "package.json"));
+  if (!pkg) return "no-package";
+  if (pkg.name === "@godxjp/ui" || pkg.name === "@godxjp/ui-mcp") return "self";
+  return null;
+}

package/scripts/audit-hook.mjs

@@ -0,0 +1,66 @@
+#!/usr/bin/env node
+/**
+ * Claude Code PostToolUse hook — the FORCING FUNCTION.
+ *
+ * Wired by `init-agent-kit.mjs` into a consumer's `.claude/settings.json` so that
+ * after EVERY Write/Edit/MultiEdit of a .tsx/.ts file, the godxjp-ui static audit
+ * runs on that file and its findings are fed straight back to the agent. The agent
+ * cannot skip it — the harness runs the hook, not the agent's goodwill — so a
+ * hand-rolled <label>+<Input>, a raw <button>, a loud palette colour, or an emoji
+ * is surfaced the instant it is written, and the agent self-corrects.
+ *
+ * Contract: reads the hook JSON on stdin ({ tool_input: { file_path } }). Prints
+ * findings to stderr and exits 2 when any are found (Claude Code feeds stderr back
+ * to the model); exits 0 (silent) when the file is clean or irrelevant. Non-fatal —
+ * it never blocks the edit, it just makes the agent SEE the issue.
+ */
+import { execFileSync } from "node:child_process";
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const AUDIT = join(HERE, "ui-audit.mjs");
+
+function readStdin() {
+  try {
+    return JSON.parse(readFileSync(0, "utf8")); // fd 0 = the hook payload piped by Claude Code
+  } catch {
+    return null;
+  }
+}
+
+const payload = readStdin();
+const file = payload?.tool_input?.file_path ?? payload?.tool_input?.filePath;
+if (!file || !/\.(tsx|ts)$/.test(file) || /\.(test|stories|d)\.tsx?$/.test(file)) process.exit(0);
+
+// ui-audit exits 1 when it finds errors — execFileSync throws, but the JSON is still on
+// e.stdout. Capture it either way; only a truly broken run (no stdout) is ignored.
+let out;
+try {
+  out = execFileSync("node", [AUDIT, "--format", "json", file], { encoding: "utf8" });
+} catch (e) {
+  out = e.stdout?.toString();
+}
+let result;
+try {
+  result = JSON.parse(out);
+} catch {
+  process.exit(0); // never let an audit error break the edit flow
+}
+
+const findings = result.findings ?? [];
+if (findings.length === 0) process.exit(0);
+
+const lines = [
+  `godxjp-ui audit flagged ${findings.length} issue(s) in this file — fix before moving on:`,
+];
+for (const f of findings) {
+  lines.push(`  [${f.severity}] ${f.rule} (line ${f.line})${f.standard ? ` · ${f.standard}` : ""}`);
+  lines.push(`    ${f.message}`);
+}
+lines.push(
+  "Consult the godxjp-ui MCP (get_component / list_audit_rules) and use the real primitive — do not hand-roll.",
+);
+process.stderr.write(lines.join("\n") + "\n");
+process.exit(2); // exit 2 → Claude Code surfaces stderr to the agent

package/scripts/cli.mjs

@@ -0,0 +1,26 @@
+#!/usr/bin/env node
+/**
+ * @godxjp/ui CLI — `npx @godxjp/ui <command>`.
+ *   init-agent     scaffold the agent forcing-kit (MCP + auto-audit hook + mandate)
+ *   audit          static UI audit (regex over source)
+ *   visual-audit   runtime audit (Playwright + axe-core) against a running app
+ */
+import { spawnSync } from "node:child_process";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const MAP = {
+  "init-agent": "init-agent-kit.mjs",
+  audit: "ui-audit.mjs",
+  "visual-audit": "visual-audit.mjs",
+};
+
+const [cmd, ...rest] = process.argv.slice(2);
+const script = MAP[cmd];
+if (!script) {
+  console.error("usage: godxjp-ui <init-agent | audit | visual-audit> [args]");
+  process.exit(1);
+}
+const r = spawnSync("node", [join(HERE, script), ...rest], { stdio: "inherit" });
+process.exit(r.status ?? 0);

package/scripts/init-agent-kit.mjs

@@ -0,0 +1,52 @@
+#!/usr/bin/env node
+/**
+ * init-agent-kit — the FULL forcing-kit. Run once from a consumer app:
+ *   npx @godxjp/ui init-agent
+ *
+ * Scaffolds (idempotent, non-destructive) the harness-enforced workflow so an agent
+ * follows the whole godxjp-ui process every time it touches UI:
+ *   1. .mcp.json            — registers the godx-ui MCP (component + audit guidance)
+ *   2. .claude/settings.json — PostToolUse hook auto-runs the audit on every .tsx edit
+ *                              and feeds findings back; SessionStart injects the mandate
+ *   3. .claude/godxjp-ui-workflow.md — the per-session mandate the SessionStart hook reads
+ *
+ * Existing config is preserved (hooks are appended only if absent). It then prints the
+ * optional pre-commit / CI snippets.
+ */
+import {
+  ensureClaudeHooks,
+  ensureClaudeMd,
+  ensureMcpJson,
+  shouldSkip,
+  writeWorkflowMd,
+} from "./_agent-setup.mjs";
+
+const root = process.env.INIT_CWD || process.cwd();
+
+const skip = shouldSkip(root);
+if (skip === "self") {
+  console.error("init-agent is for CONSUMER apps, not the @godxjp/ui repo itself.");
+  process.exit(1);
+}
+
+const mcp = ensureMcpJson(root);
+const hooks = ensureClaudeHooks(root);
+const md = writeWorkflowMd(root);
+const claudeMd = ensureClaudeMd(root);
+
+console.log("\n  @godxjp/ui agent-kit installed:");
+console.log(`    • .mcp.json — godx-ui MCP (${mcp})`);
+console.log(
+  `    • .claude/settings.json — ${hooks.length ? hooks.join(", ") : "hooks already present"}`,
+);
+console.log(`    • .claude/godxjp-ui-workflow.md — ${md ? "created" : "already present"}`);
+console.log(`    • CLAUDE.md — godxjp-ui mandate (${claudeMd})`);
+console.log(`
+  The auto-audit hook now runs on every Write/Edit of a .tsx file and feeds findings
+  back to the agent — it cannot skip the audit. Restart your agent to load the MCP + hooks.
+
+  Optional hard gate (block bad UI from landing):
+    • pre-commit:  node node_modules/@godxjp/ui/scripts/ui-audit.mjs resources/js || exit 1
+    • CI step:     node node_modules/@godxjp/ui/scripts/ui-audit.mjs --quiet <your-ui-dirs>
+`);
+process.exit(0);

package/scripts/postinstall.mjs

@@ -0,0 +1,31 @@
+#!/usr/bin/env node
+/**
+ * postinstall — runs when a consumer installs @godxjp/ui. Auto-registers the godx-ui
+ * MCP server in the consumer's `.mcp.json` so the agent gets live access to the
+ * component catalog + audit rules WITHOUT any manual step. Non-destructive (only adds
+ * a missing server entry) and guarded so it never runs in CI or in the library's own repo.
+ *
+ * The heavier forcing-kit (the auto-audit PostToolUse hook + the workflow mandate) is
+ * left to an EXPLICIT `npx @godxjp/ui init-agent`, since hooks change the dev loop and
+ * should be opted into, not forced on install. Set GODXJP_UI_SKIP_SETUP=1 to disable.
+ */
+import { ensureMcpJson, shouldSkip } from "./_agent-setup.mjs";
+
+const root = process.env.INIT_CWD || process.cwd();
+
+const skip = shouldSkip(root);
+if (skip) process.exit(0); // silent: CI / opt-out / self-install / no consumer project
+
+try {
+  const r = ensureMcpJson(root);
+  if (r === "present") process.exit(0); // already configured — stay quiet
+  console.log(
+    `\n  @godxjp/ui → registered the godx-ui MCP in .mcp.json (${r}).\n` +
+      "  Your agent now has live component + audit guidance. Restart it to pick up the MCP.\n" +
+      "  For the full forcing-kit (auto-audit on every edit + workflow mandate):\n" +
+      "    npx @godxjp/ui init-agent\n",
+  );
+} catch {
+  // Never fail an install over optional setup.
+}
+process.exit(0);

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(