@godxjp/ui 32.5.0 → 32.7.0

package/scripts/consumer-rule.md

@@ -1,39 +1,33 @@
 # @godxjp/ui
 
-> **Tệp này do gói `@godxjp/ui` sở hữu.** Cài gói không tự ghi gì cả: nội dung chỉ được ghi lại
-> khi bạn chạy `npx godxjp-ui sync-rules` (thêm `--dry-run` để xem trước). Chạy lại sau mỗi lần
-> nâng cấp. Dấu `<!-- godxjp-ui:version -->` luôn được đồng bộ với phiên bản
-> gói đang cài — kể cả khi thân tệp không đổi giữa hai bản.
-> Đừng sửa ở đây — luật của riêng kho thuộc về một tệp khác trong `.ai/rules/`,
-> và index sẽ nạp cả hai. (Khác với `.claude/skills/.../SKILL.md`, nơi mục §8
-> trở đi là của kho và được giữ lại.)
-
-Đây là **danh sách kiểm** bắn mỗi lần chạm một tệp UI. Lý do đầy đủ nằm ở
-`docs/CONSUMER-RULES.md` (10 luật) và, với kho chuột bạch, ở
-`.claude/skills/godx-ui-guinea-pig/SKILL.md`.
-
-## Loading styles: one entry, fonts are opt-in
-
-```ts
-import "@godxjp/ui/styles.css"; // precompiled, no Tailwind needed
-```
+> **Tệp do gói `@godxjp/ui` sở hữu**, ghi lại mỗi lần chạy `npx godxjp-ui sync-rules`. Đừng sửa ở
+> đây — luật riêng của kho thuộc về một tệp khác trong `.ai/rules/`.
+
+Danh sách kiểm bắn mỗi lần chạm một tệp UI. Luật đầy đủ: `docs/CONSUMER-RULES.md`.
+
+## Styles và theme
 
 ```css
-@import "@godxjp/ui/styles"; /* Tailwind v4: every component layer, NO font files */
-@import "@godxjp/ui/styles/fonts.css"; /* optional, after the styles import: the bundled faces */
+@import "@godxjp/ui/styles"; /* or: import "@godxjp/ui/styles.css" — no Tailwind needed */
 ```
 
-Since v32 the styles entry no longer bundles fonts. A Japanese app that wants the bundled faces
-installs them and adds the fonts import (the GoDX preset does both for you):
+Fonts are opt-in (`@godxjp/ui/styles/fonts.css`, after the styles import). Never cherry-pick
+`*-layout.css` layers. The default `--primary` is a neutral placeholder: set `--primary` once in
+your theme, or import a preset (`@godxjp/ui/themes/godx.css`). Details: `docs/CUSTOMER-THEMING.md`.
 
-```bash
-pnpm add @fontsource/noto-sans-jp @fontsource/m-plus-2
-```
+## Screen composition (ui-audit không thấy những lỗi này)
 
-An app that supplies its own face (next/font, self-host, a system stack) skips the fonts import and
-names its face with `--font-sans-base`. Never cherry-pick individual `*-layout.css` layers: that
-breaks the layer-order contract, which is not the same thing as choosing an entry point. Reasons
-and measurements are in `docs/CUSTOMER-THEMING.md`.
+- Most sections are a `Heading` + content, NOT a `Card`. A Card is for a genuinely separate
+  surface (a table, a form block), never a frame around every section.
+- No `subtitle` that restates the `title`. Leave it out unless it adds a fact.
+- Filters sit ABOVE the table they filter, never after it.
+- KPI tiles (`StatCard`) only on dashboards, 3–4 at most. A list page opens with its list.
+- `EmptyState` = one sentence + one action. Inside a Card it has no icon.
+- `Alert` only for something the user must act on now; not a page decoration.
+- Tiers / categories / roles render in ONE neutral tone (`<Badge variant="outline">`); colour
+  is for status.
+- Vary spacing by level: `xs` inside a group, `sm` within a row, `md` between items, `lg`
+  between blocks. One gap everywhere reads as generated.
 
 ## Bố cục chuẩn của platform: BA CỘT, và ba cột là BA PHẠM VI
 
@@ -83,13 +77,12 @@ 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                      | `<Title>` · `<Paragraph>` · `<Link>` (`Text` 33 prop)                              |
+| 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>`                                                                    |
 | khung xương của một FORM khi đang tải                            | `<SkeletonForm>`                                                                   |
 | ô màu chỉ để xem, màu do NGƯỜI DÙNG chọn                         | `<Swatch>`                                                                         |
-| ảnh đại diện của một tệp / bản xem trước                         | `<Thumbnail>`                                                                      |
 | danh sách "có gì trong gói này"                                  | `<FeatureList>`                                                                    |
 | panel kéo giãn được (chia đôi màn)                               | `<DraggablePanel>`                                                                 |
 | màn hội thoại AI                                                 | `<Welcome>` · `<Conversations>` · `<Attachments>` · `<ThoughtChain>` · `<Actions>` |
@@ -98,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.
 
@@ -111,57 +104,28 @@ 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ế.
 
-## Dialog và AlertDialog là MỘT họ — `variant` là lối chuẩn
-
-Đừng với tay sang 12 export `AlertDialog*` nữa. Chúng **vẫn chạy y như cũ** (gỡ
-là breaking change) nhưng là **LỐI CŨ**: đo được 26 export với **12 cặp trùng
-tên** và **0** phần chỉ `AlertDialog` mới có. antd — thẩm quyền bề mặt prop của
-gói này — chỉ có MỘT `Modal`, và mức nguy hiểm ở đó là một PROP.
+## Xác nhận nguy hiểm: `Dialog variant="destructive"`
 
 ```tsx
-<DialogContent variant="destructive">   {/* thay cho <AlertDialogContent> */}
+<DialogContent variant="destructive">   {/* không dùng họ AlertDialog* — lối cũ */}
 ```
 
-Một prop ấy quyết định ba thứ đi cùng nhau: `role="alertdialog"`, click ra ngoài
-KHÔNG đóng, nút chính nhấn mạnh destructive (và ✕ mặc định tắt). Esc VẪN đóng —
-y như `AlertDialogContent` trước nay. Đặt `variant` ở `DialogRoot` thì cả cây kế
-thừa.
-
-## antd là CHUẨN — thiếu gì thì port 100%, đừng tự thiết kế
-
-`docs/DESIGN-AUTHORITY.md` của gói: **nơi antd đặt tên cho một năng lực, gói này
-lấy nguyên tên và nguyên ngữ nghĩa của antd.** Một năng lực còn thiếu được port
-từ antd **100% TRƯỚC** — tên, prop, ngữ nghĩa — rồi mới cải tiến. Không thiết kế
-lại trước, không port một nửa.
-
-Nghĩa là với consumer: thấy thiếu prop thì **mở issue kèm tên antd của nó**
-(`sorter`, `closable`, `okType`…), đừng đề xuất một cái tên mới và đừng tự vẽ
-lại bằng class tiện ích. Ba trục cố ý lệch khỏi antd đều đã ghi lý do trong
-DESIGN-AUTHORITY (logical thay cho `left/right`, từ vựng giá trị của gói này,
-`density` thay cho `size`) — lệch thêm thì phải viết ra ở đó.
-
-## Catalog giờ chở CẢ luật bố cục — nhưng phải hỏi mới có
-
-Mục này từng nói "catalog chở PROP, không chở LUẬT BỐ CỤC", với `CardBar` làm
-bằng chứng: một prop (`extra`), không dòng nào nói nó tự kẻ theo vị trí. **Bằng
-chứng ấy đã hết đúng.** `CardBar` nay có 6 prop, trong đó `border` (`"none" |
-"block-start" | "block-end" | "both"`) ép được đường kẻ khi xếp chồng, và cả
-`Card` lẫn `CardBar` trong catalog đều nói ra luật vị trí (đầu: kẻ dưới · cuối:
-kẻ trên · giữa: cả hai).
-
-Nên luật hiện hành là: **hỏi `get_component` trước** — nay nó thường trả lời cả
-hình dạng lẫn luật. Còn khi `usage`/`description` im lặng về bố cục thì mới mở
-`node_modules/@godxjp/ui/src/styles/*-layout.css` của component ấy ra đọc; chú
-thích trong đó vẫn là bản đầy đủ nhất.
+Một prop: `role="alertdialog"`, click ra ngoài không đóng, nút chính nhấn mạnh destructive.
+Thiếu prop thì mở issue kèm tên antd của nó (`docs/DESIGN-AUTHORITY.md`), đừng tự đặt tên.
+
+## Luật bố cục: hỏi `get_component` trước
+
+`usage`/`description` thường nói cả luật vị trí (vd. `CardBar` tự kẻ theo vị trí, `border` để
+ép). Khi catalog im lặng thì mới đọc `node_modules/@godxjp/ui/src/styles/*-layout.css`.
 
 ## Card không lồng Card
 

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");
@@ -295,6 +318,22 @@ const isAsChildSlot = (content, index) => {
 const rawTagOutsideAsChildSlot = (tag) => (content) =>
   [...content.matchAll(rawTag(tag))].filter((match) => !isAsChildSlot(content, match.index));
 
+/*
+ * ADMIN-SCREEN TELLS (gh#1294). Consumer screens built only from correct primitives still read as
+ * generated, through structure: a Card per section, a Card in a Card, a KPI tile row above a
+ * list, an icon EmptyState inside a Card, a wall of Badges or Alerts. Each is sometimes right, so
+ * these are WARNINGS. The per-file limits were set from four consumer repos (ql, platform,
+ * godx-task, godx-content: 511 files importing @godxjp/ui, 2026-10-14) to flag the densest
+ * ~10–15% of the files that use the tag at all:
+ *   Card   ≥5 → 43 of 336 files (12.8%)
+ *   Badge  ≥5 → 28 of 211 (13.3%)
+ *   Alert  ≥4 → 27 of 200 (13.5%)
+ */
+const CARD_LIMIT = 5;
+const BADGE_LIMIT = 5;
+const ALERT_LIMIT = 4;
+const STATCARD_ROW = 3;
+
 /**
  * @type {{id:string, severity:'error'|'warn', test:RegExp, message:string, standard?:string,
  *         exempt?:RegExp, classOnly?:boolean}[]}
@@ -915,6 +954,64 @@ const RULES = [
     message:
       "Buttons in one row mix sizes — every Button under one parent takes the same `size` (a missing size is `default`; `icon-sm` pairs with `sm`, `icon-xs` with `xs`, `icon` with default). Pick the row's size and apply it to every button in it (docs/CONSUMER-RULES.md §5).",
   },
+  // Admin-screen tells (gh#1294) — structure, not decoration; limits measured, see CARD_LIMIT.
+  {
+    id: "nested-card",
+    replacement: "Heading + Flex inside the one Card",
+    scope: "consumer",
+    severity: "warn",
+    spansElement: true,
+    matches: nestedCardMatches,
+    message:
+      "A Card (or StatCard) inside a Card — two borders for one boundary. Group inside the outer Card with a Heading and Flex/Separator; keep Card for a real surface boundary.",
+  },
+  {
+    id: "card-per-section",
+    replacement: "Heading + Flex direction=col per section",
+    scope: "consumer",
+    severity: "warn",
+    spansElement: true,
+    matches: (source) => densityMatches(source, ["Card"], CARD_LIMIT),
+    message: `${CARD_LIMIT}+ Cards in one file — a Card per section. Mark sections with a Heading and section spacing (PageContainer children, Flex gap="lg"); keep Card for a real boundary (a table surface, a selectable item).`,
+  },
+  {
+    id: "kpi-row-off-dashboard",
+    replacement: "drop the StatCard row; put counts in the table header or Pagination total",
+    scope: "consumer",
+    severity: "warn",
+    spansElement: true,
+    matches: kpiRowMatches,
+    message: `${STATCARD_ROW}+ StatCards outside a dashboard — a row count is not a KPI. Keep StatCard rows for a dashboard with comparison or trend (delta); a list shows its total in Pagination showTotal.`,
+  },
+  {
+    id: "empty-state-icon-in-card",
+    replacement: 'EmptyState title + action, no icon (or variant="compact")',
+    scope: "consumer",
+    severity: "warn",
+    spansElement: true,
+    matches: emptyStateIconInCardMatches,
+    message:
+      'An icon EmptyState inside a Card. In an admin surface an empty state is one sentence and one action: drop `icon`, or use variant="compact".',
+  },
+  {
+    id: "badge-wall",
+    replacement: "plain text for categories; Badge only for status",
+    scope: "consumer",
+    severity: "warn",
+    spansElement: true,
+    matches: (source) => densityMatches(source, ["Badge", "Tag"], BADGE_LIMIT),
+    message: `${BADGE_LIMIT}+ Badge/Tag in one file. Badge is for status; render categories, tiers and scopes as plain text, and keep one status column per table.`,
+  },
+  {
+    id: "alert-per-page",
+    replacement:
+      "one Alert for the page's blocking state; inline FormField errors and toasts for the rest",
+    scope: "consumer",
+    severity: "warn",
+    spansElement: true,
+    matches: (source) => densityMatches(source, ["Alert"], ALERT_LIMIT),
+    message: `${ALERT_LIMIT}+ Alerts in one file. An Alert is for a state that blocks or changes the task; field errors belong in FormField, results in a toast, and standing info in plain text.`,
+  },
 ];
 
 /**
@@ -1554,9 +1651,11 @@ const BUTTON_ROW_TRANSPARENT = new Set([
   "TooltipTrigger",
 ]);
 
-/** A Button's `size` literal from its OPENING tag's own attributes (not a nested element's). */
-function buttonSizeOf(openTag) {
-  // Blank every `{…}` body so `icon={<Plus size="sm" />}` cannot answer for the Button.
+/**
+ * An opening tag with every `{…}` body blanked (the `{` kept), so `icon={<Plus size="sm" />}`
+ * cannot answer for the element that owns the attribute.
+ */
+function topLevelAttrs(openTag) {
   let top = "";
   let depth = 0;
   let quote = "";
@@ -1573,7 +1672,12 @@ function buttonSizeOf(openTag) {
     top += depth ? (ch === "{" && depth === 1 ? "{" : " ") : ch;
     if (ch === "}") depth--;
   }
-  const at = /\bsize\s*=\s*/.exec(top);
+  return top;
+}
+
+/** A Button's `size` literal from its OPENING tag's own attributes (not a nested element's). */
+function buttonSizeOf(openTag) {
+  const at = /\bsize\s*=\s*/.exec(topLevelAttrs(openTag));
   if (!at) return "default";
   const rest = openTag.slice(at.index + at[0].length);
   const lit = /^(?:"([^"]*)"|'([^']*)'|\{\s*(?:"([^"]*)"|'([^']*)'|`([^`$]*)`)\s*\})/.exec(rest);
@@ -1587,15 +1691,14 @@ const buttonSizeFamily = (size) => {
 };
 
 /**
- * `mixed-button-size`: group every <Button> by its nearest non-transparent JSX parent and yield
- * one match per group whose size families differ. A tag stack over the whole file; an element in
- * an attribute (`actions={<>…</>}`) gets the attribute's owner as its parent, kept apart from the
- * owner's children. A `<` glued to an identifier outside JSX children is a TS generic.
+ * Every JSX opening tag in the file, with the stack of elements open around it. A tag stack over
+ * the whole file; an element in an attribute (`actions={<>…</>}`) gets the attribute's owner as an
+ * `attr: true` frame, kept apart from the owner's children. A `<` glued to an identifier outside
+ * JSX children is a TS generic. `stack` is live: read it before asking for the next element.
  */
-function* mixedButtonSizeMatches(source) {
+function* jsxElements(source) {
   const stack = []; // { tag, id, attr }
   const pending = []; // opening tags whose attributes are still being scanned
-  const groups = new Map();
   let nextId = 0;
   const settle = (upTo) => {
     while (pending.length && pending.at(-1).end < upTo) {
@@ -1625,21 +1728,31 @@ function* mixedButtonSizeMatches(source) {
     const end = jsxOpeningEnd(source, m.index);
     if (end >= source.length) continue;
     const openTag = source.slice(m.index, end + 1);
-    if (tag === "Button") {
-      const parent = stack.findLast((f) => f.attr || !BUTTON_ROW_TRANSPARENT.has(f.tag));
-      const size = buttonSizeOf(openTag);
-      if (parent && size !== null) {
-        (groups.get(parent.id) ?? groups.set(parent.id, []).get(parent.id)).push({
-          size,
-          index: m.index,
-          openTag,
-        });
-      }
-    }
+    yield { tag, index: m.index, openTag, stack };
     const frame = { tag, id: nextId++, attr: true };
     stack.push(frame);
     pending.push({ end, frame, selfClose: /\/\s*>$/.test(openTag) });
   }
+}
+
+/**
+ * `mixed-button-size`: group every <Button> by its nearest non-transparent JSX parent and yield
+ * one match per group whose size families differ.
+ */
+function* mixedButtonSizeMatches(source) {
+  const groups = new Map();
+  for (const { tag, index, openTag, stack } of jsxElements(source)) {
+    if (tag !== "Button") continue;
+    const parent = stack.findLast((f) => f.attr || !BUTTON_ROW_TRANSPARENT.has(f.tag));
+    const size = buttonSizeOf(openTag);
+    if (parent && size !== null) {
+      (groups.get(parent.id) ?? groups.set(parent.id, []).get(parent.id)).push({
+        size,
+        index,
+        openTag,
+      });
+    }
+  }
   for (const group of groups.values()) {
     const families = new Set(group.map((b) => buttonSizeFamily(b.size)));
     if (group.length < 2 || families.size < 2) continue;
@@ -1650,6 +1763,46 @@ function* mixedButtonSizeMatches(source) {
   }
 }
 
+/** One finding per file, at the `limit`-th occurrence of any tag in `tags`, naming the count. */
+function* densityMatches(source, tags, limit) {
+  const hits = [];
+  for (const { tag, index } of jsxElements(source)) if (tags.includes(tag)) hits.push(index);
+  if (hits.length >= limit) yield { 0: `${hits.length} in this file`, index: hits[limit - 1] };
+}
+
+/** A Card or StatCard opened while another Card is open, in children or in an attribute. */
+function* nestedCardMatches(source) {
+  for (const { tag, index, openTag, stack } of jsxElements(source)) {
+    if ((tag === "Card" || tag === "StatCard") && stack.some((f) => f.tag === "Card")) {
+      yield { 0: openTag, index };
+    }
+  }
+}
+
+/** ≥3 StatCards in a file whose path does not say it is a dashboard. */
+function* kpiRowMatches(source, rel = "") {
+  if (/dashboard/i.test(rel)) return;
+  yield* densityMatches(source, ["StatCard"], STATCARD_ROW);
+}
+
+/** An EmptyState that draws an icon (not `icon={null}`, not compact) inside a Card. */
+function* emptyStateIconInCardMatches(source) {
+  for (const { tag, index, openTag, stack } of jsxElements(source)) {
+    if (tag !== "EmptyState" || !stack.some((f) => f.tag === "Card" || f.tag === "CardContent")) {
+      continue;
+    }
+    const top = topLevelAttrs(openTag);
+    const icon = /\bicon\s*=\s*/.exec(top);
+    if (!icon || /^\{\s*(?:null|undefined)\s*\}/.test(openTag.slice(icon.index + icon[0].length))) {
+      continue;
+    }
+    const variant = /\bvariant\s*=\s*/.exec(top);
+    const rest = variant ? openTag.slice(variant.index + variant[0].length) : "";
+    if (/^(?:"compact"|'compact'|\{\s*["'`]compact["'`]\s*\})/.test(rest)) continue;
+    yield { 0: openTag, index };
+  }
+}
+
 // 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>).
@@ -1769,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) {
@@ -2065,7 +2225,7 @@ for (const dir of SCAN_DIRS) {
     for (const rule of fileRules) {
       if (!rule.spansElement || !isJsx) continue;
       for (const match of rule.matches
-        ? rule.matches(scanContent)
+        ? rule.matches(scanContent, rel)
         : scanContent.matchAll(rule.test)) {
         // A comparison `>` inside a JSX prop is not the end of its opening tag.
         if (