@godxjp/ui 31.31.8 → 32.0.0

package/README.md

@@ -1,10 +1,12 @@
 # @godxjp/ui
 
-The shared React UI framework for every godx surface (admin, agency portal, handheld).
+A React UI framework built on design tokens: accessible components, a controlled prop vocabulary,
+and a machine-readable catalog so coding agents use the real API instead of guessing. It is for any
+team; GoDX is one preset on top of it.
 
-- 📦 **npm:** `@godxjp/ui` (published) · MCP server `@godxjp/ui-mcp`
-- 🌐 **Live preview / catalog:** **https://godx-jp.github.io/godxjp-ui/** (components · tokens · props)
-- 🤖 **Agents:** the `@godxjp/ui-mcp` server exposes the full catalog (`get_component`, `list_primitives`, `search_components`) so coding agents use the real API instead of hand-rolling.
+- npm: `@godxjp/ui` (published) · MCP server `@godxjp/ui-mcp`
+- Live preview / catalog: **https://godx-jp.github.io/godxjp-ui/** (components · tokens · props)
+- Agents: the `@godxjp/ui-mcp` server exposes the full catalog (`get_component`, `list_primitives`, `search_components`) so coding agents use the real API instead of hand-rolling.
 
 ```bash
 npm i @godxjp/ui
@@ -14,15 +16,19 @@ npm i @godxjp/ui
 
 ## Using this from an AI agent
 
-The catalog — 165 components, 1616 tokens, 47 cardinal rules — is published in two forms from one
+<!-- agent-catalog-counts:start -->
+
+The catalog — 161 components, 2183 tokens, 43 cardinal rules — is published in two forms from one
 source. **Entry point for either: [`AGENTS.md`](AGENTS.md).**
+<!-- agent-catalog-counts:end -->
 
 ### If your agent can run a process
 
 Claude Code · Codex CLI · Cursor · any MCP client:
 
 ```bash
-npx @godxjp/ui sync-rules
+npx godxjp-ui sync-rules --dry-run   # preview the files it would create or change
+npx godxjp-ui sync-rules             # write them
 ```
 
 Writes `.mcp.json`, `CLAUDE.md` and `.ai/rules/` into the consumer repo and wires
@@ -30,27 +36,30 @@ Writes `.mcp.json`, `CLAUDE.md` and `.ai/rules/` into the consumer repo and wire
 **locked to the version on disk** — the failure it prevents is an agent being told a prop does not
 exist because the catalog was two minors behind (gh#789).
 
-The package's postinstall runs this on every install, so an upgrade moves the MCP pin forward by
-itself. **Where install scripts are off** (`npm config get ignore-scripts` is `true`, which some CI
-images and machines set), it never runs: run `npx @godxjp/ui sync-rules` yourself after each upgrade,
-or the agent keeps asking the catalog of the version you first installed.
+**Setup is explicit.** Installing the package writes nothing. Run `npx godxjp-ui sync-rules` once
+after installing and again after each upgrade, so the MCP pin moves with the package.
 
 ### If your agent can only fetch URLs
 
 ChatGPT on the web, Claude.ai, or any client without a local process. The same data is served as
 static files straight from this public repo — no hosting, no deploy step:
 
-| file                                                                                                                    | size    | what it is                                                                                             |
-| ----------------------------------------------------------------------------------------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------ |
-| [`agent/START-HERE.md`](https://raw.githubusercontent.com/godx-jp/godxjp-ui/main/agent/START-HERE.md)                   | 6 KB    | **read first** — self-contained: the four rules, the token override model, a page that passes review   |
-| [`agent/llms.txt`](https://raw.githubusercontent.com/godx-jp/godxjp-ui/main/agent/llms.txt)                             | 2 KB    | the [llms.txt](https://llmstxt.org/) entry point                                                       |
-| [`agent/index.json`](https://raw.githubusercontent.com/godx-jp/godxjp-ui/main/agent/index.json)                         | 2 KB    | manifest: version, counts, every file's URL                                                            |
-| [`agent/components-index.json`](https://raw.githubusercontent.com/godx-jp/godxjp-ui/main/agent/components-index.json)   | 42 KB   | all 165 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–32 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.1 MB  | all 165 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)                       | 0.6 MB  | every design token, its value and why it exists                                                        |
-| [`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)                         | 17 KB   | the 47 cardinal rules                                                                                  |
+<!-- agent-catalog-files:start -->
+
+<!-- prettier-ignore-start -->
+| file | size | what it is |
+| --- | --- | --- |
+| [`agent/START-HERE.md`](https://raw.githubusercontent.com/godx-jp/godxjp-ui/main/agent/START-HERE.md) | 11 KB | **read first** — self-contained: the four rules, the token override model, a page that passes review |
+| [`agent/llms.txt`](https://raw.githubusercontent.com/godx-jp/godxjp-ui/main/agent/llms.txt) | 3 KB | the [llms.txt](https://llmstxt.org/) entry point |
+| [`agent/index.json`](https://raw.githubusercontent.com/godx-jp/godxjp-ui/main/agent/index.json) | 3 KB | manifest: version, counts, every file's URL |
+| [`agent/components-index.json`](https://raw.githubusercontent.com/godx-jp/godxjp-ui/main/agent/components-index.json) | 47 KB | all 161 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–36 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.2 MB | all 161 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) | 841 KB | all 2183 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) | 21 KB | the 43 cardinal rules |
+<!-- prettier-ignore-end -->
+<!-- agent-catalog-files:end -->
 
 Pasteable bootstrap:
 
@@ -100,7 +109,7 @@ src/styles/      CSS that styles components by [data-slot]; density.css = the on
 src/components/  React components by group (data-display, data-entry, layout, feedback, …)
 src/props/       Prop type system: vocabulary/ (atomic) + components/ + registry.ts (NORMATIVE, CI-checked)
 src/lib/         cn(), control-styles, variants, hooks
-examples/        *.preview.tsx — Storybook-style stories (rendered by the preview app + Pages site)
+docs/            real-screen example pages (rendered by the preview app + Pages site)
 preview/         The preview app (vite, :6008) → also deployed to GitHub Pages
 ```
 
@@ -110,22 +119,22 @@ A value is defined **once** as a CSS var (`--primary`), mapped to a utility in t
 
 ## Component groups
 
-| Group              | Import                    | Examples                                                                                                                                                                                                                                |
-| ------------------ | ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **Layout**         | `@godxjp/ui/layout`       | `Flex`, `PageContainer`, `ResponsiveGrid`, `AppShell`, `Sidebar`, `Separator`, `AspectRatio`, `Resizable`                                                                                                                               |
-| **General**        | `@godxjp/ui/general`      | `Button`                                                                                                                                                                                                                                |
-| **Data Entry**     | `@godxjp/ui/data-entry`   | `Input`, `Select`, `FormField`, `Field`, `DatePicker`, `TimePicker`, `Combobox`, `Switch`, `Toggle`, `Upload`, `Cascader`, `TreeSelect`, `ColorPicker`, `Slider`, `PasswordInput`, `PasswordStrength`, `InputOTP`, `Rating`, `TagInput` |
-| **Data Display**   | `@godxjp/ui/data-display` | `Table`, `DataTable`, `Card`, `StatCard`, `Badge`, `Avatar`, `Descriptions`, `Timeline`, `EmptyState`, `Progress`, `QrCode`, `CredentialReveal`, `Accordion`, `HoverCard`, `Carousel`, `Popover`, `Collapsible`                         |
-| **Feedback**       | `@godxjp/ui/feedback`     | `Dialog`, `AlertDialog`, `Sheet` (side), `Drawer` (bottom-sheet), `Toast`, `Skeleton`, `Alert`, `Tooltip`                                                                                                                               |
-| **Query**          | `@godxjp/ui/query`        | `DataState`, `InfiniteQueryState` (adapter subpath — pulls TanStack Query; no router)                                                                                                                                                   |
-| **React Router**   | `@godxjp/ui/react-router` | `PrefetchLink` — imports the optional `react-router-dom` peer, so it is kept out of `/query` (gh#996)                                                                                                                                   |
-| **Navigation**     | `@godxjp/ui/navigation`   | `Tabs`, `Toolbar`, `DropdownMenu`, `Steps`, `Pagination`, `Breadcrumb`, `AppSettingPicker`                                                                                                                                              |
-| **App**            | `@godxjp/ui/app`          | `AppProvider`, `useDateTime` (adapter — i18n/datetime singleton)                                                                                                                                                                        |
-| **Datetime**       | `@godxjp/ui/datetime`     | `formatDate` (mandatory for display)                                                                                                                                                                                                    |
-| **Form**           | `@godxjp/ui/form`         | `useZodForm`, `FormRoot` (adapter subpath — pulls react-hook-form)                                                                                                                                                                      |
-| **Hooks**          | `@godxjp/ui/hooks`        | `useIsMobile`, `useMediaQuery`                                                                                                                                                                                                          |
-| **shadcn paths**   | `@godxjp/ui/ui`           | Thin re-exports for shadcn-style imports (tree-shakeable)                                                                                                                                                                               |
-| **Admin (legacy)** | `@godxjp/ui/admin`        | Compound admin exports                                                                                                                                                                                                                  |
+| Group              | Import                    | Examples                                                                                                                                                                                                        |
+| ------------------ | ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Layout**         | `@godxjp/ui/layout`       | `Flex`, `PageContainer`, `ResponsiveGrid`, `AppShell`, `Sidebar`, `Breadcrumb`, `Separator`, `AspectRatio`, `ResizablePanelGroup`                                                                               |
+| **General**        | `@godxjp/ui/general`      | `Button`                                                                                                                                                                                                        |
+| **Data Entry**     | `@godxjp/ui/data-entry`   | `Input`, `Select`, `FormField`, `Field`, `DatePicker`, `TimePicker`, `Switch`, `Toggle`, `Upload`, `Cascader`, `TreeSelect`, `ColorPicker`, `Slider`, `PasswordInput`, `PasswordStrength`, `InputOTP`, `Rating` |
+| **Data Display**   | `@godxjp/ui/data-display` | `Table`, `DataTable`, `Card`, `StatCard`, `Badge`, `Avatar`, `Descriptions`, `Timeline`, `EmptyState`, `Progress`, `QrCode`, `CredentialReveal`, `Accordion`, `Popover`, `Collapsible`                          |
+| **Feedback**       | `@godxjp/ui/feedback`     | `Dialog`, `AlertDialog`, `Sheet` (side or bottom), `Toaster` / `toast`, `Skeleton`, `Alert`, `Tooltip`                                                                                                          |
+| **Query**          | `@godxjp/ui/query`        | `DataState`, `InfiniteQueryState` (adapter subpath — pulls TanStack Query; no router)                                                                                                                           |
+| **React Router**   | `@godxjp/ui/react-router` | `PrefetchLink` — imports the optional `react-router-dom` peer, so it is kept out of `/query` (gh#996)                                                                                                           |
+| **Navigation**     | `@godxjp/ui/navigation`   | `Tabs`, `Toolbar`, `DropdownMenu`, `Steps`, `Pagination`, `AppSettingPicker`                                                                                                                                    |
+| **App**            | `@godxjp/ui/app`          | `AppProvider`, `useDateTime` (adapter — i18n/datetime singleton)                                                                                                                                                |
+| **Datetime**       | `@godxjp/ui/datetime`     | `formatDate` (mandatory for display)                                                                                                                                                                            |
+| **Form**           | `@godxjp/ui/form`         | `useZodForm`, `FormRoot` (adapter subpath — pulls react-hook-form)                                                                                                                                              |
+| **Hooks**          | `@godxjp/ui/hooks`        | `useIsMobile`, `useMediaQuery`                                                                                                                                                                                  |
+| **shadcn paths**   | `@godxjp/ui/ui`           | Thin re-exports for shadcn-style imports (tree-shakeable)                                                                                                                                                       |
+| **Admin (legacy)** | `@godxjp/ui/admin`        | Compound admin exports                                                                                                                                                                                          |
 
 ---
 
@@ -133,116 +142,88 @@ A value is defined **once** as a CSS var (`--primary`), mapped to a utility in t
 
 Replace these at the call site:
 
-| Removed / renamed (≤ v8)                  | Replacement (v11)                                   |
-| ----------------------------------------- | --------------------------------------------------- |
-| `Stack`                                   | `Flex direction="col"`                              |
-| `Inline`                                  | `Flex` (default `direction="row"`)                  |
-| `Autocomplete`                            | `Select` with `showSearch` + `options`              |
-| `CountrySelect`                           | `AppSettingPicker kind="country"`                   |
-| `LocalePicker`                            | `AppSettingPicker kind="language"`                  |
-| `CountryOptionLabel`                      | `Intl.DisplayNames` (ISO 3166-1 α-2) — no component |
-| `SwitchField`                             | `Field` + `Switch`                                  |
-| `CardStat`                                | `StatCard`                                          |
-| `KeyValueGrid`                            | `Descriptions`                                      |
-| `ProgressMeter`                           | `Progress`                                          |
-| `FilterBar`                               | `Toolbar`                                           |
-| `ChoiceField`                             | `Field`                                             |
-| `SkeletonCard`                            | `SkeletonStat`                                      |
-| `StatusBadge`                             | `Badge` (`status` / `tone`)                         |
-| `DialogConfirm` / `Dialog mode="confirm"` | `AlertDialog`                                       |
-
-The full data-grid feature set (sort / search / column visibility / paging) is now built into the one `DataTable` (`@godxjp/ui/data-display`) — TanStack-powered, with the lean `data` + `columns` API for the common case and the compound parts (`DataTable.Search` / `.ViewOptions` / `.Pagination` …) for the rich chrome. The separate `@godxjp/ui/data-grid` (`DataGrid`) subpath has been merged in and removed.
+| Removed / renamed (≤ v8)                | Replacement (v11)                                   |
+| --------------------------------------- | --------------------------------------------------- |
+| `Stack`                                 | `Flex direction="col"`                              |
+| `Inline`                                | `Flex` (default `direction="row"`)                  |
+| `Autocomplete`                          | `Select` with `showSearch` + `options`              |
+| `CountrySelect`                         | `AppSettingPicker kind="country"`                   |
+| `LocalePicker`                          | `AppSettingPicker kind="language"`                  |
+| `CountryOptionLabel`                    | `Intl.DisplayNames` (ISO 3166-1 α-2) — no component |
+| `SwitchField`                           | `Field` + `Switch`                                  |
+| `CardStat`                              | `StatCard`                                          |
+| `KeyValueGrid`                          | `Descriptions`                                      |
+| `ProgressMeter`                         | `Progress`                                          |
+| `FilterBar` (still exported, an alias)  | `Toolbar`                                           |
+| `ChoiceField`                           | `Field`                                             |
+| `SkeletonCard`                          | `SkeletonStat`                                      |
+| `StatusBadge` (still exported)          | `Badge` (`status` / `tone`)                         |
+| `DialogConfirm` (a confirm-mode dialog) | `AlertDialog`                                       |
+
+The full data-grid feature set (sort / search / column visibility / paging) is now built into the one `DataTable` (`@godxjp/ui/data-display`) — TanStack-powered, with the lean `data` + `columns` API for the common case and the compound parts (`DataTable.Search` / `.ViewOptions` / `.Pagination` …) for the rich chrome. The former separate data-grid subpath is gone: there is one `DataTable`.
 
 ---
 
 ## Consumer setup — theme is self-contained
 
-The framework ships colors, the type scale, the wa-iro palette, and (opt-in) bundled fonts (M PLUS 2 + Noto Sans JP fallback via `@fontsource`). A consumer's entire styling surface is **one import + content sources** — no `:root` overrides, no font `<link>`:
+The framework ships colors, the type scale, spacing, density and the component layers. Fonts are
+opt-in (below). A consumer's entire styling surface is **one import + content sources**, with no
+`:root` overrides and no font `<link>`.
+
+### Without Tailwind
+
+```ts
+import "@godxjp/ui/styles.css"; // precompiled, no Tailwind needed
+```
+
+### With Tailwind v4
 
 ```css
 /* resources/css/app.css */
-@import "@godxjp/ui/styles";
+@import "@godxjp/ui/styles"; /* unchanged */
 @source "../js/**/*.{ts,tsx}";
 @source "../views";
 ```
 
-### Where the CSS weight actually is — the font faces, not the components
-
-`@godxjp/ui/styles` is the zero-config all-in-one: every component's layers **plus 729 `@font-face`
-declarations** for the bundled CJK faces. Those declarations are render-blocking CSS on every page,
-separate from the font FILES (which load lazily, per glyph range). Measured on a fresh Vite 8 +
-Tailwind v4 app using 15 components (gh#971):
+### Fonts (opt-in since v32)
 
-| entry                    | CSS emitted | gzip       |
-| ------------------------ | ----------- | ---------- |
-| `@godxjp/ui/styles`      | 1,303,803 B | **367 KB** |
-| `@godxjp/ui/styles/core` | 581,210 B   | **86 KB**  |
+The styles entry no longer bundles any font. Install the families you want and import the font
+sheet after the styles import; the GoDX preset does this for you:
 
-So if CSS weight matters, **the one change that moves it is the import line** — 77% of it is the face
-declarations. `core` is not a per-component slice: it still carries every component's layers (about
-64 KB gzip for all ~165), it only drops the faces. Load fonts another way (next/font, a system stack,
-your own `@font-face`) and take the same layers without them:
-
-```css
-@import "@godxjp/ui/styles/core"; /* every component layer, no @font-face */
+```bash
+pnpm add @fontsource/noto-sans-jp @fontsource/m-plus-2
 ```
 
-Supplying Noto Sans JP yourself and want the cold-visit swap not to reflow the page? Take the
-third entry instead — the same layers plus the six metric-matched fallback faces, whose `src` is
-`local()`-only, so it costs **zero network bytes** over `core`:
-
 ```css
-@import "@godxjp/ui/styles/core-with-fallbacks"; /* core + 6 local()-only faces */
+@import "@godxjp/ui/styles/fonts.css"; /* after the styles import */
 ```
 
-Then name the family directly after your own face:
-`--font-sans-base: "Noto Sans JP", "Noto Sans JP Fallback", system-ui, sans-serif;`
-
-`core` stays at **zero** `@font-face` on purpose — `grep -c '@font-face'
-node_modules/@godxjp/ui/dist/styles/core.css` → `0` is the promise, so the fallbacks got their own
-entry rather than being folded in.
-
-Japanese app that wants the bundled face without the per-screen round-trips? The fourth entry
-replaces the 729 sliced faces with one merged file per weight, JIS X 0208 level 1:
-
-```css
-@import "@godxjp/ui/styles/core-with-jis-level1"; /* core + fallbacks + 3 merged faces */
-```
+Skip it to use your own face or a system stack: name it with `--font-sans-base` (see
+[docs/CUSTOMER-THEMING.md](docs/CUSTOMER-THEMING.md)).
 
-**3 requests, ~1.53 MB, all on first paint** — against 150 requests and 1,772,728 bytes for a
-694-character Japanese screen on `styles`, spread across screens. It does not cover JIS level 2
-(rare-surname kanji fall through to the platform face, so name one after ours) and it loses to the
-slices below roughly 620 distinct characters. Full table and reasoning in
-[docs/CUSTOMER-THEMING.md](docs/CUSTOMER-THEMING.md).
-
-> **Do not cherry-pick `*-layout.css` files.** Layers depend on each other (a
-> Select's rows, a menu's surface, a form's rhythm live in shared rules) and a
-> missing layer fails silently: menus render with no background, rows with no
-> height. `styles`, `styles/core`, `styles/core-with-fallbacks` and
-> `styles/core-with-jis-level1` are the four supported entries; the runtime `visual-audit` flags a
-> page whose layers are incomplete (`css-layers-missing`). The one supported way to ship LESS
-> than `core` is `prune-css` below — the tool slices along the dependency graph the package
-> ships, so it cannot forget a layer the way a hand-picked list does.
+> **Do not cherry-pick `*-layout.css` files.** Layers depend on each other (a Select's rows, a
+> menu's surface, a form's rhythm live in shared rules) and a missing layer fails silently: menus
+> render with no background, rows with no height. The runtime `visual-audit` flags a page whose
+> layers are incomplete (`css-layers-missing`). The one supported way to ship LESS than the full
+> styles entry is `prune-css` below: it slices along the dependency graph the package ships, so it
+> cannot forget a layer the way a hand-picked list does.
 
 ### prune-css — ship only the component layers you use (gh#971)
 
-`core` still carries every component's layers (~64 KB gzip for all ~165). If that remainder
-matters, let the package slice it:
+The styles entry carries every component's layers. If that weight matters, let the package slice it:
 
 ```bash
-npx @godxjp/ui prune-css resources/js --out resources/css/godx-ui.css   # --fonts for the bundled faces
+npx godxjp-ui prune-css resources/js --out resources/css/godx-ui.css
 ```
 
-It scans your sources for `@godxjp/ui` imports, resolves the CSS layer dependency closure from
-the graph shipped in `dist/styles/layers.json` (what each component's internals render is part
-of the graph — a `DataTable` still gets its dropdown and pagination surfaces), and emits a file
-that imports the foundation plus only the needed layers, in `styles/index.css`'s exact order.
-Import that file INSTEAD of `@godxjp/ui/styles`. Defaults mirror `styles/core` (no
-`@font-face`); the sonner / react-day-picker vendor sheets come along only when a used
-component renders them. **Re-run it whenever the set of components you use changes and after
-every upgrade** — the emitted header says so, and the tool refuses to run against a manifest
-from a different package version. Measured on gh#971's 15-component app: 368 KB gzip
-(`styles`) → 86 KB (`core`) → 75 KB pruned; a small 8-component app lands at 55 KB.
+It scans your sources for `@godxjp/ui` imports, resolves the CSS layer dependency closure from the
+graph shipped in `dist/styles/layers.json` (what each component's internals render is part of the
+graph — a `DataTable` still gets its dropdown and pagination surfaces), and emits a file that
+imports the foundation plus only the needed layers, in `styles/index.css`'s exact order. Import
+that file INSTEAD of `@godxjp/ui/styles`. The sonner / react-day-picker vendor sheets come along
+only when a used component renders them. **Re-run it whenever the set of components you use
+changes and after every upgrade** — the emitted header says so, and the tool refuses to run against
+a manifest from a different package version.
 
 ## Golden ratio (φ ≈ 1.618)
 

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` 31.31.8.** If the project you are editing has a different
+**This catalog describes `@godxjp/ui` 32.0.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.
@@ -43,28 +43,28 @@ Then ask it: `search_components`, `get_component`, `get_tokens`, `get_rule`, `li
 **You cannot run a process** (ChatGPT web · Claude.ai · anything fetching URLs)
 → These files are for you. Fetch in this order:
 
-0. `patterns-index.json` — 21 whole-task patterns as name + tagline + tags. **If your
+0. `patterns-index.json` — 22 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".
-1. `components-index.json` — 51 KB, all 185 components as name + group +
+1. `components-index.json` — 47 KB, all 161 components as name + group +
    tagline. Read this when you already know the SHAPE you need. Each entry may carry `absorbed`:
    names that **do not exist** and map to it — `Combobox`, `Autocomplete`, `CountrySelect` and
    `SearchSelect` are all `Select`. If you are about to hand-roll something, search this field
    first; it exists because that is the mistake.
 2. `components/<Name>.json` — one file per component (1 KB–36 KB, median 6 KB), carrying its props,
    its `importPath`, and its examples. Fetch only the handful you picked in step 1.
-3. `rules.json` — 50 cardinal rules. The ones about raw HTML and hardcoded colour are not
+3. `rules.json` — 43 cardinal rules. The ones about raw HTML and hardcoded colour are not
    style advice.
-4. `tokens.json` — 2188 design tokens, each tagged with its `tier`. **If you were handed a
-   brand, read the 211 `foundation` entries first** — `--primary`, `--background`,
+4. `tokens.json` — 2183 design tokens, each tagged with its `tier`. **If you were handed a
+   brand, read the 210 `foundation` entries first** — `--primary`, `--background`,
    `--radius`, `--font-size-base` are the handful everything else derives from. The
-   1865 `component` entries are per-part knobs; reach for one only when a role is
+   1861 `component` entries are per-part knobs; reach for one only when a role is
    right everywhere except one component.
 5. `anti-ai-tells.json` — 26 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.
 
-**Do not fetch `components.json`.** It is 1.3 MB, and most URL fetchers truncate a
+**Do not fetch `components.json`.** It is 1.2 MB, and most URL fetchers truncate a
 response that size and return the head without telling you. You get the first few entries, believe
 you read the catalog, and answer the rest from memory — which is the failure this file exists to
 prevent. The per-component files say the same thing without the cliff.
@@ -143,9 +143,9 @@ has stopped following the brand.
 
 | `tier` | count | what it is | set it? |
 |---|---|---|---|
-| `foundation` | 211 | the seeds — `--primary`, `--background`, `--foreground`, `--radius`, `--font-size-base`, `--shadow-color`. Everything below is derived from these | **yes — this is the main road.** Handed a brand colour, this is where it goes: `:root { --primary: <H> <S>% <L>%; }` (HSL components, no `hsl()` wrapper) |
+| `foundation` | 210 | the seeds — `--primary`, `--background`, `--foreground`, `--radius`, `--font-size-base`, `--shadow-color`. Everything below is derived from these | **yes — this is the main road.** Handed a brand colour, this is where it goes: `:root { --primary: <H> <S>% <L>%; }` (HSL components, no `hsl()` wrapper) |
 | `semantic` | 112 | 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` | 1865 | 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` | 1861 | 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/Accordion.json

@@ -39,13 +39,13 @@
     3,
     6
   ],
-  "storyPath": "data-display/Accordion.stories.tsx",
+  "storyPath": "data-display/accordion.tsx",
   "subParts": [
     "AccordionContent",
     "AccordionItem",
     "AccordionTrigger"
   ],
-  "tagline": "Radix accordion — vertically stacked, collapsible sections. Compose Accordion > AccordionItem > AccordionTrigger + AccordionContent.",
+  "tagline": "React Aria disclosure group — vertically stacked, collapsible sections. Compose Accordion > AccordionItem > AccordionTrigger + AccordionContent.",
   "usage": [
     "DO compose the full set: <Accordion type=\"single\" collapsible><AccordionItem value=\"a\"><AccordionTrigger/><AccordionContent/></AccordionItem></Accordion>.",
     "DO give each AccordionItem a unique `value`.",

package/agent/components/AccountChip.json

@@ -49,7 +49,7 @@
   "rules": [
     40
   ],
-  "storyPath": "layout/AccountChip.stories.tsx",
+  "storyPath": "layout/account-chip.tsx",
   "tagline": "Signed-in user for a PageContainer extra slot, Topbar or footer row: avatar, name and one ghost action at the control tier height — never a hand-rolled rounded-full border div.",
   "usage": [
     "Put it in PageContainer `extra` beside Buttons and a Select width=\"auto\": every control in that row shares --control-height.",

package/agent/components/Actions.json

@@ -56,7 +56,7 @@
     44,
     45
   ],
-  "storyPath": "general/Actions.stories.tsx",
+  "storyPath": "general/actions.tsx",
   "subParts": [
     "ActionsItem",
     "ActionsCopy",

package/agent/components/Activity.json

@@ -51,10 +51,10 @@
     "Button (loading) — THIS action is in flight, on a control. Not an ambient state.",
     "Progress — a DETERMINATE amount is done. Activity's `bar` variant is the indeterminate case, where no percentage exists.",
     "DataState — antd `Spin`'s wrapper form (`<Spin spinning>{children}</Spin>`) over a query: skeleton → prerequisite → empty → error, with cause-aware retry. This is what to reach for when the REGION is loading.",
-    "antd `Spin` — no such component here, by a ruling recorded twice in docs/roadmap/parity-backlog.md and docs/roadmap/parity-audit-data-display-feedback.md §2.20. Its four jobs are Activity / Skeleton / DataState / Button `loading`. Its `delay` (flicker guard) is tracked separately against Button as `loadingDelay`; its `fullscreen` is a Dialog/app-shell concern, not an indicator one."
+    "antd `Spin` — no such component here, by a standing parity ruling (antd Spin is not ported). Its four jobs are Activity / Skeleton / DataState / Button `loading`. Its `delay` (flicker guard) is tracked separately against Button as `loadingDelay`; its `fullscreen` is a Dialog/app-shell concern, not an indicator one."
   ],
   "rules": [],
-  "storyPath": "general/Activity.stories.tsx",
+  "storyPath": "general/activity.tsx",
   "tagline": "The official AMBIENT-motion primitive and the standalone indeterminate indicator (antd `Spin`) — a continuous, unbounded 'something is happening right now, elsewhere' mark (someone typing, a sync running, a response streaming, a recording live). Loading a REGION is Skeleton; an in-flight ACTION is Button loading; a known percentage is Progress.",
   "usage": [
     "DO read this first if you came looking for a Spin/Spinner (gh#830). antd's `Spin` is ONE component with a `spinning` boolean covering four different situations; here those are four components, because the accessible semantics of each are genuinely different: (1) something is happening ELSEWHERE, indefinitely → Activity, no live region by default; (2) the CONTENT of this region is loading → Skeleton (aria-busy + aria-live, shaped placeholders) or DataState (the whole skeleton → prerequisite → empty → error lifecycle); (3) THIS action is in flight → Button `loading` (aria-busy + activation blocked on the control itself); (4) a percentage is known → Progress. Picking by shape ('I want the round one') is how a persistent indicator ends up telling a screen reader the page is busy forever.",

package/agent/components/Affix.json

@@ -58,7 +58,7 @@
     44,
     45
   ],
-  "storyPath": "layout/Affix.stories.tsx",
+  "storyPath": "layout/affix.tsx",
   "tagline": "Ant Design `Affix` (6.6.5): pin an element to its scrollport once the page scrolls past it, and REPORT that it is pinned. `position: sticky` pins and then says nothing, so a sticky header cannot shrink, swap its logo or raise its shadow; this one exposes the boolean as `data-affixed` for CSS and `onChange` for JavaScript, and holds the flow open with a MEASURED placeholder so the page does not jump by the bar's height at the moment it pins.",
   "usage": [
     "DO use it whenever the pinned state has to be VISIBLE — a header that condenses, a toolbar that gains a shadow over the rows sliding under it, a filter rail that swaps to a compact form. That state is the entire reason this exists; if you need none of it, plain `position: sticky` is lighter and correct.",

package/agent/components/Alert.json

@@ -1,4 +1,8 @@
 {
+  "absorbed": [
+    "Banner",
+    "Callout"
+  ],
   "example": "import { Alert, AlertTitle, AlertDescription } from \"@godxjp/ui/feedback\";\n\n<Alert tone=\"warning\">\n  <AlertTitle>3 件の打刻漏れがあります</AlertTitle>\n  <AlertDescription>本日中に確認してください。</AlertDescription>\n</Alert>",
   "group": "feedback",
   "importPath": "@godxjp/ui/feedback",
@@ -6,9 +10,15 @@
   "props": [
     {
       "defaultValue": "\"default\"",
-      "description": "STRUCTURAL axis, orthogonal to `tone` (which owns colour + icon): \"default\" is the inline rounded card; \"banner\" is the full-bleed attention strip — prefer the `Banner` export, which fixes this axis.",
+      "description": "STRUCTURAL axis, orthogonal to `tone` (which owns colour + icon): \"default\" is the inline rounded card; \"banner\" is the full-bleed page/shell attention strip (square corners, page-gutter inset, actions wrap below 640px); \"callout\" is the aside INSIDE a document body — `role=\"note\"`, never a live region, `kind` picks the admonition. v32 folded the former `Banner` and `Callout` exports into these values.",
       "name": "variant",
-      "type": "\"default\" | \"banner\""
+      "type": "\"default\" | \"banner\" | \"callout\""
+    },
+    {
+      "defaultValue": "\"note\"",
+      "description": "`variant=\"callout\"` only. GitHub/Obsidian admonition preset; resolves the tone AND the leading glyph. A preset, not a second colour axis — `tone` and `icon` still override per instance. Ignored by the other variants.",
+      "name": "kind",
+      "type": "\"note\" | \"tip\" | \"important\" | \"warning\" | \"caution\""
     },
     {
       "description": "Renders an × dismiss button when provided.",
@@ -21,19 +31,21 @@
       "type": "LucideIcon | false"
     },
     {
-      "description": "Semantic tone driving the colour + leading icon.",
+      "description": "Semantic tone driving the colour + leading icon AND live-region politeness (\"destructive\"/\"warning\" announce assertively via role=\"alert\"; every other tone politely via role=\"status\"). Under `variant=\"callout\"` tone drives colour only — a callout is never a live region.",
       "name": "tone",
-      "type": "\"success\" | \"warning\" | \"destructive\" | \"info\" | \"neutral\""
+      "type": "\"default\" | \"success\" | \"warning\" | \"destructive\" | \"info\" | \"muted\" | \"neutral\""
     }
   ],
   "related": [
     "Toaster — use for transient, auto-dismissing feedback ('Record saved', 'Deleted'). Alert is for persistent page-scoped banners; Toaster is for fire-and-forget notifications triggered by toast() from sonner.",
     "AlertMutationFeedback — use when you want inline success/error feedback tightly coupled to a form mutation's state (renders inline below the submit button). Alert requires you to manage show/hide state yourself.",
     "DataState — use for full query lifecycle (loading skeleton + empty state + error) inside a data-fetching section. Alert.QueryError is the error sub-component DataState uses internally; prefer DataState when you also need the loading/empty states.",
+    "ErrorSurface — a whole-page semantic exception state (403/404/5xx) that REPLACES the page. An `Alert` (any variant) annotates a page that still works.",
+    "Prose — the typographic column a `variant=\"callout\"` normally sits inside; the callout's block margin is tuned to that rhythm.",
     "EmptyState — use for the zero-data case inside a list or table section, not for errors or warnings. Alert is for status messages; EmptyState is for the absence of data."
   ],
   "rules": [],
-  "storyPath": "feedback/Alert.stories.tsx",
+  "storyPath": "feedback/alert.tsx",
   "subParts": [
     "AlertActions",
     "AlertBase",
@@ -43,7 +55,7 @@
     "AlertQueryError",
     "AlertTitle"
   ],
-  "tagline": "Inline alert banner with variant-aware icon + optional dismiss. Parts: Alert/AlertTitle/AlertDescription/AlertActions/AlertQueryError.",
+  "tagline": "Status message with a tone icon and optional dismiss, in three presentations: inline card, full-bleed page/shell strip (`variant=\"banner\"`), or a non-live aside inside a document (`variant=\"callout\"`, GitHub `> [!NOTE]`). Parts: Alert.Title/Description/Content/Actions/QueryError.",
   "usage": [
     "ANATOMY (positions are fixed — never re-lay-them-out): Alert is ONE horizontal row — a SINGLE leading tone icon at the inline-start (top-aligned to the first text line, auto-selected by `tone`, never two icons), then the text body (Title/Description), then `<Alert.Actions>` in a trailing-RIGHT column (≥sm), and the dismiss × pinned to the TOP-RIGHT corner (rendered by `onDismiss`). DON'T stack these vertically, DON'T make the action a full-width bar under the text, DON'T center the × at the bottom, DON'T add a second icon — that hand-rolled vertical banner is the #1 Alert mistake.",
     "DO compose text as `<Alert.Title>` + `<Alert.Description>` — they stack vertically inside the body (the Example below is canonical). When you add `<Alert.Actions>`, the body becomes a two-column grid (text | actions) at ≥sm; group multi-part text in `<Alert.Content>` so it occupies the text column as one block: `<Alert tone=\"destructive\"><Alert.Content><Alert.Title>Error</Alert.Title><Alert.Description>{msg}</Alert.Description></Alert.Content><Alert.Actions><Button …/></Alert.Actions></Alert>`.",
@@ -52,6 +64,8 @@
     "DON'T pass raw action elements directly as top-level children of `<Alert>` without wrapping them in `<Alert.Actions>` — the layout slot only activates correctly via the `data-slot=\"alert-actions\"` wrapper.",
     "DON'T hand-roll a dismiss ✕ button — pass `onDismiss` to `<Alert>` and the component renders its own accessible dismiss button with `aria-label=\"Dismiss\"`. The `onDismiss` handler may return a Promise.",
     "DON'T suppress the icon with `icon={false}` unless there is a deliberate design reason; the icon is the primary a11y cue for sighted users since the root already carries `role=\"alert\"` for screen readers.",
+    "BANNER (`variant=\"banner\"`): place it FULL-BLEED at the top of the surface it warns about — directly under the Topbar inside AppShell's children for shell-wide attention (past-due subscription, active support session), or as the first child of a page. Its inline inset defaults to the page gutter (--space-page-active-x) and its geometry is owned by the `--banner-*` tokens; never fake a strip with `className` overrides. At most ONE per surface.",
+    "CALLOUT (`variant=\"callout\"`): for content that is PART of the document being read — a docs admonition, a CMS note, a policy caveat. It renders `role=\"note\"` and never announces. Map Markdown `[!NOTE]`/`[!TIP]`/`[!IMPORTANT]`/`[!WARNING]`/`[!CAUTION]` straight onto `kind`. DON'T pass `onDismiss` (prose is not dismissed) and DON'T use a callout for something that just HAPPENED — that is the default or banner variant, which announce.",
     "DO NOT use `Alert` for transient ephemeral feedback (e.g. 'saved successfully'). Use `toast()` from sonner + `<Toaster>` for that. `Alert` is for persistent, page-scoped banners that stay visible until the user acts or dismisses."
   ],
   "useCases": [
@@ -60,6 +74,8 @@
     "Success confirmation banner rendered after a bulk-import job completes and the user returns to the list page — `tone=\"success\"` with `Alert.Description` showing the record count imported.",
     "TanStack Query data-fetch failure inside a Card body — use `<Alert.QueryError error={error} onRetry={refetch} />` instead of writing a custom error state.",
     "Informational notice at the top of a settings page when a feature is in beta or requires a plan upgrade — `tone=\"info\"` with a short description and an `Alert.Actions` 'Learn more' link.",
+    "Past-due subscription strip across the console shell — `variant=\"banner\" tone=\"warning\"` with an `Alert.Actions` \"お支払い方法を更新\" Button, rendered above the page slot until billing recovers.",
+    "Docs/handbook admonition inside a prose column — `variant=\"callout\" kind=\"tip\"`; a destructive-consequence note beside a runbook step is `kind=\"caution\"`, still silent on load.",
     "Dismissible billing-overdue notice at the top of the dashboard — `tone=\"destructive\"` with `onDismiss` that sets a session flag so it does not reappear until the next login."
   ]
 }

package/agent/components/AlertDialog.json

@@ -80,8 +80,9 @@
     23,
     3
   ],
-  "storyPath": "feedback/AlertDialog.stories.tsx",
+  "storyPath": "feedback/alert-dialog.tsx",
   "subParts": [
+    "AlertDialogRoot",
     "AlertDialogAction",
     "AlertDialogCancel",
     "AlertDialogContent",
@@ -95,6 +96,12 @@
   ],
   "tagline": "Canonical modal confirmation flow (destructive / high-stakes decisions). Preserves confirm semantics with `role=\"alertdialog\"` and built-in cancel/confirm handling.",
   "usage": [
+    "COMPOUND (AlertDialogRoot): Reach for the flat `AlertDialog` preset FIRST — it already covers title/description/confirm/cancel, the typed `challenge`, `stepUp` re-auth and `pending`. Use `AlertDialogRoot` only when the confirm body needs content the preset does not model (an impact summary, a diff, a nested list).",
+    "COMPOUND (AlertDialogRoot): DO name it `AlertDialogRoot`, not `AlertDialog` — the `AlertDialog` export is the flat preset and takes a completely different (non-compound) prop API.",
+    "COMPOUND (AlertDialogRoot): DO include `AlertDialogHeader` with `AlertDialogTitle` inside every `AlertDialogContent` — `role=alertdialog` needs an accessible title; omitting it warns in the console and breaks screen-reader announcement. `AlertDialogHeader` also takes the prop-driven `title`/`subtitle`/`extra`/`tone` form, where `subtitle` renders the `AlertDialogDescription`.",
+    "COMPOUND (AlertDialogRoot): DO portal explicitly: `AlertDialogContent` does NOT self-portal (unlike `DialogContent`). Wrap it in `AlertDialogPortal` with a sibling `AlertDialogOverlay`, or the scrim and stacking context are wrong.",
+    "COMPOUND (AlertDialogRoot): DO use `AlertDialogAction` / `AlertDialogCancel` for the footer buttons — they carry the button styling AND the close semantics. Do not wrap them in `asChild` `<Button variant=…>`: the Root's button classes and the child's would both land on the element and the variant would not win.",
+    "COMPOUND (AlertDialogRoot): DO NOT import `@radix-ui/react-alert-dialog` directly in a consumer app. Everything the compound needs is exported from `@godxjp/ui/feedback`.",
     "Use `AlertDialog` for destructive/irreversible actions (delete, void, unpublish, archive, etc.).",
     "Use `confirmPhrase`/`challenge` for high-friction operations (e.g. typing an org slug) to reduce accidental confirmation — both force the destructive shape: the destructive confirm button plus a leading status glyph beside the title, which is Ant Design `Modal.confirm` parity. The header surface stays UNTINTED — antd signals danger with the glyph and never tints a modal header (its soft `colorErrorBg` belongs to Alert/Tag/message). To tint the band anyway, set `DialogHeader tone` yourself; it is a separate seven-value axis the preset no longer imposes.",
     "Pass `stepUp` for a passkey/2FA re-auth gate that must resolve truthy before `onConfirm` runs (refunds, org deletion).",

package/agent/components/Anchor.json

@@ -1,8 +1,8 @@
 {
   "docPath": "navigation/anchor.tsx",
-  "example": "import { Anchor } from \"@godxjp/ui/navigation\";\n\n<Anchor\n  offsetBlockStart={64}\n  targetOffsetBlockStart={88}\n  label=\"On this page\"\n  items={[\n    { key: \"overview\", href: \"#overview\", title: \"Overview\" },\n    {\n      key: \"pricing\",\n      href: \"#pricing\",\n      title: \"Pricing\",\n      children: [{ key: \"tiers\", href: \"#tiers\", title: \"Tiers\" }],\n    },\n    { key: \"faq\", href: \"#faq\", title: \"FAQ\" },\n  ]}\n  onValueChange={(href) => console.log(\"reading\", href)}\n/>",
+  "example": "import { Anchor } from \"@godxjp/ui/lab\";\n\n<Anchor\n  offsetBlockStart={64}\n  targetOffsetBlockStart={88}\n  label=\"On this page\"\n  items={[\n    { key: \"overview\", href: \"#overview\", title: \"Overview\" },\n    {\n      key: \"pricing\",\n      href: \"#pricing\",\n      title: \"Pricing\",\n      children: [{ key: \"tiers\", href: \"#tiers\", title: \"Tiers\" }],\n    },\n    { key: \"faq\", href: \"#faq\", title: \"FAQ\" },\n  ]}\n  onValueChange={(href) => console.log(\"reading\", href)}\n/>",
   "group": "navigation",
-  "importPath": "@godxjp/ui/navigation",
+  "importPath": "@godxjp/ui/lab",
   "name": "Anchor",
   "props": [
     {
@@ -104,8 +104,9 @@
     44,
     45
   ],
-  "storyPath": "navigation/Anchor.stories.tsx",
+  "storyPath": "navigation/anchor.tsx",
   "tagline": "Ant Design `Anchor` (6.6.5): the in-page section navigation, and the only thing in this library that COMPUTES which section is current. `NavList activeId` takes that answer as a prop. Resolves by antd's rule — the last section whose edge has crossed a single decision line — which is a pure function of scroll position and therefore cannot flicker, suppresses itself during the programmatic scroll a click starts, reads the landing hash before any scroll event, and jumps rather than tweens under `prefers-reduced-motion`.",
+  "tier": "lab",
   "usage": [
     "DO give every target a real `id` and point `href` at it as `#id`. The links are real anchors: middle-clickable, deep-linkable, and correct before JavaScript boots.",
     "DO set `targetOffsetBlockStart` to the height of whatever is pinned above the content, or a clicked section lands under the header. Leave `offsetBlockStart` alone unless the DECISION LINE also needs moving; it follows `targetOffsetBlockStart` by default.",