@godxjp/ui 33.24.0 → 33.25.0

package/README.md

@@ -18,7 +18,7 @@ npm i @godxjp/ui
 
 <!-- agent-catalog-counts:start -->
 
-The catalog — 212 components, 3198 tokens, 44 cardinal rules — is published in two forms from one
+The catalog — 212 components, 3203 tokens, 44 cardinal rules — is published in two forms from one
 source. **Entry point for either: [`AGENTS.md`](AGENTS.md).**
 <!-- agent-catalog-counts:end -->
 
@@ -56,9 +56,9 @@ static files straight from this public repo — no hosting, no deploy step:
 | [`agent/components-index.json`](https://raw.githubusercontent.com/godx-jp/godxjp-ui/main/agent/components-index.json) | 47 KB | all 212 as name + group + tagline — **fetch this first** |
 | [`agent/components/<Name>.json`](https://raw.githubusercontent.com/godx-jp/godxjp-ui/main/agent/components/Select.json) | 1 KB–38 KB | one file per component, each with its `importPath` — **this is the route to take** |
 | [`agent/components.json`](https://raw.githubusercontent.com/godx-jp/godxjp-ui/main/agent/components.json) | 1.4 MB | all 212 entries in one file — most URL fetchers truncate this silently; prefer the per-component files |
-| [`agent/tokens.json`](https://raw.githubusercontent.com/godx-jp/godxjp-ui/main/agent/tokens.json) | 1.4 MB | all 3198 design tokens, their values and why they exist |
+| [`agent/tokens.json`](https://raw.githubusercontent.com/godx-jp/godxjp-ui/main/agent/tokens.json) | 1.4 MB | all 3203 design tokens, their values and why they exist |
 | [`agent/vocabulary.json`](https://raw.githubusercontent.com/godx-jp/godxjp-ui/main/agent/vocabulary.json) | 7 KB | the controlled prop vocabulary |
-| [`agent/rules.json`](https://raw.githubusercontent.com/godx-jp/godxjp-ui/main/agent/rules.json) | 23 KB | the 44 cardinal rules |
+| [`agent/rules.json`](https://raw.githubusercontent.com/godx-jp/godxjp-ui/main/agent/rules.json) | 24 KB | the 44 cardinal rules |
 <!-- prettier-ignore-end -->
 <!-- agent-catalog-files:end -->
 
@@ -226,6 +226,17 @@ only when a used component renders them. **Re-run it whenever the set of compone
 changes and after every upgrade** — the emitted header says so, and the tool refuses to run against
 a manifest from a different package version.
 
+No Tailwind (you import `@godxjp/ui/styles.css`)? Add `--precompiled` (gh#1455):
+
+```bash
+npx godxjp-ui prune-css src --out src/godx-ui.css --precompiled
+```
+
+The emitted file imports the precompiled slices instead (`@import "@godxjp/ui/styles/precompiled/base";` and one per kept layer): the same precompiled CSS as
+`styles.css`, cut per manifest file at build time (`base` = tokens, preflight and the utilities
+the components use; one slice per layer and vendor sheet). Your bundler only has to inline plain
+`@import`s. Import it INSTEAD of `@godxjp/ui/styles.css`.
+
 ## Golden ratio (φ ≈ 1.618)
 
 One token `--phi-unit` drives page/section/card spacing; micro control gaps use the 4px grid. Density (`compact` | `default` | `comfortable`) retunes `--phi-unit` with control + table heights together.

package/agent/START-HERE.md

@@ -3,7 +3,7 @@
 You are about to write code against a design system you did not author. This file is the whole
 contract. Read it before you write JSX.
 
-**This catalog describes `@godxjp/ui` 33.24.0.** If the project you are editing has a different
+**This catalog describes `@godxjp/ui` 33.25.0.** If the project you are editing has a different
 version in its `package.json`, read the pinned catalog for THAT version instead
 (`…/v<their-version>/agent/…`). A catalog newer than the installed package describes props that do
 not exist yet; older, and it hides props that do. Neither failure announces itself.
@@ -48,7 +48,7 @@ inspect every screenshot at every width region by region (no top-N cap), and han
 → These files are for you. Read `DESIGN.md` (in this folder) first: tokens, scarcity rules and
 screen anatomy, the visual target the rules below do not give you. Then fetch in this order:
 
-0. `patterns-index.json` — 28 whole-task patterns as name + tagline + tags. **If your
+0. `patterns-index.json` — 29 whole-task patterns as name + tagline + tags. **If your
    task is a task** — "build a settings page", "confirm a destructive delete", "a list page with
    filters" — start HERE, not at the components. Then fetch `patterns/<name>.json` for complete,
    copy-paste-ready code. A component index answers "does X exist"; it cannot answer "build Y".
@@ -61,10 +61,10 @@ screen anatomy, the visual target the rules below do not give you. Then fetch in
    its `importPath`, and its examples. Fetch only the handful you picked in step 1.
 3. `rules.json` — 44 cardinal rules. The ones about raw HTML and hardcoded colour are not
    style advice.
-4. `tokens.json` — 3198 design tokens, each tagged with its `tier`. **If you were handed a
+4. `tokens.json` — 3203 design tokens, each tagged with its `tier`. **If you were handed a
    brand, read the 223 `foundation` entries first** — `--primary`, `--background`,
    `--radius`, `--font-size-base` are the handful everything else derives from. The
-   2862 `component` entries are per-part knobs; reach for one only when a role is
+   2867 `component` entries are per-part knobs; reach for one only when a role is
    right everywhere except one component.
 5. `anti-ai-tells.json` — 35 shapes that make generated UI look generated, each with the
    fix. Read before you reach for a gradient hero or a wall of coloured chips.
@@ -150,7 +150,7 @@ has stopped following the brand.
 |---|---|---|---|
 | `foundation` | 223 | the seeds — `--primary`, `--background`, `--foreground`, `--radius`, `--font-size-base`, `--shadow-color`. Everything below is derived from these | **yes — this is the main road.** The default `--primary` is a neutral placeholder: set it (`:root { --primary: <H> <S>% <L>%; }`, HSL components, no `hsl()` wrapper) or import a theme preset such as `@godxjp/ui/themes/godx.css` |
 | `semantic` | 113 | named roles that follow the seeds — `--ring`, `--text-link`, `--primary-hover`, `--overlay-background` | only when the seed is right and ONE role must differ. That role then stops following a later brand change |
-| `component` | 2862 | per-part knobs, `--{component}-{part}-{property}` | rarely. Most are declared `initial` with the real default at the call site — deliberate, so a scoped override re-resolves instead of freezing at `:root` |
+| `component` | 2867 | per-part knobs, `--{component}-{part}-{property}` | rarely. Most are declared `initial` with the real default at the call site — deliberate, so a scoped override re-resolves instead of freezing at `:root` |
 
 A token whose `value` is `initial` is not empty and not broken: `initial` is the guaranteed-invalid
 value, so the real default is computed where the element paints it. Set it and yours wins.

package/agent/components/CatalogDetail.json

@@ -1,5 +1,5 @@
 {
-  "example": "import { CatalogDetail, CatalogDetailTag, Eyebrow } from \"@godxjp/ui/layout\";\n\n<CatalogDetail media={<img src={src} alt={name} />} overline={<Eyebrow>Pokémon</Eyebrow>} title={name} meta={<CatalogDetailTag>SAR</CatalogDetailTag>} summary={{ label: \"Market\", price: \"¥32,800\" }} facts={[{ key: \"set\", label: \"Expansion\", value: \"151\" }]} />",
+  "example": "import { CatalogDetail, CatalogDetailTag, Eyebrow } from \"@godxjp/ui/layout\";\n\n<CatalogDetail image={{ src: \"/reference.svg\", alt: \"Reference\", priority: true }} overline={<Eyebrow>Pokémon</Eyebrow>} title={name} meta={<CatalogDetailTag>SAR</CatalogDetailTag>} summary={{ label: \"Market\", price: \"¥32,800\" }} facts={[{ key: \"set\", label: \"Expansion\", value: \"151\" }]} />",
   "group": "layout",
   "importPath": "@godxjp/ui/layout",
   "name": "CatalogDetail",
@@ -11,11 +11,15 @@
       "type": "\"card\" | \"sealed\""
     },
     {
-      "description": "The picture.",
+      "description": "Custom picture; used when image is omitted.",
       "name": "media",
-      "required": true,
       "type": "ReactNode"
     },
+    {
+      "description": "Kit Image keyed per src. Art frame exposes data-status loading|loaded|error and aria-busy; token-driven skeleton respects reduced motion. priority requests eager/high priority. Takes precedence over media.",
+      "name": "image",
+      "type": "{ src: string; alt: string; width?: number | string; height?: number | string; fallback?: string; priority?: boolean }"
+    },
     {
       "description": "Save toggle over the frame.",
       "name": "favorite",

package/agent/components/DatePicker.json

@@ -123,7 +123,7 @@
       "type": "\"date\" | \"week\" | \"month\" | \"quarter\" | \"year\""
     },
     {
-      "description": "CARDINALITY: two endpoints in one control (antd `DatePicker.RangePicker`). value/defaultValue and the callback become `DateRange`; the pair submits as `${name}_from` / `${name}_to`. Composes with `picker`, so a month range is `<DatePicker range picker=\"month\" />`. Never place two DatePickers side by side to fake this.",
+      "description": "With no confirmation, holds the first endpoint internally while open, emits a complete range or clear, and discards half-ranges on close. CARDINALITY: two endpoints in one control (antd `DatePicker.RangePicker`). value/defaultValue and the callback become `DateRange`; the pair submits as `${name}_from` / `${name}_to`. Composes with `picker`, so a month range is `<DatePicker range picker=\"month\" />`. Never place two DatePickers side by side to fake this.",
       "name": "range",
       "type": "boolean"
     },

package/agent/components/DropdownMenu.json

@@ -89,6 +89,7 @@
   ],
   "tagline": "Dropdown menu (react-aria). Compose DropdownMenu/DropdownMenuTrigger/DropdownMenuContent/DropdownMenuItem/DropdownMenuSeparator. `trigger` picks the gestures — click (default), hover, or contextMenu, which is what replaced the deleted ContextMenu component.",
   "usage": [
+    "DO: Use only menu collection nodes inside DropdownMenuContent. Arbitrary headers, notification lists and links belong in Popover + ListRow; development diagnostics and the dropdown-menu-non-menu-children audit rule name this fix.",
     "DO compose the full sub-part tree: DropdownMenu (root) → DropdownMenuTrigger (with asChild to delegate to your Button/icon) → DropdownMenuContent → DropdownMenuItem / DropdownMenuSeparator / DropdownMenuLabel / DropdownMenuGroup. Omitting any level (e.g. rendering DropdownMenuContent without DropdownMenu as ancestor) breaks Radix context and the menu will not open.",
     "DO use DropdownMenuTrigger with asChild and pass a godx-ui Button or icon Button as the child — never render a raw <button> or <div> as the trigger, and never omit asChild when the child is already a button-like element (double-button nesting breaks a11y).",
     "DO use variant='destructive' on DropdownMenuItem for irreversible actions (delete, revoke, void) — this applies the semantic destructive colour token automatically without any className override.",

package/agent/components/EditorialCard.json

@@ -65,6 +65,7 @@
   ],
   "tagline": "A whole-card link (gh#1435). `variant=\"journal\"`: an edge-to-edge cover, category, title, two lines of description and a footer with a circled arrow; the link is named by its title (aria-labelledby). `variant=\"spotlight\"`: kicker, title and a line beside a tilted picture. Pass the link element (router Link or `<a href>`) as `link`; the card content is rendered into it. Geometry: `--editorial-journal-*`, `--editorial-spotlight-*`.",
   "usage": [
-    "DO lay journal cards out with `ResponsiveGrid preset=\"trio\"`."
+    "DO lay journal cards out with `ResponsiveGrid preset=\"trio\"`.",
+    "DO use kit Image with preview={false} for media inside the whole-card link. Spotlight sizes the Image frame to fill its slot, including placeholder and fallback (gh#1474)."
   ]
 }

package/agent/components/Image.json

@@ -8,6 +8,11 @@
   "importPath": "@godxjp/ui/data-display",
   "name": "Image",
   "props": [
+    {
+      "description": "Reports resolved status, including cached images; error remains final while showing fallback.",
+      "name": "onStatusChange",
+      "type": "(status: \"loading\" | \"loaded\" | \"error\") => void"
+    },
     {
       "description": "Image URL.",
       "name": "src",
@@ -29,7 +34,7 @@
       "type": "string"
     },
     {
-      "description": "Painted over the frame until the picture loads; `true` = a muted block.",
+      "description": "After hydration, painted over the frame while the picture loads; SSR leaves pictures uncovered. `true` = a muted block. Child content can shrink to fit the frame.",
       "name": "placeholder",
       "type": "ReactNode | boolean"
     },

package/agent/components/Pagination.json

@@ -4,6 +4,11 @@
   "importPath": "@godxjp/ui/navigation",
   "name": "Pagination",
   "props": [
+    {
+      "description": "Pointer enter, focus or touch start on enabled page/previous/next controls, including simple and responsive forms. May repeat: preload/cache the target without changing value. Disabled or out-of-range targets do not emit.",
+      "name": "onPageIntent",
+      "type": "(page: number) => void"
+    },
     {
       "description": "Tên khả truy cập của landmark phân trang. Bắt buộc khi một trang có nhiều bộ phân trang.",
       "name": "ariaLabel",

package/agent/components/Popover.json

@@ -113,6 +113,7 @@
   ],
   "tagline": "React Aria floating panel anchored to a trigger — always compose with PopoverTrigger + PopoverContent; never use a raw div overlay.",
   "usage": [
+    "DO: PopoverContent scrolls automatically when its available height caps content. Focus rings remain contained at scroll edges, including flush panels.",
     "HOVER CARD: `<Popover openOn=\"hover\"><PopoverTrigger asChild><a href=…>@yamada</a></PopoverTrigger><PopoverContent>…</PopoverContent></Popover>` for RICH preview content (an avatar + bio, an entity summary). For a short plain-text hint use Tooltip. DON'T put essential information only in a hover card — touch never opens it; make the same content reachable from the trigger's destination. There is no `HoverCard` component.",
     "DO compose: <Popover> → <PopoverTrigger asChild> → <Button/> and <PopoverContent>. All four parts are required for any popover to function; omitting PopoverTrigger or PopoverContent produces nothing.",
     "DO set `<PopoverContent width=\"auto\">` when the child brings its own measure — a Calendar, a chart, a fixed-width preview. The panel's own 18rem clips them, and a `w-*` utility on className is a per-call-site constant no service theme can retune, which is exactly what `flush` exists to avoid on the padding axis. `width=\"trigger\"` matches the anchor, the shape every select-like control wants.",

package/agent/components/Select.json

@@ -268,7 +268,7 @@
       "type": "React.ReactNode"
     },
     {
-      "description": "antd `popupMatchSelectWidth`. true (default) pins the popup to the trigger width, false lets it hug its rows, a number pins it to that many pixels.",
+      "description": "antd `popupMatchSelectWidth`. true (default): the trigger width is the floor and the popup grows to its longest row, up to --select-content-max-width (32rem) and the viewport less --select-content-viewport-inset, then wraps rows. false lets it hug its rows below the trigger width; a number pins it to that many pixels. The width never depends on where the popup is placed, so it cannot change while open.",
       "name": "popupMatchSelectWidth",
       "type": "boolean | number"
     },
@@ -398,6 +398,7 @@
   ],
   "tagline": "Polymorphic single-select: pass options/loadOptions for the data-driven (Ant-style) API, or compose sub-parts manually — never use a raw <select>.",
   "usage": [
+    "DO: Searchable popup widths, including numeric popupMatchSelectWidth, are capped by --search-select-panel-max-width and --search-select-panel-viewport-inset, using the viewport width excluding classic scrollbars.",
     "Coarse pointers: affix actions use --control-affix-touch-target-size (44px by default); text space is reserved separately. Fine-pointer geometry is unchanged.",
     "FREE-TEXT TAGS WITH NO LIST (keywords, email recipients, labels typed from scratch): `<Select mode=\"tags\" open={false} value={tags} onValueChange={setTags} />` — the inline chip field. Use plain `mode=\"tags\"` (popup) only when there is a list of existing tags to pick from. There is no `TagInput` component.",
     "DO use the data-driven API (options/loadOptions) for straightforward selects — it handles grouping, search, async, and custom rendering automatically. Only reach for the compound API when you need to inject arbitrary content into the trigger or listbox.",

package/agent/components/Toaster.json

@@ -42,7 +42,7 @@
   "usage": [
     "DO: Mount exactly ONE `<Toaster richColors />` at the app root (e.g. inside your layout or AppShell children). Multiple mounts create duplicate toast stacks — there is no provider context, only DOM portals.",
     "DO: Import `toast` from `\"@godxjp/ui/feedback\"` to fire toasts anywhere: `toast.success(…)`, `toast.error(…)`, `toast.warning(…)`, `toast.info(…)`, `toast.loading(…)`, `toast.promise(…)`. It is Sonner's own API with one house default: `toast.error` and `toast.warning` carry a close button (opt out per call with `{ closeButton: false }`), success/info stay auto-dismiss only (gh#1253).",
-    "DON'T: Import `toast` from `\"sonner\"` directly — it works, but it skips the close-button default on error/warning. Also note `toast.promise` settling into an error does not gain the button; pass `closeButton` there yourself if the failure must stay dismissible.",
+    "DON'T: Import `toast` from `\"sonner\"` directly — a consumer-installed version can own a different toast store from the kit Toaster, silently hiding toasts. Use `import { toast } from \"@godxjp/ui\"` (also available from `@godxjp/ui/feedback`); this also preserves close-button defaults. Also note `toast.promise` settling into an error does not gain the button; pass `closeButton` there yourself if the failure must stay dismissible.",
     "DO: Tune how long toasts stay with the `--toast-duration` token in the theme (default 4000ms) rather than a `duration` prop on every mount. Never truncate a toast's body — it wraps.",
     "DO: Let the wrapper handle theming — it uses `useDocumentTheme()` to sync with the document `dark` class and `prefers-color-scheme` automatically. Never pass a hardcoded `theme` prop unless you are deliberately overriding.",
     "DON'T: Use `Toaster` for persistent errors or blocking confirmations. Toasts auto-dismiss; they are not a substitute for `Alert` (inline persistent warnings) or `Dialog` (decisions requiring user input).",

package/agent/components.json

@@ -1685,7 +1685,8 @@
     ],
     "tagline": "A whole-card link (gh#1435). `variant=\"journal\"`: an edge-to-edge cover, category, title, two lines of description and a footer with a circled arrow; the link is named by its title (aria-labelledby). `variant=\"spotlight\"`: kicker, title and a line beside a tilted picture. Pass the link element (router Link or `<a href>`) as `link`; the card content is rendered into it. Geometry: `--editorial-journal-*`, `--editorial-spotlight-*`.",
     "usage": [
-      "DO lay journal cards out with `ResponsiveGrid preset=\"trio\"`."
+      "DO lay journal cards out with `ResponsiveGrid preset=\"trio\"`.",
+      "DO use kit Image with preview={false} for media inside the whole-card link. Spotlight sizes the Image frame to fill its slot, including placeholder and fallback (gh#1474)."
     ]
   },
   {
@@ -1983,7 +1984,7 @@
     ]
   },
   {
-    "example": "import { CatalogDetail, CatalogDetailTag, Eyebrow } from \"@godxjp/ui/layout\";\n\n<CatalogDetail media={<img src={src} alt={name} />} overline={<Eyebrow>Pokémon</Eyebrow>} title={name} meta={<CatalogDetailTag>SAR</CatalogDetailTag>} summary={{ label: \"Market\", price: \"¥32,800\" }} facts={[{ key: \"set\", label: \"Expansion\", value: \"151\" }]} />",
+    "example": "import { CatalogDetail, CatalogDetailTag, Eyebrow } from \"@godxjp/ui/layout\";\n\n<CatalogDetail image={{ src: \"/reference.svg\", alt: \"Reference\", priority: true }} overline={<Eyebrow>Pokémon</Eyebrow>} title={name} meta={<CatalogDetailTag>SAR</CatalogDetailTag>} summary={{ label: \"Market\", price: \"¥32,800\" }} facts={[{ key: \"set\", label: \"Expansion\", value: \"151\" }]} />",
     "group": "layout",
     "importPath": "@godxjp/ui/layout",
     "name": "CatalogDetail",
@@ -1995,11 +1996,15 @@
         "type": "\"card\" | \"sealed\""
       },
       {
-        "description": "The picture.",
+        "description": "Custom picture; used when image is omitted.",
         "name": "media",
-        "required": true,
         "type": "ReactNode"
       },
+      {
+        "description": "Kit Image keyed per src. Art frame exposes data-status loading|loaded|error and aria-busy; token-driven skeleton respects reduced motion. priority requests eager/high priority. Takes precedence over media.",
+        "name": "image",
+        "type": "{ src: string; alt: string; width?: number | string; height?: number | string; fallback?: string; priority?: boolean }"
+      },
       {
         "description": "Save toggle over the frame.",
         "name": "favorite",
@@ -9172,7 +9177,7 @@
         "type": "React.ReactNode"
       },
       {
-        "description": "antd `popupMatchSelectWidth`. true (default) pins the popup to the trigger width, false lets it hug its rows, a number pins it to that many pixels.",
+        "description": "antd `popupMatchSelectWidth`. true (default): the trigger width is the floor and the popup grows to its longest row, up to --select-content-max-width (32rem) and the viewport less --select-content-viewport-inset, then wraps rows. false lets it hug its rows below the trigger width; a number pins it to that many pixels. The width never depends on where the popup is placed, so it cannot change while open.",
         "name": "popupMatchSelectWidth",
         "type": "boolean | number"
       },
@@ -9302,6 +9307,7 @@
     ],
     "tagline": "Polymorphic single-select: pass options/loadOptions for the data-driven (Ant-style) API, or compose sub-parts manually — never use a raw <select>.",
     "usage": [
+      "DO: Searchable popup widths, including numeric popupMatchSelectWidth, are capped by --search-select-panel-max-width and --search-select-panel-viewport-inset, using the viewport width excluding classic scrollbars.",
       "Coarse pointers: affix actions use --control-affix-touch-target-size (44px by default); text space is reserved separately. Fine-pointer geometry is unchanged.",
       "FREE-TEXT TAGS WITH NO LIST (keywords, email recipients, labels typed from scratch): `<Select mode=\"tags\" open={false} value={tags} onValueChange={setTags} />` — the inline chip field. Use plain `mode=\"tags\"` (popup) only when there is a list of existing tags to pick from. There is no `TagInput` component.",
       "DO use the data-driven API (options/loadOptions) for straightforward selects — it handles grouping, search, async, and custom rendering automatically. Only reach for the compound API when you need to inject arbitrary content into the trigger or listbox.",
@@ -10129,7 +10135,7 @@
         "type": "\"date\" | \"week\" | \"month\" | \"quarter\" | \"year\""
       },
       {
-        "description": "CARDINALITY: two endpoints in one control (antd `DatePicker.RangePicker`). value/defaultValue and the callback become `DateRange`; the pair submits as `${name}_from` / `${name}_to`. Composes with `picker`, so a month range is `<DatePicker range picker=\"month\" />`. Never place two DatePickers side by side to fake this.",
+        "description": "With no confirmation, holds the first endpoint internally while open, emits a complete range or clear, and discards half-ranges on close. CARDINALITY: two endpoints in one control (antd `DatePicker.RangePicker`). value/defaultValue and the callback become `DateRange`; the pair submits as `${name}_from` / `${name}_to`. Composes with `picker`, so a month range is `<DatePicker range picker=\"month\" />`. Never place two DatePickers side by side to fake this.",
         "name": "range",
         "type": "boolean"
       },
@@ -10705,7 +10711,7 @@
     "usage": [
       "DO: Mount exactly ONE `<Toaster richColors />` at the app root (e.g. inside your layout or AppShell children). Multiple mounts create duplicate toast stacks — there is no provider context, only DOM portals.",
       "DO: Import `toast` from `\"@godxjp/ui/feedback\"` to fire toasts anywhere: `toast.success(…)`, `toast.error(…)`, `toast.warning(…)`, `toast.info(…)`, `toast.loading(…)`, `toast.promise(…)`. It is Sonner's own API with one house default: `toast.error` and `toast.warning` carry a close button (opt out per call with `{ closeButton: false }`), success/info stay auto-dismiss only (gh#1253).",
-      "DON'T: Import `toast` from `\"sonner\"` directly — it works, but it skips the close-button default on error/warning. Also note `toast.promise` settling into an error does not gain the button; pass `closeButton` there yourself if the failure must stay dismissible.",
+      "DON'T: Import `toast` from `\"sonner\"` directly — a consumer-installed version can own a different toast store from the kit Toaster, silently hiding toasts. Use `import { toast } from \"@godxjp/ui\"` (also available from `@godxjp/ui/feedback`); this also preserves close-button defaults. Also note `toast.promise` settling into an error does not gain the button; pass `closeButton` there yourself if the failure must stay dismissible.",
       "DO: Tune how long toasts stay with the `--toast-duration` token in the theme (default 4000ms) rather than a `duration` prop on every mount. Never truncate a toast's body — it wraps.",
       "DO: Let the wrapper handle theming — it uses `useDocumentTheme()` to sync with the document `dark` class and `prefers-color-scheme` automatically. Never pass a hardcoded `theme` prop unless you are deliberately overriding.",
       "DON'T: Use `Toaster` for persistent errors or blocking confirmations. Toasts auto-dismiss; they are not a substitute for `Alert` (inline persistent warnings) or `Dialog` (decisions requiring user input).",
@@ -10907,6 +10913,11 @@
     "importPath": "@godxjp/ui/navigation",
     "name": "Pagination",
     "props": [
+      {
+        "description": "Pointer enter, focus or touch start on enabled page/previous/next controls, including simple and responsive forms. May repeat: preload/cache the target without changing value. Disabled or out-of-range targets do not emit.",
+        "name": "onPageIntent",
+        "type": "(page: number) => void"
+      },
       {
         "description": "Tên khả truy cập của landmark phân trang. Bắt buộc khi một trang có nhiều bộ phân trang.",
         "name": "ariaLabel",
@@ -11124,6 +11135,7 @@
     ],
     "tagline": "Dropdown menu (react-aria). Compose DropdownMenu/DropdownMenuTrigger/DropdownMenuContent/DropdownMenuItem/DropdownMenuSeparator. `trigger` picks the gestures — click (default), hover, or contextMenu, which is what replaced the deleted ContextMenu component.",
     "usage": [
+      "DO: Use only menu collection nodes inside DropdownMenuContent. Arbitrary headers, notification lists and links belong in Popover + ListRow; development diagnostics and the dropdown-menu-non-menu-children audit rule name this fix.",
       "DO compose the full sub-part tree: DropdownMenu (root) → DropdownMenuTrigger (with asChild to delegate to your Button/icon) → DropdownMenuContent → DropdownMenuItem / DropdownMenuSeparator / DropdownMenuLabel / DropdownMenuGroup. Omitting any level (e.g. rendering DropdownMenuContent without DropdownMenu as ancestor) breaks Radix context and the menu will not open.",
       "DO use DropdownMenuTrigger with asChild and pass a godx-ui Button or icon Button as the child — never render a raw <button> or <div> as the trigger, and never omit asChild when the child is already a button-like element (double-button nesting breaks a11y).",
       "DO use variant='destructive' on DropdownMenuItem for irreversible actions (delete, revoke, void) — this applies the semantic destructive colour token automatically without any className override.",
@@ -13841,6 +13853,7 @@
     ],
     "tagline": "React Aria floating panel anchored to a trigger — always compose with PopoverTrigger + PopoverContent; never use a raw div overlay.",
     "usage": [
+      "DO: PopoverContent scrolls automatically when its available height caps content. Focus rings remain contained at scroll edges, including flush panels.",
       "HOVER CARD: `<Popover openOn=\"hover\"><PopoverTrigger asChild><a href=…>@yamada</a></PopoverTrigger><PopoverContent>…</PopoverContent></Popover>` for RICH preview content (an avatar + bio, an entity summary). For a short plain-text hint use Tooltip. DON'T put essential information only in a hover card — touch never opens it; make the same content reachable from the trigger's destination. There is no `HoverCard` component.",
       "DO compose: <Popover> → <PopoverTrigger asChild> → <Button/> and <PopoverContent>. All four parts are required for any popover to function; omitting PopoverTrigger or PopoverContent produces nothing.",
       "DO set `<PopoverContent width=\"auto\">` when the child brings its own measure — a Calendar, a chart, a fixed-width preview. The panel's own 18rem clips them, and a `w-*` utility on className is a per-call-site constant no service theme can retune, which is exactly what `flush` exists to avoid on the padding axis. `width=\"trigger\"` matches the anchor, the shape every select-like control wants.",
@@ -18526,6 +18539,11 @@
     "importPath": "@godxjp/ui/data-display",
     "name": "Image",
     "props": [
+      {
+        "description": "Reports resolved status, including cached images; error remains final while showing fallback.",
+        "name": "onStatusChange",
+        "type": "(status: \"loading\" | \"loaded\" | \"error\") => void"
+      },
       {
         "description": "Image URL.",
         "name": "src",
@@ -18547,7 +18565,7 @@
         "type": "string"
       },
       {
-        "description": "Painted over the frame until the picture loads; `true` = a muted block.",
+        "description": "After hydration, painted over the frame while the picture loads; SSR leaves pictures uncovered. `true` = a muted block. Child content can shrink to fit the frame.",
         "name": "placeholder",
         "type": "ReactNode | boolean"
       },

package/agent/index.json

@@ -2,9 +2,9 @@
   "counts": {
     "anti-ai-tells": 35,
     "components": 212,
-    "patterns": 28,
+    "patterns": 29,
     "rules": 44,
-    "tokens": 3198,
+    "tokens": 3203,
     "vocabulary": 16
   },
   "design": "https://raw.githubusercontent.com/godx-jp/godxjp-ui/main/agent/DESIGN.md",
@@ -54,19 +54,19 @@
   "note": "Pin to the tag that matches the @godxjp/ui version you installed. A catalog newer than your package describes props you do not have; older, and it hides props you do.",
   "read": {
     "live": "https://raw.githubusercontent.com/godx-jp/godxjp-ui/main/agent/index.json",
-    "pinned": "https://raw.githubusercontent.com/godx-jp/godxjp-ui/v33.24.0/agent/index.json"
+    "pinned": "https://raw.githubusercontent.com/godx-jp/godxjp-ui/v33.25.0/agent/index.json"
   },
   "source": "mcp/src/data — the same data @godxjp/ui-mcp serves — plus the foundation and semantic token tiers, read from src/tokens/*.css",
   "start": "https://raw.githubusercontent.com/godx-jp/godxjp-ui/main/agent/START-HERE.md",
   "tokenTiers": {
     "component": "per-part knobs, --{component}-{part}-{property}; usually leave these alone",
     "counts": {
-      "component": 2862,
+      "component": 2867,
       "foundation": 223,
       "semantic": 113
     },
     "foundation": "the seeds a consumer is invited to set — --primary, --background, --radius",
     "semantic": "named roles that follow the seeds — --ring, --text-link, --overlay-background"
   },
-  "version": "33.24.0"
+  "version": "33.25.0"
 }

package/agent/llms.txt

@@ -1,10 +1,10 @@
 # @godxjp/ui
 
-> A Japanese-enterprise React design system: 212 components, 3198 design tokens,
-> 44 cardinal rules. This file is the entry point for AI agents. Catalog version 33.24.0.
+> A Japanese-enterprise React design system: 212 components, 3203 design tokens,
+> 44 cardinal rules. This file is the entry point for AI agents. Catalog version 33.25.0.
 
 If your client can run a process, do not read these files — run the MCP server instead
-(`npx @godxjp/ui-mcp@33.24.0`). It is searchable and version-locked. These files exist for agents
+(`npx @godxjp/ui-mcp@33.25.0`). It is searchable and version-locked. These files exist for agents
 that can only fetch URLs.
 
 ## Start
@@ -15,11 +15,11 @@ that can only fetch URLs.
 
 ## Catalog
 
-- [patterns-index.json](https://raw.githubusercontent.com/godx-jp/godxjp-ui/main/agent/patterns-index.json): 28 whole-task patterns (name, tagline, tags). Start here when the task is a TASK — "build a settings page" — then fetch `patterns/<name>.json` for complete code.
+- [patterns-index.json](https://raw.githubusercontent.com/godx-jp/godxjp-ui/main/agent/patterns-index.json): 29 whole-task patterns (name, tagline, tags). Start here when the task is a TASK — "build a settings page" — then fetch `patterns/<name>.json` for complete code.
 - [components-index.json](https://raw.githubusercontent.com/godx-jp/godxjp-ui/main/agent/components-index.json): 47 KB — all 212 components as name, group, tagline, plus `absorbed`: the names that do NOT exist and map to it (`Combobox` → `Select`).
 - [components/&lt;Name&gt;.json](https://raw.githubusercontent.com/godx-jp/godxjp-ui/main/agent/components/Select.json): one file per component (1 KB–38 KB, median 5 KB). Read the index, then fetch only the ones you chose — this is the selective route, and the reason you do not need the blob.
 - [components.json](https://raw.githubusercontent.com/godx-jp/godxjp-ui/main/agent/components.json): 1.4 MB — every entry in one file. Most URL fetchers truncate a response this size without saying so; prefer the per-component files.
-- [tokens.json](https://raw.githubusercontent.com/godx-jp/godxjp-ui/main/agent/tokens.json): every design token with its value, the reason it exists, and its `tier` — 223 `foundation` seeds (`--primary`, `--background`, `--radius`: set these when you are handed a brand), 113 `semantic` roles, 2862 `component` knobs.
+- [tokens.json](https://raw.githubusercontent.com/godx-jp/godxjp-ui/main/agent/tokens.json): every design token with its value, the reason it exists, and its `tier` — 223 `foundation` seeds (`--primary`, `--background`, `--radius`: set these when you are handed a brand), 113 `semantic` roles, 2867 `component` knobs.
 - [vocabulary.json](https://raw.githubusercontent.com/godx-jp/godxjp-ui/main/agent/vocabulary.json): the controlled prop vocabulary — which prop name means what, across every component.
 - [rules.json](https://raw.githubusercontent.com/godx-jp/godxjp-ui/main/agent/rules.json): 44 cardinal rules.
 - [anti-ai-tells.json](https://raw.githubusercontent.com/godx-jp/godxjp-ui/main/agent/anti-ai-tells.json): 35 shapes that make generated UI look generated, each with its fix.
@@ -27,7 +27,7 @@ that can only fetch URLs.
 ## Pinning
 
 Every URL above tracks `main`. To pin to the release a project actually installed, swap `main` for
-the tag: `.../godx-jp/godxjp-ui/v33.24.0/agent/...`. A catalog that does not match the installed
+the tag: `.../godx-jp/godxjp-ui/v33.25.0/agent/...`. A catalog that does not match the installed
 package describes props that are absent, or hides props that are present, and says nothing either way.
 
 Pinned catalogs only exist for releases whose tag actually contains `agent/`. If `…/v<version>/agent/index.json` returns 404, that release predates this catalog: read `…/main/…` instead and compare `index.json` → `version` against the package you have, so you at least know which way it drifted.

package/agent/patterns/notice-bar.json

@@ -0,0 +1,16 @@
+{
+  "aliases": [
+    "consent-bar",
+    "cookie-consent"
+  ],
+  "code": "// Register noticeBarDocs copy in your application message catalogue (en/ja/vi recipe: docs/feedback/notice-bar.tsx).\n// Framework-Component Test: C3 FAIL; compose existing primitives.\nimport { useEffect, useRef, useState } from \"react\";\nimport { createPortal } from \"react-dom\";\nimport { Card, CardContent } from \"@godxjp/ui/data-display\";\nimport { Button, Text, Heading } from \"@godxjp/ui/general\";\nimport { Flex, PageContainer } from \"@godxjp/ui/layout\";\nimport { useTranslation } from \"@godxjp/ui/i18n\";\n\n/**\n * Composition, gh#1463. C1 PASS; C2 FAIL (ordinary region + native Tab order);\n * C3 FAIL (Card + Flex + Button + fixed section); C4/C5/C6 PASS; C7 FAIL\n * (persistent non-modal consent is not a named primitive in two reference libraries).\n * Consent policy/storage belongs to the application. No focus trap, live role or auto focus.\n * Portal to body avoids paint/transform ancestors turning fixed into a local pin.\n */\nexport default function Demo() {\n  const { t } = useTranslation();\n  const [decision, setDecision] = useState<string | null>(null);\n  const [mounted, setMounted] = useState(false);\n  const region = useRef<HTMLElement>(null);\n  const host = useRef<HTMLDivElement>(null);\n  const [direction, setDirection] = useState(\"ltr\");\n  useEffect(() => {\n    setDirection(host.current ? getComputedStyle(host.current).direction : \"ltr\");\n    setMounted(true);\n  }, []);\n  useEffect(() => {\n    const node = region.current;\n    if (!mounted || decision !== null || !node) return;\n    const root = document.documentElement;\n    const previous = root.style.getPropertyValue(\"--toast-offset-bottom\");\n    const priority = root.style.getPropertyPriority(\"--toast-offset-bottom\");\n    const base = getComputedStyle(root).getPropertyValue(\"--toast-offset-bottom\").trim() || \"0px\";\n    const publish = () => root.style.setProperty(\"--toast-offset-bottom\", `calc(${base} + ${node.offsetHeight}px)`);\n    publish();\n    const observer = new ResizeObserver(publish);\n    observer.observe(node);\n    return () => {\n      observer.disconnect();\n      if (previous) root.style.setProperty(\"--toast-offset-bottom\", previous, priority);\n      else root.style.removeProperty(\"--toast-offset-bottom\");\n    };\n  }, [mounted, decision]);\n  return <>\n    <div ref={host}><PageContainer title={t(\"noticeBarDocs.page\")}>\n      <Text as=\"p\">{t(\"noticeBarDocs.body\")}</Text>\n      <Button variant=\"outline\" onClick={() => setDecision(null)}>{t(\"noticeBarDocs.reopen\")}</Button>\n      {decision !== null && <Text as=\"p\">{t(decision)}</Text>}\n      <section id=\"privacy\"><Heading level={2}>{t(\"noticeBarDocs.privacy\")}</Heading><Text as=\"p\">{t(\"noticeBarDocs.policy\")}</Text></section>\n    </PageContainer></div>\n    {mounted && decision === null && createPortal(\n      <section ref={region} dir={direction} style={{position: \"fixed\", insetInline: 0, insetBlockEnd: 0, zIndex: \"var(--sticky-z-index)\", paddingBlockEnd: \"env(safe-area-inset-bottom, 0px)\", paddingInlineStart: direction === \"rtl\" ? \"env(safe-area-inset-right, 0px)\" : \"env(safe-area-inset-left, 0px)\", paddingInlineEnd: direction === \"rtl\" ? \"env(safe-area-inset-left, 0px)\" : \"env(safe-area-inset-right, 0px)\", background: \"hsl(var(--card))\", color: \"hsl(var(--card-foreground))\"}} role=\"region\" aria-label={t(\"noticeBarDocs.title\")}>\n        <Card><CardContent>\n          <Flex align=\"center\" justify=\"between\" gap=\"lg\" wrap>\n            <Flex direction=\"col\" gap=\"xs\" style={{flex: \"1 1 var(--page-measure-narrow)\", minInlineSize: 0, overflowWrap: \"anywhere\"}}>\n              <Text weight=\"medium\">{t(\"noticeBarDocs.title\")}</Text>\n              <Text as=\"p\">{t(\"noticeBarDocs.description\")} <a href=\"#privacy\" style={{textDecorationLine: \"underline\"}}>{t(\"noticeBarDocs.privacy\")}</a></Text>\n            </Flex>\n            <Flex gap=\"sm\" wrap>\n              <Button variant=\"outline\" onClick={() => setDecision(\"noticeBarDocs.declined\")}>{t(\"noticeBarDocs.decline\")}</Button>\n              <Button onClick={() => setDecision(\"noticeBarDocs.accepted\")}>{t(\"noticeBarDocs.accept\")}</Button>\n            </Flex>\n          </Flex>\n        </CardContent></Card>\n      </section>, document.body)}\n  </>;\n}\n",
+  "name": "notice-bar",
+  "tagline": "Fixed non-modal consent region: opaque Card, wrapping actions, safe-area padding, measured Toaster clearance; application owns consent policy. Recipe: docs/feedback/notice-bar.tsx, isolate feedback-notice-bar.",
+  "tags": [
+    "feedback",
+    "consent",
+    "cookie",
+    "notice",
+    "fixed"
+  ]
+}

package/agent/patterns-index.json

@@ -1,4 +1,19 @@
 [
+  {
+    "aliases": [
+      "consent-bar",
+      "cookie-consent"
+    ],
+    "name": "notice-bar",
+    "tagline": "Fixed non-modal consent region: opaque Card, wrapping actions, safe-area padding, measured Toaster clearance; application owns consent policy. Recipe: docs/feedback/notice-bar.tsx, isolate feedback-notice-bar.",
+    "tags": [
+      "feedback",
+      "consent",
+      "cookie",
+      "notice",
+      "fixed"
+    ]
+  },
   {
     "name": "common-fixes",
     "tagline": "Fix the most common @godxjp/ui consumer mistakes & visual bugs (StatCard double-border, grey Badge, crushed/empty table headers, washed-out sidebar footer, Inertia layout crash, SSR hydration). Before → after.",

package/agent/patterns.json

@@ -1,4 +1,20 @@
 [
+  {
+    "aliases": [
+      "consent-bar",
+      "cookie-consent"
+    ],
+    "code": "// Register noticeBarDocs copy in your application message catalogue (en/ja/vi recipe: docs/feedback/notice-bar.tsx).\n// Framework-Component Test: C3 FAIL; compose existing primitives.\nimport { useEffect, useRef, useState } from \"react\";\nimport { createPortal } from \"react-dom\";\nimport { Card, CardContent } from \"@godxjp/ui/data-display\";\nimport { Button, Text, Heading } from \"@godxjp/ui/general\";\nimport { Flex, PageContainer } from \"@godxjp/ui/layout\";\nimport { useTranslation } from \"@godxjp/ui/i18n\";\n\n/**\n * Composition, gh#1463. C1 PASS; C2 FAIL (ordinary region + native Tab order);\n * C3 FAIL (Card + Flex + Button + fixed section); C4/C5/C6 PASS; C7 FAIL\n * (persistent non-modal consent is not a named primitive in two reference libraries).\n * Consent policy/storage belongs to the application. No focus trap, live role or auto focus.\n * Portal to body avoids paint/transform ancestors turning fixed into a local pin.\n */\nexport default function Demo() {\n  const { t } = useTranslation();\n  const [decision, setDecision] = useState<string | null>(null);\n  const [mounted, setMounted] = useState(false);\n  const region = useRef<HTMLElement>(null);\n  const host = useRef<HTMLDivElement>(null);\n  const [direction, setDirection] = useState(\"ltr\");\n  useEffect(() => {\n    setDirection(host.current ? getComputedStyle(host.current).direction : \"ltr\");\n    setMounted(true);\n  }, []);\n  useEffect(() => {\n    const node = region.current;\n    if (!mounted || decision !== null || !node) return;\n    const root = document.documentElement;\n    const previous = root.style.getPropertyValue(\"--toast-offset-bottom\");\n    const priority = root.style.getPropertyPriority(\"--toast-offset-bottom\");\n    const base = getComputedStyle(root).getPropertyValue(\"--toast-offset-bottom\").trim() || \"0px\";\n    const publish = () => root.style.setProperty(\"--toast-offset-bottom\", `calc(${base} + ${node.offsetHeight}px)`);\n    publish();\n    const observer = new ResizeObserver(publish);\n    observer.observe(node);\n    return () => {\n      observer.disconnect();\n      if (previous) root.style.setProperty(\"--toast-offset-bottom\", previous, priority);\n      else root.style.removeProperty(\"--toast-offset-bottom\");\n    };\n  }, [mounted, decision]);\n  return <>\n    <div ref={host}><PageContainer title={t(\"noticeBarDocs.page\")}>\n      <Text as=\"p\">{t(\"noticeBarDocs.body\")}</Text>\n      <Button variant=\"outline\" onClick={() => setDecision(null)}>{t(\"noticeBarDocs.reopen\")}</Button>\n      {decision !== null && <Text as=\"p\">{t(decision)}</Text>}\n      <section id=\"privacy\"><Heading level={2}>{t(\"noticeBarDocs.privacy\")}</Heading><Text as=\"p\">{t(\"noticeBarDocs.policy\")}</Text></section>\n    </PageContainer></div>\n    {mounted && decision === null && createPortal(\n      <section ref={region} dir={direction} style={{position: \"fixed\", insetInline: 0, insetBlockEnd: 0, zIndex: \"var(--sticky-z-index)\", paddingBlockEnd: \"env(safe-area-inset-bottom, 0px)\", paddingInlineStart: direction === \"rtl\" ? \"env(safe-area-inset-right, 0px)\" : \"env(safe-area-inset-left, 0px)\", paddingInlineEnd: direction === \"rtl\" ? \"env(safe-area-inset-left, 0px)\" : \"env(safe-area-inset-right, 0px)\", background: \"hsl(var(--card))\", color: \"hsl(var(--card-foreground))\"}} role=\"region\" aria-label={t(\"noticeBarDocs.title\")}>\n        <Card><CardContent>\n          <Flex align=\"center\" justify=\"between\" gap=\"lg\" wrap>\n            <Flex direction=\"col\" gap=\"xs\" style={{flex: \"1 1 var(--page-measure-narrow)\", minInlineSize: 0, overflowWrap: \"anywhere\"}}>\n              <Text weight=\"medium\">{t(\"noticeBarDocs.title\")}</Text>\n              <Text as=\"p\">{t(\"noticeBarDocs.description\")} <a href=\"#privacy\" style={{textDecorationLine: \"underline\"}}>{t(\"noticeBarDocs.privacy\")}</a></Text>\n            </Flex>\n            <Flex gap=\"sm\" wrap>\n              <Button variant=\"outline\" onClick={() => setDecision(\"noticeBarDocs.declined\")}>{t(\"noticeBarDocs.decline\")}</Button>\n              <Button onClick={() => setDecision(\"noticeBarDocs.accepted\")}>{t(\"noticeBarDocs.accept\")}</Button>\n            </Flex>\n          </Flex>\n        </CardContent></Card>\n      </section>, document.body)}\n  </>;\n}\n",
+    "name": "notice-bar",
+    "tagline": "Fixed non-modal consent region: opaque Card, wrapping actions, safe-area padding, measured Toaster clearance; application owns consent policy. Recipe: docs/feedback/notice-bar.tsx, isolate feedback-notice-bar.",
+    "tags": [
+      "feedback",
+      "consent",
+      "cookie",
+      "notice",
+      "fixed"
+    ]
+  },
   {
     "code": "// ───────────────────────────────────────────────────────────────────────\n// 0) ★ MOST COMMON: <Card> body has NO padding (content is flush against the edges)\n//    Cause: the bare <Card> has ZERO inner padding — it MUST contain <CardContent>.\n//    Don't hand-roll padding with className=\"p-4\" on the Card either.\n// ❌  <Card><Flex direction=\"col\" gap=\"md\">…fields…</Flex></Card>   // flush, no padding\n// ❌  <Card className=\"p-4\">…fields…</Card>                          // hand-rolled padding\n// ✅  <Card><CardContent><Flex direction=\"col\" gap=\"md\">…fields…</Flex></CardContent></Card>\n//    Titles → <CardHeader><CardTitle>. Only go flush deliberately for a full-bleed table:\n// ✅  <Card><CardContent flush><DataTable/></CardContent></Card>\n//    GENERAL RULE — compose godx-ui primitives FULLY; never hand-roll what one ships:\n//      padding → CardContent (not p-4) · controls → Input/Select/Button (not raw <input>/<select>/<button>)\n//      vertical spacing → Flex direction=\"col\" gap (not space-y-*) · empty rows → DataTable's built-in\n//      empty / <EmptyState> (not a custom data.length===0 guard). If a primitive exists, USE it.\n\n// 1) StatCard shows a DOUBLE border (too thick)\n//    Cause: StatCard IS already a bordered Card. Don't wrap it.\n// ❌  <Card><CardContent><StatCard label=\"x\" value=\"1\" /></CardContent></Card>\n// ✅  dashboard only, with comparison/trend:\n//     <ResponsiveGrid columns={4}><StatCard label=\"売上\" value=\"¥8.2M\" delta=\"+12%\" /></ResponsiveGrid>\n//    A list or detail page has NO StatCard row — a row count is not a KPI (Pagination showTotal).\n\n// 2) Badge renders grey with a ○ (no colour) for localized/tier labels\n//    Cause: it auto-maps only English lifecycle keys.\n// ✅  <Badge status=\"active\">公開中</Badge>                       // lifecycle → keep icon\n// ✅  <Badge status=\"プレミアム\" tone=\"neutral\" icon={null} />   // tier → ONE neutral tone\n//    Colour is for status only; a tier/category/scope is plain text or a neutral pill.\n\n// 3) Table text collapses to one char per line, or a chip wraps\n// ✅  give long columns a width:  { key: \"name\", header: \"氏名\", width: \"w-64\" }\n//    (cells + chips are pinned white-space: nowrap by the library.)\n\n// 4) Empty (icon/action) column header shows a blank grey block\n// ✅  header: \"\" renders a transparent cell — leave it empty, don't inject a space.\n\n// 5) DataTable columns are crushed / squeezed\n//    Cause: the table is nested in a narrow grid column.\n// ❌  <ResponsiveGrid columns={3}><div className=\"lg:col-span-2\"><Card><DataTable/></Card></div></ResponsiveGrid>\n// ✅  Table gets its OWN full-width row: <Card><CardContent flush><DataTable/></CardContent></Card>\n\n// 6) Toolbar (filter bar) has no padding (sticks to the edge)\n//    Cause: it's inside CardContent flush (flush strips padding — that's for tables).\n// ❌  <Card><CardContent flush><Toolbar/><DataTable/></CardContent></Card>\n// ✅  <Toolbar/>  then  <Card><CardContent flush><DataTable/></CardContent></Card>\n\n// 7) Sidebar footer looks washed-out / off-design\n//    Cause: raw opacity-*/text-[11px]. Use semantic tokens.\n// ✅  <div className=\"text-muted-foreground text-xs\">\n//        <div className=\"text-foreground font-medium\">{name}</div><div>{role}</div></div>\n\n// 8) Inertia: \"Objects are not valid as a React child {errors, auth, …}\"\n//    Cause: persistent layout passed as a render fn. Use the ARRAY form.\n// ❌  Page.layout = (page) => <Layout>{page}</Layout>\n// ✅  Page.layout = [Layout]            // Layout is ({children}) => ...\n\n// 9) Inertia v3 hydration mismatch (\"server rendered text didn't match the client\")\n//    Cause: Math.random()/argless new Date() during render (SSR ≠ client).\n// ✅  seed deterministically by index, or compute in an event handler.\n\n// 10) Hide a column on mobile / sign-aware KPI delta\n// ✅  columns: [{ key: \"email\", header: \"メール\", hiddenOnMobile: true }]\n// ✅  <StatCard label=\"売上\" value=\"¥8.2M\" delta=\"+12%\" />   // + green / - red; inverse flips",
     "name": "common-fixes",

package/agent/rules.json

@@ -55,7 +55,7 @@
     "title": "TypeScript strict"
   },
   {
-    "body": "The runtime stack is what `package.json` declares: react-aria-components / react-aria / react-stately, cmdk, sonner, lucide-react, @tanstack/react-table, react-day-picker, class-variance-authority + clsx + tailwind-merge. A new dependency needs an ADR saying why it is the canonical choice and why an existing one cannot do it.",
+    "body": "The runtime stack is what `package.json` declares: react-aria-components / react-aria / react-stately, cmdk, sonner, lucide-react, @tanstack/react-table, react-day-picker, class-variance-authority + clsx + tailwind-merge. Consumers must import toast from @godxjp/ui (or @godxjp/ui/feedback), never directly from sonner: two installed versions own separate toast stores and silently miss the kit Toaster. The audit rule no-direct-sonner-import enforces this. A new dependency needs an ADR saying why it is the canonical choice and why an existing one cannot do it.",
     "number": 14,
     "title": "Every third-party library is a deliberate, declared choice"
   },
@@ -160,7 +160,7 @@
     "title": "Long text columns get an explicit width"
   },
   {
-    "body": "Author and verify every page at 320–390px FIRST. Page sections are spaced by `PageContainer` itself (`--page-body-gap` between its direct children). Inside a section spacing comes only from `Flex` `gap` (vertical rhythm = `Flex direction=\"col\"`, control rows = the default `direction=\"row\"`) + `ResponsiveGrid columns={2|3|4}` (which collapse to a single column on narrow screens) — never raw `p-*` / `gap-*` / `space-*` utilities for page layout (the static audit rejects them). Styles are loaded whole: `@godxjp/ui/styles` or `styles/core`, never a hand-picked set of layers. They differ ONLY in the 729 bundled CJK `@font-face` declarations, and that difference is most of the CSS: 367 KB vs 86 KB gzip for a 15-component app (gh#971) — pick `styles/core` whenever the app loads fonts another way.",
+    "body": "Author and verify every page at 320–390px FIRST. Page sections are spaced by `PageContainer` itself (`--page-body-gap` between its direct children). Inside a section spacing comes only from `Flex` `gap` (vertical rhythm = `Flex direction=\"col\"`, control rows = the default `direction=\"row\"`) + `ResponsiveGrid columns={2|3|4}` (which collapse to a single column on narrow screens) — never raw `p-*` / `gap-*` / `space-*` utilities for page layout (the static audit rejects them). Load `@godxjp/ui/styles` (Tailwind v4) or `styles.css` (precompiled) for all families, or `styles/application` to omit editorial/catalog/holding layouts; `styles/editorial` adds that family after the application entry. Existing `styles/core` still carries all families. Fonts are opt-in. For a content-aware subset run `npx @godxjp/ui prune-css src --out <your stylesheet>` and import its generated file instead; add `--precompiled` without Tailwind, or `--exclude-family editorial` to reject accidental use of the omitted family. Both paths use the package-owned layer dependency graph. Re-run after upgrades/import changes; never hand-pick layout files.",
     "number": 40,
     "title": "Pages are mobile-first"
   },