@godxjp/ui 22.0.0 → 23.1.0

package/docs/roadmap/parity-backlog.md

@@ -31,7 +31,7 @@ compared against, or successive waves will silently measure against different ta
 
 ## P1 — grouped by owning file, so one agent owns one group
 
-**`data-entry`** — `Slider` missing `aria-valuetext` (`slider.tsx:138-157`) · `SearchInput` Enter does
+**`data-entry`** — `SearchInput` Enter does
 not commit (no `onKeyDown` in the file; `:59-63`) · `ColorPicker` has no `size`/`status`/`variant`
 and no `presets` (`data-entry.prop.ts:893-908`) · `PasswordStrength` uses `role="img"` instead of
 `role="meter"` (`:74-76`) · `Upload showUploadList` boolean-only (`:1196`) ·
@@ -56,8 +56,7 @@ derives delta tone from a regex on a stringified node (`card.tsx:233-246`) · `Q
 `isDismissable`) · `Pagination` is controlled-only, breaking the full-triad rule · `AppShell` has no
 `onSidebarCollapsedChange` and no built-in trigger (`app-shell.tsx:30`) · shell collapse breakpoint
 hardcoded (`shell-layout.css:1119`) while the overlay family's equivalent is a token · `Sidebar`
-submenu open state is unreachable local state (`sidebar.tsx:271`) · `NavigationMenu` has no overflow
-affordance (WCAG 2.4.3 / 1.4.10) · no `copyable` anywhere despite `ErrorSurface` rendering a
+submenu open state is unreachable local state (`sidebar.tsx:271`) · no `copyable` anywhere despite `ErrorSurface` rendering a
 `requestId` "so it can be read out or copied accurately" (`layout.prop.ts:787`) · clamped text
 cannot expand.
 

package/docs/roadmap/tree-components.md

@@ -100,7 +100,6 @@ Plus the house rules: forward `ref`, spread `...props`, accept `className` + `id
   (`margin-inline-start`, `padding-inline-start`), never `ml-`/`pl-`/`left-`.
 - Tri-state parent checkbox: checked / unchecked / **indeterminate** when only some descendants
   are checked (skip propagation entirely when `checkStrictly`).
-- Ships `tree.a11y.test.tsx` with `expectNoA11yViolations` — 0 violations.
 
 ## 5. Tokens (tier: `src/tokens/components/tree.css`, `@import`ed from `src/tokens/base.css`)
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@godxjp/ui",
-  "version": "22.0.0",
-  "godxUiMcp": "22.0.0",
+  "version": "23.1.0",
+  "godxUiMcp": "23.1.0",
   "license": "Apache-2.0",
   "repository": {
     "type": "git",
@@ -245,18 +245,6 @@
       "types": "./dist/components/data-entry/command.d.ts",
       "import": "./dist/components/data-entry/command.js"
     },
-    "./ui/context-menu": {
-      "types": "./dist/components/navigation/context-menu.d.ts",
-      "import": "./dist/components/navigation/context-menu.js"
-    },
-    "./ui/menubar": {
-      "types": "./dist/components/navigation/menubar.d.ts",
-      "import": "./dist/components/navigation/menubar.js"
-    },
-    "./ui/navigation-menu": {
-      "types": "./dist/components/navigation/navigation-menu.d.ts",
-      "import": "./dist/components/navigation/navigation-menu.js"
-    },
     "./ui/resizable": {
       "types": "./dist/components/layout/resizable.d.ts",
       "import": "./dist/components/layout/resizable.js"
@@ -338,27 +326,19 @@
     "check:screen-reader-evidence": "node scripts/check-screen-reader-evidence.mjs",
     "check:voiceover-capture": "node scripts/check-voiceover-capture.mjs",
     "capture:voiceover": "node scripts/capture-voiceover-evidence.mjs",
-    "check:data-entry-frame-runtime": "node scripts/check-data-entry-frame-runtime.mjs",
     "check:data-entry-owner-source": "node scripts/check-data-entry-owner-source.mjs",
     "check:data-entry-touch-aria": "node scripts/check-data-entry-touch-aria.mjs",
-    "check:layout-nav-frames": "node scripts/check-layout-nav-frames.mjs",
-    "check:provider-feedback-query-runtime": "for frames in navigation-app-setting-picker,feedback-dialog,feedback-sheet,feedback-alert-dialog feedback-tooltip,feedback-toast,feedback-skeleton,query-data-state query-infinite-query-state,query-mutation-feedback,query-prefetch-link; do FRAMES=$frames node scripts/check-provider-feedback-query-runtime.mjs || exit 1; done",
-    "check:layout-nav-closure": "for frames in layout-flex,layout-app-shell,layout-aspect-ratio,layout-auth-shell layout-page-container,layout-resizable-panel,layout-separator,layout-sidebar layout-split-pane,layout-topbar,navigation-breadcrumb,navigation-app-setting-picker navigation-context-menu,navigation-dropdown-menu,navigation-menubar,navigation-navigation-menu navigation-steps,navigation-toolbar,navigation-tabs,navigation-pagination; do FRAMES=$frames node scripts/check-layout-nav-closure.mjs || exit 1; done",
     "check:display-runtime-evidence": "node scripts/check-display-runtime-evidence.mjs",
-    "check:data-table-pagination-wrap": "node scripts/check-data-table-pagination-wrap.mjs",
-    "check:tabs-overflow-menu": "node scripts/check-tabs-overflow-menu.mjs",
-    "check:button-icon-xs": "node scripts/check-button-icon-xs.mjs",
-    "check:timeline-title-fill": "node scripts/check-timeline-title-fill.mjs",
-    "check:descriptions-label-value-step": "node scripts/check-descriptions-label-value-step.mjs",
+    "check:choice-hit-target": "node scripts/check-choice-hit-target.mjs",
+    "check:app-shell-narrow-grid": "node scripts/check-app-shell-narrow-grid.mjs",
     "check:frame-contracts": "pnpm check:component-api-manifest && pnpm audit:component-cases && pnpm check:frame-coverage && pnpm check:frame-coverage-ledger && pnpm check:screen-reader-evidence && pnpm check:data-entry-owner-source && pnpm check:display-runtime-evidence",
-    "check:final-touch-rtl": "node scripts/check-final-touch-rtl.mjs",
-    "check:frame-runtime": "pnpm check:data-entry-frame-runtime && pnpm check:data-entry-touch-aria && pnpm check:layout-nav-frames && pnpm check:provider-feedback-query-runtime && pnpm check:layout-nav-closure && pnpm check:final-touch-rtl && pnpm check:data-table-pagination-wrap && pnpm check:tabs-overflow-menu && pnpm check:button-icon-xs && pnpm check:timeline-title-fill && pnpm check:descriptions-label-value-step",
+    "check:frame-runtime": "pnpm check:data-entry-touch-aria && pnpm check:app-shell-narrow-grid && pnpm check:choice-hit-target",
     "verify": "pnpm typecheck && pnpm lint && pnpm format && pnpm build && pnpm preview:build && pnpm check:example-imports && pnpm check:core-isolation && pnpm check:no-consumer-coupling && pnpm check:prop-vocabulary && pnpm check:token-tiers && pnpm check:no-external-assets && pnpm check:token-scale-bypass && pnpm check:radix-surface && pnpm check:dist-tokens-resolve && pnpm check:no-hardcoded-geometry && pnpm check:no-hardcoded-css-values && pnpm check:disclosure-duplication && pnpm check:no-inline-magic-numbers && pnpm check:no-tailwind-class-assertions && pnpm check:control-sizing && pnpm check:rtl && pnpm check:typography && pnpm check:mcp-lockstep && pnpm check:mcp-sync && pnpm check:doc-prop-existence && pnpm check:mcp-catalog-coverage && pnpm check:mcp-orphans && pnpm check:mcp-pattern-imports && pnpm check:audit-sync && pnpm check:frame-coverage && pnpm test",
     "verify:static": "pnpm build && pnpm check:packed-public-contract && pnpm typecheck && pnpm typecheck:docs && pnpm lint && pnpm preview:build && pnpm check:example-imports && pnpm check:core-isolation && pnpm check:no-consumer-coupling && pnpm check:use-client && pnpm check:prop-vocabulary && pnpm check:token-tiers && pnpm check:token-scale-bypass && pnpm check:radix-surface && pnpm check:dist-tokens-resolve && pnpm check:no-hardcoded-geometry && pnpm check:no-hardcoded-css-values && pnpm check:disclosure-duplication && pnpm check:no-inline-magic-numbers && pnpm check:no-tailwind-class-assertions && pnpm check:control-sizing && pnpm check:rtl && pnpm check:typography && pnpm check:mcp-lockstep && pnpm check:mcp-sync && pnpm check:doc-prop-existence && pnpm check:mcp-catalog-coverage && pnpm check:mcp-orphans && pnpm check:mcp-pattern-imports && pnpm check:audit-sync && pnpm check:mcp-prop-sync && pnpm check:contrast && pnpm check:visual-audit && pnpm test",
     "verify:ci": "pnpm verify:ci:static && pnpm check:frame-contracts && pnpm test",
-    "verify:ci:static": "pnpm build && pnpm check:packed-public-contract && pnpm typecheck && pnpm typecheck:docs && pnpm lint && pnpm preview:build && pnpm check:registry && pnpm check:example-imports && pnpm check:core-isolation && pnpm check:no-consumer-coupling && pnpm check:use-client && pnpm check:prop-vocabulary && pnpm check:token-tiers && pnpm check:no-external-assets && pnpm check:token-scale-bypass && pnpm check:no-antd-runtime && pnpm check:radix-surface && pnpm check:dist-tokens-resolve && pnpm check:no-hardcoded-geometry && pnpm check:no-hardcoded-css-values && pnpm check:disclosure-duplication && pnpm check:no-inline-magic-numbers && pnpm check:no-tailwind-class-assertions && pnpm check:control-sizing && pnpm check:rtl && pnpm check:typography && pnpm check:mcp-lockstep && pnpm check:mcp-sync && pnpm check:doc-prop-existence && pnpm check:mcp-catalog-coverage && pnpm check:mcp-orphans && pnpm check:mcp-pattern-imports && pnpm check:audit-sync && pnpm check:gate-coverage && pnpm check:mcp-prop-sync && pnpm check:catalog-contradictions && pnpm check:catalog-snippets",
-    "verify:browser": "pnpm check:contrast && pnpm check:text-ink-clip && pnpm check:visual-audit",
-    "verify:release": "pnpm verify:static && pnpm check:frame-contracts && pnpm check:frame-coverage && pnpm check:frame-axe",
+    "verify:ci:static": "pnpm build && pnpm check:packed-public-contract && pnpm typecheck && pnpm typecheck:docs && pnpm lint && pnpm preview:build && pnpm check:registry && pnpm check:example-imports && pnpm check:core-isolation && pnpm check:no-consumer-coupling && pnpm check:use-client && pnpm check:prop-vocabulary && pnpm check:token-tiers && pnpm check:no-external-assets && pnpm check:token-scale-bypass && pnpm check:no-antd-runtime && pnpm check:radix-surface && pnpm check:dist-tokens-resolve && pnpm check:no-hardcoded-geometry && pnpm check:no-hardcoded-css-values && pnpm check:disclosure-duplication && pnpm check:no-inline-magic-numbers && pnpm check:no-tailwind-class-assertions && pnpm check:control-sizing && pnpm check:rtl && pnpm check:typography && pnpm check:mcp-lockstep && pnpm check:mcp-token-sync && pnpm check:email-token-sync && pnpm check:mcp-sync && pnpm check:doc-prop-existence && pnpm check:mcp-catalog-coverage && pnpm check:mcp-orphans && pnpm check:mcp-pattern-imports && pnpm check:audit-sync && pnpm check:gate-coverage && pnpm check:mcp-prop-sync && pnpm check:catalog-contradictions && pnpm check:catalog-snippets",
+    "verify:browser": "pnpm check:contrast && pnpm check:text-ink-clip && pnpm check:font-fallback-metrics && pnpm check:visual-audit",
+    "verify:release": "pnpm verify:static && pnpm check:frame-contracts && pnpm check:frame-coverage",
     "verify:publish-tree": "pnpm build && pnpm check:packed-public-contract && pnpm check:use-client && pnpm check:dist-tokens-resolve",
     "check:release-plan": "node scripts/check-release-command-plan.mjs",
     "check:packed-public-contract": "node scripts/check-packed-public-contract.mjs",
@@ -407,20 +387,24 @@
     "check:gate-coverage": "node scripts/check-gate-coverage.mjs",
     "check:contrast": "node scripts/check-contrast.mjs",
     "check:text-ink-clip": "node scripts/check-text-ink-clip.mjs",
+    "check:font-fallback-metrics": "node scripts/check-font-fallback-metrics.mjs",
     "visual-audit": "node scripts/visual-audit.mjs",
     "check:visual-audit": "node scripts/visual-audit-smoke.mjs",
-    "check:frame-axe": "node scripts/check-frame-axe.mjs",
     "check:frame-geometry": "node scripts/frame-geometry.mjs",
     "postinstall": "node scripts/postinstall.mjs",
     "init-agent": "node scripts/init-agent-kit.mjs",
     "check:use-client": "node scripts/check-use-client.mjs",
-    "check:catalog-snippets": "node scripts/audit-catalog-snippets.mjs"
+    "check:catalog-snippets": "node scripts/audit-catalog-snippets.mjs",
+    "check:data-entry-frame-runtime": "node scripts/check-data-entry-frame-runtime.mjs",
+    "check:data-table-empty-inset": "node scripts/check-data-table-empty-inset.mjs",
+    "check:number-input-step-target": "node scripts/check-number-input-step-target.mjs",
+    "check:mcp-token-sync": "node scripts/gen-component-tokens.mjs --check",
+    "check:email-token-sync": "node scripts/gen-email-tokens.mjs --check",
+    "check:focus-ring-paint": "node scripts/check-focus-ring-paint.mjs"
   },
   "peerDependencies": {
-    "@axe-core/playwright": "*",
     "@hookform/resolvers": "^5.2.0",
     "@tanstack/react-query": ">=5.0.0",
-    "axe-core": "*",
     "playwright": "*",
     "react": ">=19.0.0",
     "react-dom": ">=19.0.0",
@@ -436,32 +420,12 @@
     },
     "playwright": {
       "optional": true
-    },
-    "@axe-core/playwright": {
-      "optional": true
-    },
-    "axe-core": {
-      "optional": true
     }
   },
   "dependencies": {
     "@date-fns/tz": "^1.5.0",
     "@fontsource/m-plus-2": "^5.3.0",
     "@fontsource/noto-sans-jp": "^5.3.0",
-    "@radix-ui/react-accordion": "^1.2.20",
-    "@radix-ui/react-avatar": "^1.2.6",
-    "@radix-ui/react-collapsible": "^1.1.20",
-    "@radix-ui/react-context-menu": "^2.3.7",
-    "@radix-ui/react-label": "^2.1.15",
-    "@radix-ui/react-menubar": "^1.1.24",
-    "@radix-ui/react-navigation-menu": "^1.2.22",
-    "@radix-ui/react-scroll-area": "^1.2.18",
-    "@radix-ui/react-select": "^2.3.7",
-    "@radix-ui/react-separator": "^1.1.15",
-    "@radix-ui/react-slider": "^1.4.7",
-    "@radix-ui/react-slot": "^1.3.3",
-    "@radix-ui/react-toggle": "^1.1.18",
-    "@radix-ui/react-toggle-group": "^1.1.19",
     "@react-aria/utils": "^3.34.1",
     "@tanstack/react-table": "^9.2.4",
     "class-variance-authority": "^0.7.1",
@@ -483,9 +447,17 @@
     "vaul": "^1.1.2"
   },
   "devDependencies": {
-    "@axe-core/playwright": "^4.13.0",
     "@eslint/js": "^10.0.1",
     "@hookform/resolvers": "^5.9.1",
+    "@radix-ui/react-accordion": "^1.2.20",
+    "@radix-ui/react-avatar": "^1.2.6",
+    "@radix-ui/react-collapsible": "^1.1.20",
+    "@radix-ui/react-label": "^2.1.15",
+    "@radix-ui/react-select": "^2.3.7",
+    "@radix-ui/react-separator": "^1.1.15",
+    "@radix-ui/react-slot": "^1.3.3",
+    "@radix-ui/react-toggle": "^1.1.18",
+    "@radix-ui/react-toggle-group": "^1.1.19",
     "@tailwindcss/vite": "^4.3.3",
     "@tanstack/react-query": "^5.102.8",
     "@testing-library/jest-dom": "^7.0.1",
@@ -497,7 +469,6 @@
     "@types/react-dom": "^19.2.5",
     "@vitejs/plugin-react": "^6.1.1",
     "@vitest/coverage-v8": "^4.1.11",
-    "axe-core": "^4.13.0",
     "eslint": "^10.9.1",
     "eslint-plugin-react": "^7.37.5",
     "eslint-plugin-react-hooks": "^7.1.1",
@@ -520,7 +491,6 @@
     "typescript-eslint": "^8.68.0",
     "vite": "^8.2.2",
     "vitest": "^4.1.11",
-    "vitest-axe": "1.0.0-pre.5",
     "zod": "^4.5.4"
   },
   "bin": {

package/scripts/_agent-setup.mjs

@@ -372,6 +372,24 @@ export function ensureConsumerRules(root) {
   mkdirSync(dir, { recursive: true });
   writeFileSync(target, next);
 
+  // Prettier and this writer were fighting over the same file: the body holds aligned markdown
+  // tables, Prettier reformats them, the digest changes, the next install writes it back, and
+  // `format:check` goes red again — a loop with no winner, and the consumer is who is stuck in it
+  // (godx-jp/id#513). The file is OURS; say so to Prettier once, idempotently.
+  const ignoreFile = join(root, ".prettierignore");
+  if (existsSync(ignoreFile)) {
+    const cur = readFileSync(ignoreFile, "utf8");
+    const owned = [".ai/rules/godxjp-ui.md", ".claude/godxjp-ui-workflow.md"].filter(
+      (line) => !cur.includes(line),
+    );
+    if (owned.length) {
+      writeFileSync(
+        ignoreFile,
+        `${cur.replace(/\s*$/, "")}\n\n# Owned by @godxjp/ui — rewritten on every install, never hand-formatted.\n${owned.join("\n")}\n`,
+      );
+    }
+  }
+
   // Only touch the index when the repo keeps one; a missing index means the repo reads rule files
   // directly, and inventing one would change how it loads everything else.
   const index = join(dir, "index.md");

package/scripts/guinea-pig-skill.md

@@ -45,12 +45,17 @@ chúng. Không chép lại ở đây. Ba điều cấm riêng của **chuột b
    `w-[240px]`, `text-muted-foreground`.
 3. **Gõ mã màu hex hay số đo ngoài thang token.**
 
-Thước đo, chạy trước mọi lần review:
+Thước đo, chạy trước mọi lần review — **quét đúng thứ bạn vừa đụng vào**:
 
 ```bash
-node node_modules/@godxjp/ui/scripts/ui-audit.mjs resources/js   # 0 lỗi là mức đạt
+node node_modules/@godxjp/ui/scripts/ui-audit.mjs --changed   # 0 lỗi là mức đạt
 ```
 
+`--changed` lấy danh sách từ diff so với merge-base, nên nó thấy cả file sửa bằng
+shell — thứ hook `PostToolUse` không thấy. Quét cả `resources/js` chỉ khi việc được
+giao ĐÚNG là soát toàn bộ UI: trên một kho cũ, nó trả về hàng trăm phát hiện thuộc
+mã kế thừa và chôn mất cái bạn vừa tạo ra.
+
 Một lỗi bạn **không sửa được ở phía consumer** chính là một khoảng trống của DS.
 Nó là đầu vào của §3, không phải một ngoại lệ để nới.
 
@@ -116,10 +121,11 @@ tarball đường dẫn máy bạn lọt vào commit. `main` phải `npm ci` đ
 
 ### Bước 5 — Cổng của DS
 
-```bash
-# = verify:ci:static + check:frame-contracts + pnpm test, tức ĐÚNG những gì ci.yml chạy.
-cd ~/Herd/godxjp-ui && pnpm verify:ci
-```
+**KHÔNG chạy `pnpm verify:ci` / `pnpm test` của kho DS khi chưa được chủ dự án cho
+phép trong chính lượt trao đổi ấy.** Đó là bộ đầy đủ của một kho KHÁC — hàng nghìn
+test cộng các cổng trình duyệt, hàng chục phút máy mỗi lượt. Chạy đúng test bạn vừa
+viết cho thay đổi này, đẩy nhánh, rồi đọc cổng đỏ trên Actions: `ci.yml` chạy y hệt
+những thứ ấy trên PR. **Tới được bước này KHÔNG phải là được phép.**
 
 **Không nới, không tắt, không thêm ngoại lệ để lấy màu xanh.** Một cổng đỏ là
 một câu hỏi, không phải một chướng ngại. Nếu bạn tin cổng ấy sai thì nói ra và

package/scripts/ui-audit.mjs

@@ -5,7 +5,8 @@
  * .claude/skills/frontend-design/rules/ui-standardization.md): use the design system, never
  * hand-roll.
  */
-import { readdirSync, readFileSync, statSync } from "node:fs";
+import { spawnSync } from "node:child_process";
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
 import { isAbsolute, join, relative } from "node:path";
 
 const CWD = process.cwd();
@@ -20,11 +21,45 @@ const args = process.argv.slice(2);
 const asJson = args.includes("--format") && args[args.indexOf("--format") + 1] === "json";
 const quiet = args.includes("--quiet");
 const dirArgs = args.filter((a) => !a.startsWith("--") && a !== "json");
-const SCAN_DIRS = dirArgs.length
-  ? dirArgs
-  : SELF
-    ? ["src", "docs"]
-    : ["resources/js/components", "resources/js/pages", "resources/js/layouts"];
+
+/**
+ * `--changed` — audit what this branch touched, whatever tool touched it.
+ *
+ * The PostToolUse hook fires on `Write|Edit|MultiEdit`, so an agent editing through a shell
+ * (`sed -i`, a heredoc, `cat >`) never triggers it. A consumer measured exactly that: across a
+ * long session EVERY `.tsx` edit went through Bash and the audit fired not once (godx-jp/id#497).
+ * The hook cannot close it — a Bash call carries no `file_path`. A diff can, and one line in a
+ * local gate or in CI then covers every edit path, including the ones nobody thought of.
+ */
+function changedFiles() {
+  const base =
+    spawnSync("git", ["merge-base", "HEAD", "origin/main"], { encoding: "utf8" }).stdout.trim() ||
+    "HEAD";
+  const run = (a) => spawnSync("git", a, { encoding: "utf8" }).stdout ?? "";
+
+  return [
+    ...new Set(
+      [
+        run(["diff", "--name-only", "--diff-filter=ACMR", base, "--"]),
+        run(["diff", "--name-only", "--diff-filter=ACMR", "--cached"]),
+        run(["ls-files", "--others", "--exclude-standard"]),
+      ]
+        .join("\n")
+        .split("\n")
+        .map((f) => f.trim())
+        .filter((f) => /\.(tsx|jsx)$/.test(f) && existsSync(join(CWD, f))),
+    ),
+  ];
+}
+
+const CHANGED = args.includes("--changed");
+const SCAN_DIRS = CHANGED
+  ? changedFiles()
+  : dirArgs.length
+    ? dirArgs
+    : SELF
+      ? ["src", "docs"]
+      : ["resources/js/components", "resources/js/pages", "resources/js/layouts"];
 
 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";
@@ -89,6 +124,7 @@ const ATTRS = String.raw`(?:"(?:\\.|[^"\\])*"|'(?:\\.|[^'\\])*'|=>|[^>"'])*`;
 const RULES = [
   {
     id: "no-utility-spacing",
+    replacement: "Flex gap / ResponsiveGrid / PageContainer",
     classOnly: true,
     scope: "consumer",
     severity: "error",
@@ -101,6 +137,7 @@ const RULES = [
   },
   {
     id: "no-utility-layout",
+    replacement: "Flex (row), Flex direction col (stack), ResponsiveGrid",
     scope: "consumer",
     severity: "error",
     // A hand-rolled flex/grid container. The primitives exist precisely so a row is <Flex>, a
@@ -111,6 +148,7 @@ const RULES = [
   },
   {
     id: "no-hand-rolled-surface",
+    replacement: "Card / Badge / Avatar / ListRow / Descriptions / EmptyState / Progress",
     scope: "consumer",
     severity: "warn",
     // rounded + border/bg on the consumer's own element = a fake Card / Badge / Avatar / ListRow
@@ -139,6 +177,7 @@ const RULES = [
   },
   {
     id: "no-space-xy",
+    replacement: "Flex gap",
     classOnly: true,
     severity: "error",
     test: /\bspace-[xy]-\d/,
@@ -146,6 +185,7 @@ const RULES = [
   },
   {
     id: "no-raw-palette-color",
+    replacement: "a semantic token (--primary, --muted-foreground, --border)",
     classOnly: true,
     severity: "error",
     test: new RegExp(
@@ -156,11 +196,12 @@ const RULES = [
   },
   {
     id: "status-tone-not-variant",
+    replacement: "tone=",
     severity: "error",
     spansElement: true,
     // Only the tone-driven status components (Badge/Tag/StatCard) are wrong here — they expose a
     // `tone` prop and reserve `variant` for STRUCTURE (default|secondary|outline). Button, Alert,
-    // DropdownMenuItem, ContextMenuItem, AlertDialog etc. legitimately use `variant` for emphasis,
+    // DropdownMenuItem, AlertDialog etc. legitimately use `variant` for emphasis,
     // so they must NOT be flagged.
     test: new RegExp(
       `<(?:Badge|Tag|StatCard)\\b${ATTRS}\\bvariant=["'](?:success|warning|destructive|info|neutral)["']`,
@@ -178,6 +219,7 @@ const RULES = [
   },
   {
     id: "value-callback-on-value-change",
+    replacement: "onValueChange",
     severity: "error",
     spansElement: true,
     test: new RegExp(
@@ -190,6 +232,7 @@ const RULES = [
   },
   {
     id: "no-arbitrary-hex",
+    replacement: "a semantic token",
     classOnly: true,
     severity: "error",
     test: /(bg|text|border|ring|fill|stroke|from|to|via)-\[#[0-9a-fA-F]{3,8}\]/,
@@ -200,6 +243,7 @@ const RULES = [
   // (they start with a letter), so token-driven values stay legal (rules §4–§5).
   {
     id: "no-arbitrary-spacing",
+    replacement: "Flex gap / the spacing scale",
     classOnly: true,
     severity: "error",
     test: /\b(p|px|py|pt|pb|pl|pr|pe|ps|m|mx|my|mt|mb|ml|mr|me|ms|gap|gap-x|gap-y|inset|inset-x|inset-y|top|right|bottom|left)-\[-?\.?\d/,
@@ -208,6 +252,7 @@ const RULES = [
   },
   {
     id: "no-arbitrary-size",
+    replacement: "a size token or the component's size prop",
     classOnly: true,
     severity: "error",
     // `min-w-[…]` / `min-h-[…]` are allowed: a MINIMUM dimension is the legit responsive
@@ -220,6 +265,7 @@ const RULES = [
   },
   {
     id: "no-arbitrary-typography",
+    replacement: "Text size / weight / tone",
     classOnly: true,
     severity: "error",
     test: /\b(text|leading|tracking|font)-\[-?\.?\d/,
@@ -228,6 +274,7 @@ const RULES = [
   },
   {
     id: "no-arbitrary-radius",
+    replacement: "a radius token",
     classOnly: true,
     severity: "error",
     test: /\brounded(?:-[a-z]+)?-\[-?\.?\d/,
@@ -267,6 +314,7 @@ const RULES = [
   },
   {
     id: "no-raw-select",
+    replacement: "Select",
     scope: "consumer-control",
     severity: "error",
     test: /<select[\s>]/,
@@ -274,12 +322,14 @@ const RULES = [
   },
   {
     id: "no-raw-table",
+    replacement: "DataTable / Table",
     severity: "error",
     test: /<table[\s>]/,
     message: "Use the <Table> family from @godxjp/ui, not a raw <table> (rules §3).",
   },
   {
     id: "no-raw-textarea",
+    replacement: "Textarea",
     scope: "consumer-control",
     severity: "warn",
     test: /<textarea[\s>]/,
@@ -287,6 +337,7 @@ const RULES = [
   },
   {
     id: "no-raw-input",
+    replacement: "Input (Upload for a file picker)",
     scope: "consumer-control",
     severity: "error",
     spansElement: true,
@@ -295,6 +346,7 @@ const RULES = [
   },
   {
     id: "no-raw-button",
+    replacement: "Button",
     scope: "consumer-control",
     severity: "error",
     test: /<button[\s>]/,
@@ -302,6 +354,7 @@ const RULES = [
   },
   {
     id: "card-manual-padding",
+    replacement: "CardContent (or CardContent flush)",
     severity: "error",
     spansElement: true,
     test: new RegExp(`<Card\\b${ATTRS}\\bp-[1-9]`, "g"),
@@ -310,6 +363,7 @@ const RULES = [
   },
   {
     id: "no-dark-color-override",
+    replacement: "a semantic token, which already answers to the theme",
     classOnly: true,
     severity: "warn",
     test: /\bdark:(bg|text|border|ring|fill|stroke)-/,
@@ -342,6 +396,7 @@ const RULES = [
   // ─── International-standard a11y / i18n / RTL rules (WARN — guide the agent, never block) ───
   {
     id: "no-emoji-in-ui",
+    replacement: "a lucide icon",
     severity: "warn",
     test: EMOJI,
     standard: "Unicode UTS #51 (emoji) · WCAG 2.2 SC 1.1.1",
@@ -358,6 +413,7 @@ const RULES = [
   },
   {
     id: "no-physical-direction",
+    replacement: "the logical property (ms-/me-, inline-start/inline-end)",
     classOnly: true,
     severity: "warn",
     // Physical-edge utilities break RTL. Logical equivalents: ms-/me-/ps-/pe-, start-/end-,
@@ -465,6 +521,7 @@ if (args.includes("--rules")) {
           severity: r.severity,
           standard: r.standard ?? null,
           message: r.message,
+          replacement: r.replacement,
         })),
         null,
         2,
@@ -730,6 +787,22 @@ function jsxOpeningEnd(source, start) {
 // Structural: a <Card> (without p-0) whose first child is body content rather than a Card
 // sub-component sits FLUSH (no padding). Per-line regexes can't see across lines, so this is a
 // whole-file pass. The body must be wrapped in <CardContent> (titles in <CardHeader>).
+/**
+ * A `Card` whose entire body is a table. `CardContent` pads 16px inline while
+ * `.ui-data-table-surface` draws its own 1px border, so the default composition renders a box
+ * inside a box — and a wide table runs PAST the card's edge instead of stopping at it (measured in
+ * a consumer at −85px and −519px, godx-jp/id#498). `<CardContent flush>` already solves it. What
+ * was missing was the rule that says so.
+ *
+ * Deliberately narrow: the table must be the DIRECT child. A `<Flex direction="col">` holding
+ * filters AND a table is a mixed body, where the padding is correct — the reporter hit that trap
+ * with a `childElementCount === 1` test.
+ */
+const CARD_TABLE_FLUSH = new RegExp(
+  `<CardContent(?![^>]*\\bflush\\b)(?:\\s${ATTRS})?>\\s*<(?:DataTable|Table)\\b`,
+  "g",
+);
+
 const CARD_FLUSH = new RegExp(
   `<Card(?!${ATTRS}\\bp-0\\b)(?:\\s${ATTRS})?>\\s*<(?!CardContent|CardHeader|CardCover|CardFooter|CardBar|\\/Card)`,
   "g",
@@ -760,7 +833,53 @@ const SIBLING_CARDS = /^([ \t]*)<\/Card>\s*\n\1<Card\b/gm;
 const ACTIVE_RULES =
   SELF && !args.includes("--consumer") ? RULES.filter((r) => r.scope !== "consumer") : RULES;
 
+/**
+ * The rule file this package OWNS, and whether the consumer's copy is the one this package writes.
+ *
+ * `.ai/rules/godxjp-ui.md` opens by promising it is rewritten on every upgrade. A consumer with
+ * `ignore-scripts=true` — a sane, increasingly common default — never runs our postinstall, so the
+ * promise silently fails: measured in a consumer at `godxjp-ui:version 19.6.0` while the installed
+ * package was **23.0.0**, three majors apart (godx-jp/id#513). An agent then follows a rule file
+ * describing components that were removed, props that no longer exist and a `role` attribute that
+ * is gone — and nothing anywhere says the ground moved.
+ *
+ * postinstall cannot fix this: it is the thing that did not run. This can, because a consumer runs
+ * the audit.
+ */
+function staleOwnedRules() {
+  if (SELF) return null;
+  const target = join(CWD, ".ai", "rules", "godxjp-ui.md");
+  if (!existsSync(target)) return null;
+
+  const stamped = /<!-- godxjp-ui:version ([^\s]+) -->/.exec(readFileSync(target, "utf8"))?.[1];
+  let installed;
+  try {
+    installed = JSON.parse(
+      readFileSync(join(CWD, "node_modules", "@godxjp", "ui", "package.json"), "utf8"),
+    ).version;
+  } catch {
+    return null;
+  }
+  if (!stamped || !installed || stamped === installed) return null;
+
+  return {
+    file: ".ai/rules/godxjp-ui.md",
+    line: 1,
+    rule: "owned-rules-stale",
+    severity: "error",
+    message:
+      `This file is written by @godxjp/ui and says version ${stamped}, but the installed package ` +
+      `is ${installed}. Its rules describe a different library than the one you are building ` +
+      "against — most likely because `ignore-scripts=true` kept our postinstall from running.",
+    replacement:
+      "INIT_CWD=\"$PWD\" node node_modules/@godxjp/ui/scripts/postinstall.mjs",
+    snippet: `<!-- godxjp-ui:version ${stamped} --> vs installed ${installed}`,
+  };
+}
+
 const findings = [];
+const stale = staleOwnedRules();
+if (stale) findings.push(stale);
 let filesScanned = 0;
 for (const dir of SCAN_DIRS) {
   for (const file of walk(isAbsolute(dir) ? dir : join(CWD, dir))) {
@@ -809,6 +928,7 @@ for (const dir of SCAN_DIRS) {
             severity: rule.severity,
             standard: rule.standard,
             message: rule.message,
+            replacement: rule.replacement,
             snippet: (origLines[i] ?? line).trim().slice(0, 120),
           });
         }
@@ -844,7 +964,38 @@ for (const dir of SCAN_DIRS) {
       }
     }
     if (!isJsx) continue;
+    /**
+     * `CARD_FLUSH` wants a Card slot as the IMMEDIATE next element, so any legitimate wrapper
+     * trips it. The one that matters is `<Form>`: a submit button in `<CardFooter>` only submits
+     * when the `<form>` wraps BOTH the content and the footer, so `<Card><Form><CardContent>` is
+     * the only correct shape for that card — and it was reported as an error three times in one
+     * consumer file (godx-jp/id#496), on its newest code. A confident error against correct code
+     * teaches the reader that the audit is noise.
+     *
+     * The rule's intent is "the body must not sit flush against the card edges", so ask that:
+     * is there a `<CardContent>` before this Card's own `</Card>`? Depth is counted, because a
+     * Card can hold a Card.
+     */
+    const hasBodyBeforeClose = (from) => {
+      let depth = 0;
+      const tag = /<(\/?)Card(Content|Header|Cover|Footer|Bar)?\b/g;
+      tag.lastIndex = from;
+      for (let m; (m = tag.exec(scanContent)); ) {
+        const [, closing, slot] = m;
+        if (!slot) {
+          if (closing) {
+            if (depth === 0) return false;
+            depth -= 1;
+          } else depth += 1;
+          continue;
+        }
+        if (!closing && slot === "Content" && depth <= 1) return true;
+      }
+      return false;
+    };
+
     for (const match of scanContent.matchAll(CARD_FLUSH)) {
+      if (hasBodyBeforeClose(match.index)) continue;
       const lineNo = scanContent.slice(0, match.index).split("\n").length;
       if (suppressed("card-needs-content", lineNo - 1)) continue;
       findings.push({
@@ -857,6 +1008,24 @@ for (const dir of SCAN_DIRS) {
         snippet: match[0].replace(/\s+/g, " ").slice(0, 120),
       });
     }
+    for (const match of scanContent.matchAll(CARD_TABLE_FLUSH)) {
+      const lineNo = scanContent.slice(0, match.index).split("\n").length + 1;
+
+      if (suppressed("card-table-needs-flush", lineNo - 1)) continue;
+
+      findings.push({
+        file: rel,
+        line: lineNo,
+        rule: "card-table-needs-flush",
+        severity: "error",
+        message:
+          "A Card whose whole body is a table must let the table touch the card's inner edge — " +
+          "use <CardContent flush>. A default CardContent pads 16px while the table draws its own " +
+          "border, so the table reads as a second box inside the card and a wide one overflows it.",
+        replacement: "CardContent flush",
+        snippet: match[0].replace(/\s+/g, " ").slice(0, 120),
+      });
+    }
     if (
       !(SELF && !args.includes("--consumer")) &&
       !/<(?:Flex|ResponsiveGrid|PageContainer)\b/.test(scanContent)
@@ -899,6 +1068,12 @@ const warnings = findings.filter((f) => f.severity === "warn");
 // `resources/js/{components,pages,layouts}`; `walk()` swallows ENOENT and returns [], so in any
 // tree without that layout — this repo included — `pnpm audit` printed
 // "✓ No UI-standardization violations found." and exited 0 having read nothing at all.
+// …except under `--changed`, where "this branch touched no .tsx" is a clean run, not a
+// misconfigured path. Failing there would make the gate unusable on every backend-only commit.
+if (filesScanned === 0 && CHANGED) {
+  if (!quiet && !asJson) console.log("✓ ui-audit --changed: no .tsx/.jsx changed on this branch.");
+  process.exit(0);
+}
 if (filesScanned === 0) {
   const message =
     `ui-audit scanned 0 files — none of [${SCAN_DIRS.join(", ")}] exists (or all were filtered). ` +
@@ -937,6 +1112,9 @@ if (filesScanned === 0) {
     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}`);
+    // Name the primitive HERE: without it every finding costs a round-trip to the catalog plus a
+    // guess about what to look up (godx-jp/id#497). The audit already knows the answer.
+    if (f.replacement) console.log(`      ${C.bold}use: ${f.replacement}${C.reset}`);
     if (f.standard) console.log(`      ${C.dim}standard: ${f.standard}${C.reset}`);
     console.log(`      ${C.dim}${f.snippet}${C.reset}`);
   }