@godxjp/ui 33.22.2 → 33.25.0

package/dist/tokens/components/badge.css

@@ -13,6 +13,9 @@
   --badge-min-height: initial;
   --badge-outline-foreground: initial;
 
+  --badge-agent-border: initial;
+  --badge-agent-foreground: initial;
+
   --badge-icon-size: var(--icon-size-xs);
 
   --badge-space-x-removable: var(--space-1);

package/dist/tokens/components/control.css

@@ -321,6 +321,9 @@
 
   --select-content-max-height: 24rem;
 
+  --select-content-max-width: 32rem;
+  --select-content-viewport-inset: var(--space-6);
+
   --select-content-inline-size: auto;
 
   --select-content-background: initial;

package/dist/tokens/components/data-display.css

@@ -144,6 +144,15 @@
   --avatar-presence-busy-color: initial;
   --avatar-presence-offline-color: initial;
 
+  --avatar-agent-font-size: initial;
+  --avatar-agent-font-weight: initial;
+  --avatar-agent-padding-inline: initial;
+  --avatar-agent-inset: initial;
+  --avatar-agent-ring-width: initial;
+  --avatar-agent-background: initial;
+  --avatar-agent-foreground: initial;
+  --avatar-agent-ring-color: initial;
+
   --progress-track-background: initial;
   --progress-track-background-alpha: initial;
   --progress-fill-background: initial;

package/dist/tokens/components/editorial.css

@@ -208,7 +208,7 @@
   --editorial-search-border-color: initial;
 
   --editorial-search-background: initial;
-  --editorial-search-shadow: 0 4px 16px rgb(var(--shadow-color, 0 0 0) / 0.06);
+  --editorial-search-shadow: initial;
   --editorial-search-icon-size: var(--icon-size-lg);
 
   --editorial-search-scope-font-weight: inherit;
@@ -232,7 +232,7 @@
   --editorial-search-popup-max-height: min(32rem, 70vh);
   --editorial-search-popup-padding-block: calc(var(--space-1) + 0.125rem);
   --editorial-search-popup-radius: var(--radius);
-  --editorial-search-popup-shadow: 0 12px 32px rgb(var(--shadow-color, 0 0 0) / 0.12);
+  --editorial-search-popup-shadow: initial;
 
   --editorial-search-popup-border-color: initial;
 
@@ -317,7 +317,7 @@
   --editorial-showcase-caption-gap: calc(var(--space-3) + 0.0625rem);
   --editorial-showcase-caption-min-width: 16.25rem;
   --editorial-showcase-caption-radius: var(--radius);
-  --editorial-showcase-caption-shadow: 0 4px 16px rgb(var(--shadow-color, 0 0 0) / 0.06);
+  --editorial-showcase-caption-shadow: initial;
 
   --editorial-showcase-caption-icon-size: calc(var(--icon-size-xl) + 0.25rem);
 
@@ -365,7 +365,7 @@
   --editorial-banner-media-align: start;
 
   --editorial-catalog-card-radius: var(--radius);
-  --editorial-catalog-card-hover-shadow: 0 10px 28px rgb(var(--shadow-color, 0 0 0) / 0.1);
+  --editorial-catalog-card-hover-shadow: initial;
   --editorial-catalog-card-hover-translate: -3px;
   --editorial-catalog-card-media-aspect-size: 1 / 1.05;
   --editorial-catalog-card-media-padding-block-start: var(--space-12);
@@ -450,7 +450,7 @@
   --editorial-spotlight-media-inset-block-start: 2rem;
   --editorial-spotlight-media-offset-angle: 12deg;
   --editorial-spotlight-media-shadow: 0 6px 6px rgb(40 25 20 / 0.12);
-  --editorial-spotlight-hover-shadow: 0 4px 16px rgb(var(--shadow-color, 0 0 0) / 0.06);
+  --editorial-spotlight-hover-shadow: initial;
 
   --editorial-journal-cover-height: 13.25rem;
 
@@ -490,7 +490,7 @@
   --editorial-journal-arrow-size: 2rem;
   --editorial-journal-arrow-icon-size: var(--icon-size-md);
   --editorial-journal-focus-offset: -4px;
-  --editorial-journal-hover-shadow: 0 12px 28px rgb(var(--shadow-color, 0 0 0) / 0.08);
+  --editorial-journal-hover-shadow: initial;
 
   --editorial-masthead-height: 5.5rem;
   --editorial-masthead-gap: var(--space-8);
@@ -603,6 +603,9 @@
   --editorial-catalog-detail-art-height: auto;
   --editorial-catalog-detail-art-max-width: none;
   --editorial-catalog-detail-art-padding: var(--space-10);
+  --editorial-catalog-detail-loading-background: initial;
+  --editorial-catalog-detail-loading-duration: var(--duration-loop);
+  --editorial-catalog-detail-loading-alpha: 0.5;
   --editorial-catalog-detail-art-radius: calc(var(--radius) * 2);
   --editorial-catalog-detail-media-width: 15.625rem;
   --editorial-catalog-detail-media-height: 22.5rem;

package/dist/tokens/components/shell.css

@@ -100,6 +100,8 @@
   --app-shell-bar-inset-compact: var(--space-page-compact-x);
   --app-shell-bar-gap: var(--space-3);
 
+  --app-shell-rail-gap: var(--space-3);
+
   --app-shell-brand-max-inline-size: none;
   --app-shell-brand-compact-max-inline-size: var(--app-shell-bar-height);
 

package/dist/tokens/foundation.css

@@ -41,6 +41,10 @@
   --attention: 25 99% 46%;
   --attention-foreground: 48 8% 13%;
 
+  --agent: 262 83% 58%;
+  --agent-foreground: 0 0% 100%;
+  --text-agent: 263 70% 50%;
+
   --brand: 240 6% 10%;
   --brand-foreground: 60 33% 99%;
 
@@ -383,6 +387,10 @@
     --attention: 25 95% 56%;
     --attention-foreground: 48 9% 9%;
 
+    --agent: 262 83% 58%;
+    --agent-foreground: 0 0% 100%;
+    --text-agent: 252 95% 85%;
+
     --brand: 0 0% 98%;
     --brand-foreground: 48 9% 9%;
 

package/docs/CONSUMER-RULES.md

@@ -4,10 +4,37 @@ 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`.
+
+   **Supported opt-out for Tailwind v4 (#1475):** replace `@import "@godxjp/ui/styles"` with
+   `@import "@godxjp/ui/styles/application"` in apps that render no editorial, catalog or holding
+   components. It retains foundation, shell, controls, tables, forms, navigation, charts and vendor
+   styles. `styles` and `styles/core` retain every family for compatibility. If editorial components
+   are added later, return to `styles`, or import `styles/editorial` after `styles/application`.
+   `styles/editorial` is additive: it requires the application entry. All entries bring no bundled fonts.
+
+   For a smaller, content-aware build, run the package-owned pruner instead of guessing layers:
+
+   ```sh
+   npx @godxjp/ui prune-css "src/**/*.tsx" --exclude-family editorial --out src/godx-ui.css
+   ```
+
+   Import the generated file instead of `@godxjp/ui/styles`; keep your Tailwind `@source` declarations.
+   The optional `--exclude-family editorial` fails if a detected component needs that family. Named
+   imports are required for a useful slice; namespace/dynamic imports conservatively retain all layers.
+   Both the family entries and the pruner use the generated `styles/layers.json` dependency map.
+   Re-run after component imports change and after upgrading the package. Never edit generated imports.
+
+   **Without Tailwind (#1455):** use the same command with `--precompiled`. The generated file
+   resolves package-owned plain CSS slices through public exports; bundle its CSS imports with your
+   existing CSS bundler (Vite, webpack or esbuild). It requires no Tailwind compiler. A browser alone
+   cannot resolve npm package specifiers. Fonts stay opt-in (`--fonts`). The packed-contract gate
+   installs the tarball outside the repository and builds both modes; reproduce its measured byte
+   counts with `pnpm build && node scripts/check-packed-css-pruning.mjs`.
+
 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>`. A list's filters are ONE `<FilterBar>` that wraps at every width — never a sideways-scrolling strip of filters or filter chips; past 2–4 filters the rest go behind one "More filters" `Sheet` (cardinal rule #51, pattern `list-filters`, audit rules `filter-bar-no-overflow`, `filter-strip-no-scroll` and `hand-rolled-filter-bar`). Filters are packed at the start: never a hand-built `<Flex justify="between">` of FormFields above a table. Many conditions or an explicit 検索 button → `SearchForm` (pattern `search-form`); field × operator rows saved as views → pattern `condition-builder`.
 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 `<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).
+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>`** — 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>`). `layout="horizontal"` with `labelWidth`/`controlWidth` is the desktop default; `layout="vertical"` (labels above the inputs, as GOV.UK and the W3C WAI forms tutorial show) is equally valid when labels are long, the container is narrow, or the page asks one short question per row (gh#1496). Size each control for its content with `controlWidth` (GOV.UK text-input width: a port ~7rem, a short enum ~10rem). **GoDX house rule:** a form with three or more fields is its own page, not a Dialog (audit `dialog-form-too-big`) — a product decision for task focus and recovery, not a WCAG requirement. 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]`.
@@ -54,3 +81,11 @@ information belongs on the screen:
 If the control is disabled _pending something the user can fix_, prefer leaving it enabled and
 explaining on submit: an inert control with a paragraph beside it is often a validation message
 wearing a disguise.
+
+## Floating content and toast imports
+
+Use `DropdownMenuContent` only for menu collection nodes (`DropdownMenuItem`, checkbox/radio items, groups, labels and separators). Arbitrary notification headers, lists and links use `Popover` + `ListRow`. Development diagnostics and `dropdown-menu-non-menu-children` identify unsupported DOM children. Opaque components returning menu items remain supported.
+
+`PopoverContent` scrolls automatically when the available viewport height caps it; focus rings stay inside the scroll boundary, including `flush` content.
+
+Always use `import { toast } from "@godxjp/ui"` (or `@godxjp/ui/feedback`) with the kit's `Toaster`. Do not import toast directly from `sonner`: an app-installed version can create a separate toast store and calls never reach the kit's Toaster. The `no-direct-sonner-import` audit rule flags runtime imports. Sonner remains a dependency; no peer dependency migration is required.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@godxjp/ui",
-  "version": "33.22.2",
-  "godxUiMcp": "33.22.2",
+  "version": "33.25.0",
+  "godxUiMcp": "33.25.0",
   "license": "Apache-2.0",
   "repository": {
     "type": "git",
@@ -81,6 +81,8 @@
       "import": "./dist/lab/index.js"
     },
     "./styles": "./dist/styles/index.css",
+    "./styles/application": "./dist/styles/application.css",
+    "./styles/editorial": "./dist/styles/editorial.css",
     "./styles/core": "./dist/styles/core.css",
     "./styles/core-with-fallbacks": "./dist/styles/core-with-fallbacks.css",
     "./styles/core-with-jis-level1": "./dist/styles/core-with-jis-level1.css",

package/scripts/consumer-rule.md

@@ -109,7 +109,7 @@ godx-mailer dính bốn lỗi form trong một ngày, cả bốn đều là kit
 
 | 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` |
+| ≥2 `FormField` không có `Form`, hoặc xếp hàng bằng `<Flex>` | `<Form>` (`layout="horizontal" labelWidth controlWidth` là mặc định desktop; `layout="vertical"` hợp lệ khi nhãn dài/khung hẹp); 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`    |
 

package/scripts/prune-css.mjs

@@ -40,18 +40,25 @@ const args = process.argv.slice(2);
 if (args.includes("--help") || args.includes("-h") || args.length === 0) {
   console.log(`prune-css — emit a stylesheet with only the @godxjp/ui CSS layers your app uses
 
-usage: node node_modules/@godxjp/ui/scripts/prune-css.mjs <src dir/glob …> [--out <file>] [--fonts]
+usage: node node_modules/@godxjp/ui/scripts/prune-css.mjs <src dir/glob …> [--out <file>] [--fonts] [--precompiled]
 
   <src dir/glob …>  where your app's source lives (directories are walked; globs expand)
   --out <file>      where to write the css (default: godx-ui.css in the current directory)
+  --exclude-family <name>  fail if detected components require the omitted family (e.g. editorial)
   --fonts           include the bundled M PLUS 2 / Noto Sans JP @font-face declarations
                     (default mirrors @godxjp/ui/styles/core: none — bring your own fonts)
+  --precompiled     import the precompiled slices (plain CSS, dist/styles/precompiled/) instead
+                    of the Tailwind sources: for apps that use @godxjp/ui/styles.css and have
+                    no Tailwind compiler (gh#1455)
 
-Then import the emitted file INSTEAD of "@godxjp/ui/styles" and re-run this command whenever
+Then import the emitted file INSTEAD of "@godxjp/ui/styles" (or "@godxjp/ui/styles.css" with
+--precompiled) and re-run this command whenever
 the set of components you use changes, and after every @godxjp/ui upgrade.`);
   process.exit(0);
 }
 
+const excludeFlag = args.indexOf("--exclude-family");
+const excludedFamily = excludeFlag === -1 ? undefined : args[excludeFlag + 1];
 const outFlag = args.indexOf("--out");
 const OUT = outFlag !== -1 ? args[outFlag + 1] : "godx-ui.css";
 if (outFlag !== -1 && (!OUT || OUT.startsWith("--"))) {
@@ -59,8 +66,12 @@ if (outFlag !== -1 && (!OUT || OUT.startsWith("--"))) {
   process.exit(2);
 }
 const FONTS = args.includes("--fonts");
+const PRECOMPILED = args.includes("--precompiled");
 const positionals = args.filter(
-  (a, i) => !a.startsWith("--") && (outFlag === -1 || i !== outFlag + 1),
+  (a, i) =>
+    !a.startsWith("--") &&
+    (outFlag === -1 || i !== outFlag + 1) &&
+    (excludeFlag === -1 || i !== excludeFlag + 1),
 );
 
 // ── the package's own graph, version-locked ──────────────────────────────────
@@ -85,6 +96,13 @@ if (manifest.version !== pkg.version) {
   process.exit(2);
 }
 
+if (excludeFlag !== -1 && !Object.hasOwn(manifest.families ?? {}, excludedFamily ?? "")) {
+  console.error(
+    `prune-css: unknown --exclude-family ${excludedFamily ?? "(missing)"}; choose ${Object.keys(manifest.families ?? {}).join(", ")}`,
+  );
+  process.exit(2);
+}
+
 // ── scan consumer sources ────────────────────────────────────────────────────
 
 const SCANNABLE = /\.(tsx|jsx|ts|mjs|js|cjs|mts)$/;
@@ -184,9 +202,35 @@ for (const name of used) {
   for (const v of entry.vendor ?? []) vendors.add(v);
 }
 
+if (excludedFamily && manifest.families[excludedFamily].some((file) => layers.has(file))) {
+  console.error(
+    `prune-css: cannot exclude ${excludedFamily}: detected components require it. Remove their imports or keep the family.`,
+  );
+  process.exit(2);
+}
+
 const keptLayers = manifest.order.filter((f) => layers.has(f));
 const keptVendors = manifest.vendor.filter((f) => vendors.has(f));
-const asImport = (f) => `@import "@godxjp/ui/styles/${f.replace(/\.css$/, "")}";`;
+// --precompiled (gh#1455): the same slice, from the plain-CSS cut of styles.css that
+// build-precompiled-css.mjs writes per manifest file. The fonts sheet has no Tailwind in it, so it
+// is imported from its usual place either way.
+const asImport = (f) =>
+  PRECOMPILED && f !== manifest.fonts
+    ? `@import "@godxjp/ui/styles/precompiled/${f.replace(/\.css$/, "")}";`
+    : `@import "@godxjp/ui/styles/${f.replace(/\.css$/, "")}";`;
+if (PRECOMPILED) {
+  const missing = [...keptVendors, manifest.base, ...keptLayers].filter(
+    (f) => !existsSync(join(PKG_ROOT, "dist/styles/precompiled", f)),
+  );
+  if (missing.length) {
+    console.error(
+      `prune-css: --precompiled, but the installed @godxjp/ui ships no precompiled slice for ` +
+        `${missing.join(", ")} (dist/styles/precompiled/). Upgrade the package; inside the repo ` +
+        "itself, run `pnpm build` first.",
+    );
+    process.exit(2);
+  }
+}
 
 const lines = [
   "/*",
@@ -194,17 +238,21 @@ const lines = [
   ` *`,
   ` * @godxjp/ui version: ${pkg.version}`,
   ` * components detected: ${[...used].sort().join(", ")}`,
-  ` * layers: ${keptLayers.length} of ${manifest.order.length} (+base${FONTS ? "+fonts" : ", no bundled fonts — like styles/core"})`,
+  ` * layers: ${keptLayers.length} of ${manifest.order.length} (+base${FONTS ? "+fonts" : ", no bundled fonts — like styles/core"})${PRECOMPILED ? ", precompiled (no Tailwind needed)" : ""}`,
   ` *`,
   ` * Re-run when the components your app uses change, and after every @godxjp/ui upgrade:`,
-  ` *   node node_modules/@godxjp/ui/scripts/prune-css.mjs <src …> --out <this file>${FONTS ? " --fonts" : ""}`,
+  ` *   node node_modules/@godxjp/ui/scripts/prune-css.mjs <src …> --out <this file>${FONTS ? " --fonts" : ""}${PRECOMPILED ? " --precompiled" : ""}`,
   ` *`,
   ` * Hand-editing this file is the cherry-picking the README forbids: layers share rules and`,
   ` * a missing one fails silently. Change your imports, then re-run the tool.`,
   " */",
   // Layer order must be declared before the first @import — same statement, same reasoning,
-  // as styles/index.css (vendor between base and components; see the comment there).
-  "@layer theme, base, vendor, components, utilities;",
+  // as styles/index.css (vendor between base and components; see the comment there). Precompiled
+  // CSS also carries Tailwind's `properties` layer (the @property fallbacks), which the compiler
+  // puts FIRST in styles.css; named here, it keeps that place instead of landing after utilities.
+  PRECOMPILED
+    ? "@layer properties, theme, base, vendor, components, utilities;"
+    : "@layer theme, base, vendor, components, utilities;",
   ...keptVendors.map(asImport),
   asImport(manifest.base),
   ...(FONTS ? [asImport(manifest.fonts)] : []),

package/scripts/ui-audit.mjs

@@ -366,6 +366,27 @@ const LIST_TAGS = new Set(["DataTable", "Table", "List", "ListRow"]);
  *   CSS Logical Properties L1 (W3C) · HTML Living Standard (WHATWG).
  */
 const RULES = [
+  {
+    id: "no-direct-sonner-import",
+    replacement: "import { toast } from '@godxjp/ui'",
+    scope: "consumer",
+    severity: "error",
+    spansElement: true,
+    test: /\bimport\s+(?!type\b)(?:[^;"']*?\s+from\s*)?["']sonner["']/g,
+    message:
+      "import toast from @godxjp/ui — use `import { toast } from \"@godxjp/ui\"`; a consumer's sonner may own a different toast store from the kit's Toaster.",
+  },
+  {
+    id: "dropdown-menu-non-menu-children",
+    replacement: "Popover + ListRow",
+    scope: "consumer",
+    severity: "error",
+    spansElement: true,
+    matches: dropdownNonMenuMatches,
+    message:
+      "DropdownMenuContent accepts menu collection children only. Use DropdownMenuItem for actions; use Popover + ListRow for arbitrary headers, lists and links.",
+  },
+
   {
     id: "no-utility-spacing",
     replacement: "Flex gap / ResponsiveGrid / PageContainer",
@@ -2936,3 +2957,18 @@ if (filesScanned === 0 && !changedNoFiles) {
 
 // See the note above --rules: exitCode, so a large JSON report drains fully.
 if (filesScanned > 0 || changedNoFiles) process.exitCode = errors.length > 0 ? 1 : 0;
+
+/** Known DOM children are invalid collection nodes; opaque wrappers are deliberately allowed. */
+function* dropdownNonMenuMatches(source) {
+  const containers = new Set([
+    "DropdownMenuContent",
+    "DropdownMenuSubContent",
+    "DropdownMenuGroup",
+    "DropdownMenuRadioGroup",
+  ]);
+  for (const { tag, index, openTag, stack } of jsxElements(source)) {
+    if (!/^[a-z]/.test(tag)) continue;
+    const parent = [...stack].reverse().find((frame) => !frame.attr && frame.tag !== "");
+    if (parent && containers.has(parent.tag)) yield { 0: openTag, index };
+  }
+}

package/skills/godxjp-ui-navigation/SKILL.md

@@ -42,12 +42,16 @@ comparisons, domain vocabulary) in its own repository; they do not belong in thi
 ## 2. Hard rules
 
 **Count and form**
-- Phone: **bottom bar with 3–5 items** (the middle one may be a ＋ quick-log button); everything else
-  goes under "More". Never put setup on the bottom bar. Desktop: **an always-visible sidebar**, not
+- Phone: **bottom bar with 3–5 destinations**; every slot navigates, never an action slot (see
+  principles §1.6 and rule 11). The #1 create action sits above the bar (a FAB) or in the top bar.
+  Everything else goes under "More". Never put setup on the bottom bar. Desktop: **an always-visible sidebar**, not
   only a ☰ button. Choose by window width, not by device. (@godxjp/ui's `MobileShell` has a bottom
   bar — use it; don't rely on a drawer alone.)
-- Sidebar at most **2 levels**, groups with short headings; each role sees **≤ ~7 primary items**.
-  Anything deeper → list → detail inside the page.
+- Keep the sidebar shallow (aim for **2 levels**, groups with short headings) and each role's primary
+  list short (**~7 items**). These numbers are **review signals, not pass/fail limits**: when a role
+  exceeds them, validate the tree with the role's real tasks (tree test or walkthrough) and split by
+  work area rather than hiding items in a catch-all group. Record data deeper than the menu →
+  list → detail inside the page.
 
 **Grouping and labels**
 - Group by **task / work area**. Never group by data table, org chart or developer vocabulary
@@ -59,8 +63,8 @@ comparisons, domain vocabulary) in its own repository; they do not belong in thi
 - **Each destination appears once** in the menu. Two items leading to the same kind of record = a
   defect.
 - Action buttons (Log/Create) are **not menu items**: one prominent primary button (top of the menu,
-  or the ＋ in the middle of the bottom bar) for the #1 task; child objects are created right inside
-  their parent's page.
+  or a create button above the bottom bar — never inside a bar slot) for the #1 task; child objects
+  are created right inside their parent's page.
 
 **Per role**
 - Each role has its **own fixed landing page**: frontline staff → "Today" (due, overdue, my tasks);
@@ -99,14 +103,15 @@ An example only, for apps that run recurring checks across many sites:
   stay **permanently linked** to their source record.
 - Staff land on "Today" plus a separate place for "Overdue/Missed"; managers land on a rate table plus
   exceptions.
-- Phone bottom bar: 4–5 task items (e.g. Today · Inspections · ＋Log · Nonconformities · More).
+- Phone bottom bar: 4–5 destinations (e.g. Today · Inspections · Nonconformities · More), with
+  ＋ Log as a button above the bar.
 - Vocabulary: avoid "Reports"/"レポート" as the label for *records* (in English "Reports" means
   analytics; in Japanese "レポート" often means an individual record).
 
 ## 4. Self-check gate (before asking for approval / before merging)
 
-- [ ] A task table per role and a text menu tree per role exist; each role ≤ ~7 primary items; phone
-      3–5 items.
+- [ ] A task table per role and a text menu tree per role exist; a role past ~7 primary items or 2
+      levels has a tree test or walkthrough behind it; phone 3–5 destinations, no action slot.
 - [ ] Walkthrough of 8–10 tasks per role: no step answered "no"; no pair of competing labels.
 - [ ] No duplicate destinations; no grouping by data table; label = H1 = `<title>`, consistent across
       every locale.

package/skills/godxjp-ui-navigation/references/principles.md

@@ -215,7 +215,7 @@ The Atlassian Design System's public navigation page and the Salesforce Lightnin
 | Breadcrumb as history, or a breadcrumb plus a back link | Breadcrumbs show hierarchy [P] NN/g; "Never use the back link… together with the Breadcrumbs" [P] GOV.UK |
 | Losing list position or filters on Back | "the page often resets to the top of the list" [P] NN/g saving scroll position |
 | Main navigation in the page header, or repeated in the page body | "Avoid placing the main navigation in the page header"; avoid "replicating the app nav content in the app body" [P] Shopify |
-| More than 2 levels of sidebar or cascading menus | [P] HIG sidebars; Carbon; Fluent; NN/g menu design |
+| More than 2 levels of sidebar or cascading menus, with no tree test or walkthrough behind them | [P] HIG sidebars; Carbon; Fluent; NN/g menu design |
 | Dead ends on object pages | Give paths onward from every object instance [Pr] OOUX (A List Apart) |
 
 ---
@@ -232,7 +232,7 @@ The Atlassian Design System's public navigation page and the Salesforce Lightnin
 | 6 | Labels are short nouns in the users' words, 1–2 words, never coined terms. | https://shopify.dev/docs/apps/design/navigation ; https://www.nngroup.com/articles/top-10-ia-mistakes/ |
 | 7 | Every navigation item has a visible text label. Icons only support the label. Never truncate. | https://m3.material.io/components/navigation-bar/guidelines |
 | 8 | Order by frequency of use measured from users (top-tasks vote or field study). Positions stay fixed. | https://www.nngroup.com/articles/progressive-disclosure/ ; https://www.w3.org/WAI/WCAG22/Understanding/consistent-navigation.html |
-| 9 | Sidebar: at most 2 levels, with short group headings. Deeper data goes into list → detail inside the page. | https://developer.apple.com/design/human-interface-guidelines/sidebars |
+| 9 | Sidebar: aim for 2 levels, with short group headings — a review signal, not a pass/fail limit. A third level is for a work area that needs it, validated by a tree test or walkthrough; record data goes into list → detail inside the page. | https://developer.apple.com/design/human-interface-guidelines/sidebars |
 | 10 | Settings, admin and configuration live apart from daily work (utility area or admin section), behind a second level at most. | https://www.nngroup.com/articles/utility-navigation/ ; https://www.nngroup.com/articles/progressive-disclosure/ |
 | 11 | Navigation slots navigate; they never perform actions. Put Create in a FAB or top bar for the main object, and in context for children. | https://developer.apple.com/design/human-interface-guidelines/tab-bars |
 | 12 | Each role gets its own fixed start page, named after the work area, with task-oriented sections. | https://www.sap.com/design-system/fiori-design-web/v1-148/foundations/integration-and-services/sap-fiori-launchpad/sap-fiori-launchpad-spaces |