@godxjp/ui 32.6.0 → 32.7.0

package/dist/tokens/components/legal-document.css

@@ -8,6 +8,10 @@
 
   --legal-document-toc-width: 15rem;
 
+  --legal-document-page-padding-inline: initial;
+
+  --legal-document-title-font-size: initial;
+
   --legal-document-toc-inset-block-start: var(--space-6);
 
   --legal-document-toc-max-height: calc(100dvh - var(--space-12));

package/docs/CONSUMER-RULES.md

@@ -4,10 +4,10 @@ Read this once; the audit enforces it. What the audit cannot see (how a screen i
 should look like) is in the package's `DESIGN.md`. Everything else in `docs/` is for contributors.
 
 1. Load styles with `import "@godxjp/ui/styles.css"` (precompiled, no Tailwind needed) or `@import "@godxjp/ui/styles"` (Tailwind v4). Neither ships font files: fonts are opt-in since v32 (`pnpm add @fontsource/noto-sans-jp @fontsource/m-plus-2`, then `@import "@godxjp/ui/styles/fonts.css"` after the styles import; the GoDX preset does this for you). Never cherry-pick `*-layout.css`.
-2. **Mount `<AppProvider defaultLocale="…">` once, at the root.** Without it the kit's OWN strings (dialog close/cancel/delete, counters, picker labels) fall to the resting locale `vi` and pickers to UTC — measured in a Japanese app as Vietnamese buttons, silently (gh#1005). A development build now warns once when a kit component renders outside it; `syncI18nLocale(locale, fallback)` is the escape for an app that truly cannot mount the provider. Every page is `<PageContainer title extra footer>` (a `subtitle` only when it adds a fact the title does not); its sections are spaced by the page. Group items inside a section with `<Flex direction="col" gap>` or `<ResponsiveGrid>`.
+2. **Mount `<AppProvider defaultLocale="…">` once, at the root.** Without it the kit's OWN strings (dialog close/cancel/delete, counters, picker labels) fall to the resting locale (`<html lang>` when it names a registered locale, else `en`) and pickers to UTC (gh#1005). A development build now warns once when a kit component renders outside it; `syncI18nLocale(locale, fallback)` is the escape for an app that truly cannot mount the provider. Every page is `<PageContainer title extra footer>` (a `subtitle` only when it adds a fact the title does not); its sections are spaced by the page. Group items inside a section with `<Flex direction="col" gap>` or `<ResponsiveGrid>`.
 3. No Tailwind layout on your own elements: no `flex`, `grid`, `gap-*`, `p-*`, `m-*`, `space-*`. Rows are `<Flex>` (default row), stacks are `<Flex direction="col">`, grids are `<ResponsiveGrid>`.
 4. No hand-rolled surfaces: no `rounded-* border bg-*` divs. A box is `Card`, a pill is `Badge`, a person is `Avatar`, a row is `ListRow`, a label/value pair is `Descriptions`, an empty area is `EmptyState`, a read-only sample of a colour the USER chose is `Swatch`. A LIST of those rows is `<Flex as="ul" marker="none" direction="col" gap="none">` with `<ListRow as="li">` children — `marker="none"` keeps the `<ul>`, the `<li>` semantics and the gap token while dropping the bullet and the indent. Never a raw `<ul>`/`<ol>` (it carries no gap token), never `<div role="list">` + `<div role="listitem">`, and never a wrapper around each row: the divider is `:not(:last-child)` among siblings, so a row alone in its own wrapper is always the last one and EVERY divider disappears silently. A bulleted prose list is the same `<Flex as="ul">` without `marker`.
-5. Real controls only: `Button`, `Input`, `Select`, `Textarea`, `Checkbox`… never raw `<button>`/`<input>`; a labelled control lives in `<FormField label>`. A Select outside a form takes `width="auto"`. **A disabled control's reason is visible text, never a tooltip** — see below. **Fields live in a `<Form layout="horizontal" labelWidth controlWidth>`** — never a group of `FormField`s without one, never a hand-rolled `<Flex>` row of fields (a row that belongs together is `<SpaceCompact>` or `<Form columns>`); size each control for its content with `controlWidth` (GOV.UK text-input width: a port ~7rem, a short enum ~10rem); three or more fields is a page, not a Dialog. The audit rules are `formfield-needs-form`, `dialog-form-too-big` and `select-width-hint`. **A case the kit cannot express is an issue, not a hand-roll:** open it on godx-jp/godxjp-ui, use the nearest valid composition, and mark it `// TODO(godxjp-ui#<n>)` (gh#998). **One action row, one Button size:** every `Button` under one parent takes the same `size` — a missing size is `default`, and `icon-sm` pairs with `sm`, `icon-xs` with `xs`, `icon` with default. Never `size="sm"` beside a default Button. The audit rules are `mixed-button-size` (static) and `mixed-button-height` (visual-audit, within 0.5px) (gh#1084).
+5. Real controls only: `Button`, `Input`, `Select`, `Textarea`, `Checkbox`… never raw `<button>`/`<input>`; a labelled control lives in `<FormField label>`. A Select outside a form takes `width="auto"`. **A disabled control's reason is visible text, never a tooltip** — see below. **Fields live in a `<Form layout="horizontal" labelWidth controlWidth>`** — never a group of `FormField`s without one, never a hand-rolled `<Flex>` row of fields (a row that belongs together is `<Flex attached>` or `<Form columns>`); size each control for its content with `controlWidth` (GOV.UK text-input width: a port ~7rem, a short enum ~10rem); three or more fields is a page, not a Dialog. The audit rules are `formfield-needs-form`, `dialog-form-too-big` and `select-width-hint`. **A case the kit cannot express is an issue, not a hand-roll:** open it on godx-jp/godxjp-ui, use the nearest valid composition, and mark it `// TODO(godxjp-ui#<n>)` (gh#998). **One action row, one Button size:** every `Button` under one parent takes the same `size` — a missing size is `default`, and `icon-sm` pairs with `sm`, `icon-xs` with `xs`, `icon` with default. Never `size="sm"` beside a default Button. The audit rules are `mixed-button-size` (static) and `mixed-button-height` (visual-audit, within 0.5px) (gh#1084).
 6. Text is `<Text>` / `<Heading>` with `tone`, `size`, `weight`, `truncate`, `mono` — not `className="text-muted-foreground font-semibold"`. A STANDALONE glyph is `<Icon as={Lock} size="sm" tone="muted" />` from `@godxjp/ui/general`: a bare lucide icon carries its own `width="24" height="24"` and only four places re-size it for you (`Button`, a `DropdownMenuItem`, a `TopbarItem`, a `ListRow` leading slot), so everywhere else — in a `Text`, a table cell, an `<a>` — it draws at 24px beside 14px type. `size-4` and `w-[16px]` are closed to you by rules 3 and 8, and `size={16}` hard-codes a number the theme owns; `Icon` puts the glyph on the `--icon-size-*` scale (`2xs…4xl`) instead, and is `aria-hidden` unless you give it a `label` (then it is `role="img"` with that name). The audit rule is `lucide-icon-needs-size`.
 7. Colours are semantic tokens (`tone="destructive"`, `bg-primary`), never palette names, hex, or `bg-black` / `text-white`.
 8. Sizes come from props (`size`, `width`, `columns`), never `w-[240px]` / `max-h-[420px]`.
@@ -17,7 +17,7 @@ should look like) is in the package's `DESIGN.md`. Everything else in `docs/` is
     the table reads as a second box inside the card, and a wide one runs past the card entirely.
     (`flush` alone is enough: it drops the border, the radius and the inline padding. `tight` is a
     different knob — it governs the header band, not the body's edges.)
-11. Run `node node_modules/@godxjp/ui/scripts/ui-audit.mjs --changed` before every review; a browser sweep with `visual-audit.mjs` is a separate, heavier run — do it when the work is a visual review, not on every change; `visual-audit.mjs <url>` on the running app. Zero errors is the bar.
+11. Run `npx @godxjp/ui audit --changed` before every review (the package bin, so it works from a workspace package whose `node_modules` is hoisted to the repo root); a browser sweep with `npx @godxjp/ui visual-audit <url>` on the running app is a separate, heavier run — do it when the work is a visual review, not on every change. Zero errors is the bar.
 
 **Opting a deliberate exception out.** Name the rule; the block form also has to say why.
 

package/docs/migrations/v32.md

@@ -28,9 +28,11 @@ Off-cycle approved: owner, 2026-10-09 — the single v32 batch decided on godx-j
   renders none.
 - The email brand mark has no default label.
 - The GoDX look ships as `godxPreset` (`@godxjp/ui/themes/godx`) plus `@godxjp/ui/themes/godx.css`.
-- Since 32.0.1, `@godxjp/ui/themes/godx-tokens.css` holds the GoDX colours without the fonts, for a
-  shadow root that embeds `@godxjp/ui/styles/core` (`@font-face` only works in the document). Add it
-  after `styles/core` there; `godx.css` imports it, so a page needs only `godx.css`.
+- Since 32.0.1, `@godxjp/ui/themes/godx-tokens.css` holds the GoDX colours without the fonts.
+  `godx.css` is `fonts.css` (which imports `@fontsource/noto-sans-jp` and `@fontsource/m-plus-2`)
+  plus `godx-tokens.css`. Import `godx-tokens.css` instead of `godx.css` when the app bundles or
+  hosts its own fonts, and in a shadow root that embeds `@godxjp/ui/styles/core` (`@font-face`
+  only works in the document). Never import both. Put it after the base stylesheet.
 - A script that READS the GoDX colours from `themes/godx.css` (a token sync, a design-system
   export) must read `themes/godx-tokens.css` instead: since 32.0.1, `godx.css` holds only two
   `@import` lines.
@@ -84,7 +86,7 @@ packages. The codemod rewrites every import below; the "you finish" column is pr
 | `Title`, `Paragraph`, `Typography`                                                                                                                                                                                 | `Heading`, `Text as="p"`, `Prose` | the antd compatibility shims are removed                               |
 | `SkeletonAvatar`, `SkeletonButton`, `SkeletonImage`, `SkeletonNode`                                                                                                                                                | —                                 | removed: use `SkeletonArticle avatar` or a sized `Skeleton`            |
 | `FloatButton`, `DraggablePanel`, `PageCover`, `Masonry`, `LegalDocumentShell`, `Marquee`, `TextDiff`, `OrgChart`, `Carousel`, `TimelineGrid`, `RangeTimeline`, `EmojiPicker`, `SortableList`, `MegaMenu`, `Anchor` | same names from `@godxjp/ui/lab`  | nothing: same API, opt-in subpath                                      |
-| `ChatBubble`, `ChatBubbleList`, `ChatComposer`, `ChatSuggestion`, `Conversations`, `ThoughtChain`, `Welcome`, `Attachments`                                                                                        | same names from `@godxjp/chat`    | install `@godxjp/chat`                                                 |
+| `ChatBubble`, `ChatBubbleList`, `ChatComposer`, `ChatSuggestion`, `Conversations`, `ThoughtChain`, `Welcome`, `Attachments`                                                                                        | same names from `@godxjp/chat`    | add `@godxjp/chat` as a NEW dependency, same version as `@godxjp/ui`   |
 
 Unchanged: `SplitPane` stays (its merge into `MasterDetail` failed the parity test), `Actions` stays
 in `@godxjp/ui/general`, and `FilterBar` stays an alias of `Toolbar`. The `./ui/*` subpaths are
@@ -92,7 +94,10 @@ deprecated re-exports and will be removed in a later major.
 
 ## How to upgrade
 
-1. Upgrade all six packages to the latest 32.0.x together (`@godxjp/chat` only if you use the chat components).
+1. Upgrade all six packages to the latest 32.0.x together. An app that imports `ChatSuggestion` or
+   any other chat component from `@godxjp/ui` must ADD `@godxjp/chat` to its `package.json` — it
+   is a new dependency, not a rename — at the same version as `@godxjp/ui` (the packages release
+   in lockstep). Without it the build fails on the first chat import.
 2. Run `npx godxjp-ui codemod v32 <src> --dry-run`, review, then run it without `--dry-run`. Use
    `--godx` for GoDX products.
    The 32.0.0 codemod imported the fonts twice under `--godx` (`fonts.css` and `godx.css`, which

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@godxjp/ui",
-  "version": "32.6.0",
-  "godxUiMcp": "32.6.0",
+  "version": "32.7.0",
+  "godxUiMcp": "32.7.0",
   "license": "Apache-2.0",
   "repository": {
     "type": "git",

package/scripts/_agent-setup.mjs

@@ -15,6 +15,7 @@ import {
   chmodSync,
   existsSync,
   mkdirSync,
+  readdirSync,
   readFileSync,
   realpathSync,
   renameSync,
@@ -78,7 +79,11 @@ function mcpConfigMismatchMessage(root, existing, expected, key = MCP_KEY) {
 }
 
 /** Commands wired into the consumer's .claude/settings.json. */
-export const AUDIT_HOOK_CMD = "node node_modules/@godxjp/ui/scripts/audit-hook.mjs";
+// `npx --no-install` resolves @godxjp/ui up the node_modules chain, so the hook also works from a
+// workspace package whose install is hoisted to the repo root (gh#1296); it never downloads.
+export const AUDIT_HOOK_CMD = "npx --no-install @godxjp/ui audit-hook";
+/** The pre-#1296 default, rewritten to AUDIT_HOOK_CMD when found verbatim (a custom command is kept). */
+const LEGACY_AUDIT_HOOK_CMD = "node node_modules/@godxjp/ui/scripts/audit-hook.mjs";
 export const PRIMER_CMD = "cat .claude/godxjp-ui-workflow.md";
 
 /** What `.claude/settings.json` would get, used only for the `.godxjp-ui-suggested` sidecar. */
@@ -97,7 +102,12 @@ export const KIT_VERSION = readJson(join(SELF_ROOT, "package.json"))?.version ??
  * node_modules). Returns null when absent — caller falls back to this package's release train.
  */
 export function readConsumerUiMetadata(root) {
-  const uiPkg = readJson(join(root, "node_modules/@godxjp/ui/package.json"));
+  // Up the node_modules chain: a workspace package has @godxjp/ui hoisted to the repo root (gh#1296).
+  let uiPkg;
+  for (let dir = resolve(root); ; dir = dirname(dir)) {
+    uiPkg = readJson(join(dir, "node_modules/@godxjp/ui/package.json"));
+    if (uiPkg || dirname(dir) === dir) break;
+  }
   if (!uiPkg?.version) return null;
   return {
     version: String(uiPkg.version),
@@ -196,12 +206,14 @@ Follow this every time you create or change a page, component or form.
 - Screen composition (what the audit cannot see) is in \`.ai/rules/godxjp-ui.md\`.
 
 ## After JSX
-5. \`node node_modules/@godxjp/ui/scripts/ui-audit.mjs <files>\` — zero errors (a PostToolUse hook
-   also runs it on each edit).
+5. \`npx @godxjp/ui audit <files>\` — zero errors (a PostToolUse hook also runs it on each edit).
+   Run it from the package that owns the files; \`--help\` lists the flags.
 6. Screenshot at 390 / 768 / 1280 next to the exemplar, list the top 3 differences, fix them,
    repeat — at most 3 rounds.
-7. Before a visual review: \`node node_modules/@godxjp/ui/scripts/visual-audit.mjs <url>\`
-   (axe + contrast + layout).
+7. Before a visual review: \`npx @godxjp/ui visual-audit <url>\` (axe + contrast + layout).
+
+In a workspace, \`node_modules/@godxjp/ui\` may be hoisted to the repo root: read its files there,
+or through the MCP (\`get_design\`, \`get_rule\`).
 `;
 
 /** Delimited block appended to the consumer's CLAUDE.md — loaded into the agent's context
@@ -217,7 +229,7 @@ Before any JSX for a screen:
 3. \`get_exemplar\` (list | detail | form | settings | dashboard | approval) — match its structure.
 
 After building:
-4. \`node node_modules/@godxjp/ui/scripts/ui-audit.mjs <files>\` — zero errors.
+4. \`npx @godxjp/ui audit <files>\` — zero errors.
 5. Screenshot at 390 / 768 / 1280 beside the exemplar; fix the top 3 differences; max 3 rounds.
 
 Rules: \`node_modules/@godxjp/ui/docs/CONSUMER-RULES.md\`. Details: \`.claude/godxjp-ui-workflow.md\`.
@@ -523,7 +535,13 @@ export function ensureClaudeHooks(root) {
     (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")) {
+  for (const group of json.hooks.PostToolUse)
+    for (const hook of group.hooks ?? [])
+      if (hook.command === LEGACY_AUDIT_HOOK_CMD) {
+        hook.command = AUDIT_HOOK_CMD;
+        added.push("PostToolUse:auto-audit (workspace-safe command)");
+      }
+  if (!has(json.hooks.PostToolUse, "audit-hook")) {
     json.hooks.PostToolUse.push({
       matcher: "Write|Edit|MultiEdit",
       hooks: [{ type: "command", command: AUDIT_HOOK_CMD }],
@@ -692,16 +710,86 @@ export function guineaPigStamp() {
  * this one. The file says so at the top, because the first draft preserved nothing and silently
  * ate a note left inside it — measured, and the reason for that banner.
  */
-export function ensureConsumerRules(root) {
-  const uiDir = ["resources/js", "app/javascript", "src/components", "src", "app"].find((d) =>
+const UI_FILE = /\.(tsx|jsx)$/;
+const NOT_UI_DIR = new Set([
+  "node_modules",
+  "dist",
+  "build",
+  "out",
+  "vendor",
+  "coverage",
+  "public",
+  "storage",
+]);
+
+/** Does `dir` hold a .tsx/.jsx file within a few levels? Bounded, so a large tree costs little. */
+function holdsUi(dir, depth = 5) {
+  let entries;
+  try {
+    entries = readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return false;
+  }
+  if (entries.some((e) => e.isFile() && UI_FILE.test(e.name))) return true;
+  if (depth === 0) return false;
+  return entries.some(
+    (e) =>
+      e.isDirectory() &&
+      !e.name.startsWith(".") &&
+      !NOT_UI_DIR.has(e.name) &&
+      holdsUi(join(dir, e.name), depth - 1),
+  );
+}
+
+/**
+ * Every directory that actually holds the consumer's UI, as `paths:` globs without the `/**`
+ * (gh#1296). A fixed `src` never fired in an app whose screens live in `web/` or
+ * `resources/js/`, so the rules looked installed and loaded on no edit. Conventional nested roots
+ * first (`resources/js`, `apps/*\/src`, …), then any other top-level directory holding .tsx/.jsx.
+ * A repo with no UI files yet (a fresh scaffold) falls back to the first conventional directory
+ * that exists.
+ */
+function detectUiDirs(root) {
+  const subdirs = (rel) => {
+    try {
+      return readdirSync(join(root, rel), { withFileTypes: true })
+        .filter((e) => e.isDirectory() && !e.name.startsWith(".") && !NOT_UI_DIR.has(e.name))
+        .map((e) => e.name)
+        .sort();
+    } catch {
+      return [];
+    }
+  };
+  const found = [];
+  const add = (glob, dirs) => {
+    if (dirs.some((d) => holdsUi(join(root, d)))) found.push(glob);
+  };
+  for (const rel of ["resources/js", "app/javascript"]) add(rel, [rel]);
+  for (const parent of ["apps", "packages"]) {
+    const dirs = subdirs(parent)
+      .map((name) => `${parent}/${name}/src`)
+      .filter((d) => existsSync(join(root, d)));
+    if (dirs.length) add(`${parent}/*/src`, dirs);
+  }
+  for (const name of subdirs("")) {
+    if (!found.some((glob) => glob.split("/")[0] === name)) add(name, [name]);
+  }
+  if (found.length) return found;
+  const scaffold = ["resources/js", "app/javascript", "src/components", "src", "app"].find((d) =>
     existsSync(join(root, d)),
   );
-  if (!uiDir) return false;
+  return scaffold ? [scaffold] : [];
+}
+
+export function ensureConsumerRules(root) {
+  const uiDirs = detectUiDirs(root);
+  if (uiDirs.length === 0) return false;
+  const uiDir = uiDirs.join(", ");
 
   const dir = join(root, ".ai", "rules");
   const target = join(dir, "godxjp-ui.md");
   const body = readFileSync(join(SELF_ROOT, "scripts", "consumer-rule.md"), "utf8");
-  const front = `---\npaths:\n    - '${uiDir}/**'\n---\n\n`;
+  const front = `---\npaths:\n${uiDirs.map((d) => `    - '${d}/**'\n`).join("")}---\n\n`;
   // The digest covers the FRONT MATTER too: the detected glob is part of what makes this file
   // correct, and a repo that grows a `resources/js` after shipping with `src` needs the rewrite.
   const managed = `${front}${body}`;
@@ -745,7 +833,8 @@ export function ensureConsumerRules(root) {
     if (!cur.includes(".ai/rules/godxjp-ui.md")) {
       writeFileAtomic(
         index,
-        cur.replace(/\s*$/, "") + `\n| ${uiDir}/** | .ai/rules/godxjp-ui.md |\n`,
+        cur.replace(/\s*$/, "") +
+          `\n| ${uiDirs.map((d) => `${d}/**`).join(", ")} | .ai/rules/godxjp-ui.md |\n`,
       );
     }
   }
@@ -780,7 +869,9 @@ export function runSyncRules(root, { dryRun = false } = {}) {
     if (!refused && !(r === "present" && md === "present" && !wf && !skill && !rules)) {
       lines.push(
         `\n  @godxjp/ui → MCP in .mcp.json (${r}); workflow mandate in CLAUDE.md (${md}).\n` +
-          (rules ? `  common consumer rules in .ai/rules/godxjp-ui.md (glob ${rules}/**).\n` : "") +
+          (rules
+            ? `  common consumer rules in .ai/rules/godxjp-ui.md (UI dirs: ${rules}).\n`
+            : "") +
           (skill ? "  guinea-pig skill refreshed to this version (your section 8 kept).\n" : "") +
           "  Your agent now has live component + audit guidance. Restart it to pick up the MCP.\n" +
           "  For auto-audit on every edit (PostToolUse + SessionStart hooks):\n" +

package/scripts/cli.mjs

@@ -16,6 +16,7 @@ const HERE = dirname(fileURLToPath(import.meta.url));
 const MAP = {
   "init-agent": "init-agent-kit.mjs",
   audit: "ui-audit.mjs",
+  "audit-hook": "audit-hook.mjs",
   "visual-audit": "visual-audit.mjs",
   "prune-css": "prune-css.mjs",
   codemod: "codemod.mjs",
@@ -55,8 +56,14 @@ const HELP = {
                     fails rather than reporting clean when origin/main cannot be resolved
     --format json   machine-readable findings
     --quiet         print errors only (warnings hidden)
+    --base=<ref>    with --changed, diff against <ref> instead of origin/main
     --rules         print the rule catalog as JSON and exit
+    --consumer      inside the @godxjp/ui repo only: apply the consumer rules (always on in an app)
   Pre-commit:  npx godxjp-ui audit resources/js || exit 1`,
+  "audit-hook": `godxjp-ui audit-hook
+
+  The Claude Code PostToolUse hook init-agent wires in: reads the hook payload on stdin and audits
+  the .tsx file that was just written or edited, feeding findings back to the agent. Not for humans.`,
   "prune-css": `godxjp-ui prune-css <src dir/glob …> [--out <file>] [--fonts]
 
   Emit a stylesheet with only the component CSS layers your app uses (gh#971). Scans the given
@@ -95,6 +102,7 @@ commands:
   init-agent     install the agent forcing-kit (MCP + auto-audit hook + CLAUDE.md mandate)
   sync-rules     write/refresh package-owned agent rules (--dry-run previews)
   audit          static UI audit over source
+  audit-hook     the per-edit audit hook (wired by init-agent)
   visual-audit   runtime audit (Playwright + axe-core) against a running app
   prune-css      emit a stylesheet with only the CSS layers your app uses
 

package/scripts/consumer-rule.md

@@ -77,7 +77,7 @@ ngày: năm thứ cần đều ĐÃ CÓ và vẫn bị dựng lại bằng thứ
 | một hàng LÀ liên kết (thay cho nút rời)                          | `<ListRow asChild>`                                                                |
 | kẻ ô từng ngày trong lịch                                        | `<Calendar bordered>`                                                              |
 | dải giữa hai vùng, tự kẻ theo VỊ TRÍ                             | `<CardBar>` (`border` để ép khi xếp chồng)                                         |
-| chip "điều kiện đang bật" có dấu × để bỏ                         | `<Badge onRemove>` — KHÔNG phải `TagInput`                                         |
+| chip "điều kiện đang bật" có dấu × để bỏ                         | `<Badge onRemove>` — KHÔNG phải `Select mode="tags"`                               |
 | dải tab nằm TRONG đầu Card                                       | `<Card tabList activeTabKey onTabChange>`                                          |
 | tiêu đề / đoạn văn / liên kết trong văn bản                      | `<Heading level>` · `<Text as="p">` · `<Link>`                                     |
 | nút nổi góc màn (quay lên đầu, hành động nhanh)                  | `<FloatButton>`                                                                    |
@@ -91,11 +91,11 @@ ngày: năm thứ cần đều ĐÃ CÓ và vẫn bị dựng lại bằng thứ
 Lỗi không phải "đoán sai tên prop" mà là **cho rằng nó không tồn tại nên không
 hỏi**.
 
-## `AppProvider` là bắt buộc — thiếu nó, chuỗi của kit nói tiếng Việt
+## `AppProvider` là bắt buộc — thiếu nó, chuỗi của kit không theo ngôn ngữ của app
 
 Mount `<AppProvider defaultLocale="ja">` MỘT lần ở gốc app. Thiếu nó, chuỗi của chính kit (nút
-đóng/hủy/xóa của dialog, upload, badge đếm, nhãn picker) rơi về locale nghỉ `vi` và picker rơi về
-UTC — godx-mailer đo được nút tiếng Việt giữa UI tiếng Nhật, không một cảnh báo (gh#1005). Bản dev
+đóng/hủy/xóa của dialog, upload, badge đếm, nhãn picker) rơi về locale nghỉ — `<html lang>` nếu
+locale đó đã đăng ký, không thì `en` — và picker rơi về UTC (gh#1005). Bản dev
 giờ cảnh báo MỘT lần khi component của kit render ngoài provider. Không mount được provider thì gọi
 `syncI18nLocale(locale, fallback)` lúc khởi động.
 
@@ -104,11 +104,11 @@ giờ cảnh báo MỘT lần khi component của kit render ngoài provider. Kh
 godx-mailer dính bốn lỗi form trong một ngày, cả bốn đều là kit ĐÃ CÓ đồ đúng
 (gh#998). Giờ ui-audit chặn:
 
-| Sai                                                         | Đúng                                                                                         | rule                   |
-| ----------------------------------------------------------- | -------------------------------------------------------------------------------------------- | ---------------------- |
-| ≥2 `FormField` không có `Form`, hoặc xếp hàng bằng `<Flex>` | `<Form layout="horizontal" labelWidth controlWidth>`; hàng = `SpaceCompact` / `Form columns` | `formfield-needs-form` |
-| ≥3 `FormField` trong `DialogBody`                           | page riêng (route riêng)                                                                     | `dialog-form-too-big`  |
-| `Select` hai lựa chọn kéo full width                        | `controlWidth` trên field hoặc một lần trên `Form`                                           | `select-width-hint`    |
+| Sai                                                         | Đúng                                                                                            | rule                   |
+| ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------- | ---------------------- |
+| ≥2 `FormField` không có `Form`, hoặc xếp hàng bằng `<Flex>` | `<Form layout="horizontal" labelWidth controlWidth>`; hàng = `<Flex attached>` / `Form columns` | `formfield-needs-form` |
+| ≥3 `FormField` trong `DialogBody`                           | page riêng (route riêng)                                                                        | `dialog-form-too-big`  |
+| `Select` hai lựa chọn kéo full width                        | `controlWidth` trên field hoặc một lần trên `Form`                                              | `select-width-hint`    |
 
 Ca kit không diễn đạt được thì **mở issue ở godx-jp/godxjp-ui**, tạm dùng cách
 hợp lệ gần nhất kèm `// TODO(godxjp-ui#<n>)` — không tự chế.

package/scripts/ui-audit.mjs

@@ -7,7 +7,7 @@
  */
 import { spawnSync } from "node:child_process";
 import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
-import { isAbsolute, join, relative } from "node:path";
+import { dirname, isAbsolute, join, relative } from "node:path";
 
 const CWD = process.cwd();
 const SELF = (() => {
@@ -18,6 +18,29 @@ const SELF = (() => {
   }
 })();
 const args = process.argv.slice(2);
+
+// Before anything reads the arguments: `--help` used to be filtered out as a flag and ran a full
+// audit of the working directory instead (gh#1296).
+if (args.includes("--help") || args.includes("-h")) {
+  console.log(`usage: ui-audit [dir|file …] [--changed [--base=<ref>]] [--format json] [--quiet]
+       ui-audit --rules
+
+Static UI-standardization audit of @godxjp/ui consumer source. Exits 1 on any error.
+Run it from the package that owns the files (a workspace package works; the installed
+@godxjp/ui is found up the node_modules chain). Same as: npx @godxjp/ui audit …
+
+  dir|file …      what to scan (default: the conventional UI directories under the cwd)
+  --changed       scan what this branch changed (committed, staged, untracked)
+  --base=<ref>    the base for --changed (default origin/HEAD, then origin/main)
+  --format json   machine-readable findings
+  --quiet         errors only
+  --rules         print the rule catalog as JSON and exit
+  --consumer      library repo only: apply the consumer rules inside @godxjp/ui itself.
+                  A consumer app never needs it; there those rules always apply.
+  -h, --help      this text`);
+  process.exit(0);
+}
+
 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");
@@ -1899,13 +1922,20 @@ function staleOwnedRules() {
   const contents = readFileSync(target, "utf8");
   const stamped = /<!-- godxjp-ui:version ([^\s]+) -->/.exec(contents)?.[1];
 
+  // Up the node_modules chain, as Node resolves it: a workspace package has its @godxjp/ui hoisted
+  // to the repo root, and reading only `CWD/node_modules` reported a correct install as
+  // `owned-rules-unknown` (gh#1296). The package's `exports` map does not expose package.json,
+  // so `require.resolve` cannot do this walk for us.
   let installed;
-  try {
-    installed = JSON.parse(
-      readFileSync(join(CWD, "node_modules", "@godxjp", "ui", "package.json"), "utf8"),
-    ).version;
-  } catch {
-    installed = undefined;
+  for (let dir = CWD; installed === undefined; dir = dirname(dir)) {
+    try {
+      installed = JSON.parse(
+        readFileSync(join(dir, "node_modules", "@godxjp", "ui", "package.json"), "utf8"),
+      ).version;
+    } catch {
+      // Not here — keep walking.
+    }
+    if (dirname(dir) === dir) break;
   }
 
   if (!stamped || !installed) {