@godxjp/ui-mcp 17.0.0 → 18.0.0

package/dist/index.js

@@ -40,6 +40,11 @@ var COMPONENTS = [
         type: "BreadcrumbItemProp[]",
         description: "Ordered trail of { label, to? } segments above the title."
       },
+      {
+        name: "breadcrumbAriaLabel",
+        type: "string",
+        description: `Override the breadcrumb nav landmark's accessible name (defaults to a localized "Breadcrumb"). Required when more than one PageContainer (each with its own breadcrumb) renders on the same page/view \u2014 two nav landmarks sharing one name/role fail landmark-unique.`
+      },
       {
         name: "variant",
         type: '"default" | "narrow" | "flush" | "ghost"',
@@ -292,10 +297,31 @@ import { StatCard } from "@godxjp/ui/data-display";
         name: "breadcrumb",
         type: "BreadcrumbProp",
         description: "Breadcrumb trail rendered in the topbar header for back-navigation."
+      },
+      {
+        name: "mobileNav",
+        type: "ReactNode",
+        description: "Navigation shown in the AppShell-owned mobile drawer below `lg` (where the docked sidebar is hidden). Defaults to the `sidebar` node; pass a tailored menu, or null to opt out."
+      },
+      {
+        name: "mobileNavLabel",
+        type: "string",
+        description: "Accessible title for the mobile navigation drawer. Defaults to localized 'Menu'."
+      },
+      {
+        name: "mobileNavOpen",
+        type: "boolean",
+        description: "Controlled open state of the mobile drawer. Omit for AppShell-owned state."
+      },
+      {
+        name: "onMobileNavOpenChange",
+        type: "(open: boolean) => void",
+        description: "Change handler for the mobile drawer open state."
       }
     ],
     usage: [
       "DO pass a <Sidebar> node to `sidebar` (required) and page content to `children` (required) \u2014 these are the only two required props. Everything else is optional and omitting optional slots simply removes that zone from the rendered DOM.",
+      "DO rely on AppShell's OWNED mobile drawer below `lg`: it renders a hamburger trigger in the topbar and a focus-trapped Sheet (Esc + overlay close, focus returns to the trigger). `mobileNav` defaults to the `sidebar` node, so the same nav is reachable on mobile with no wiring \u2014 never hide the sidebar without providing this. Pass a tailored `mobileNav`, or `mobileNav={null}` only when navigation lives elsewhere (e.g. a bottom bar).",
       "DO use the auto-built topbar rail (logo / topbarLeft / topbarRight) for simple shells. Pass a fully configured <Topbar> to the `topbar` prop only when you need live handlers (entity switcher via productMenu, search, notifications, user avatar) \u2014 when `topbar` is provided, logo/topbarLeft/topbarRight are ignored entirely.",
       "DO wire a single `sidebarCollapsed` boolean between AppShell's `sidebarCollapsed` prop and Sidebar's `collapsed` prop \u2014 AppShell sets `data-collapsed='true'` on the root div (which CSS reads for width transitions) but does NOT own the collapsed state itself; lift the state and pass it down to both.",
       "DO place breadcrumb content in AppShell's `breadcrumb` prop (renders in the `app-breadcrumb` div inside `<main>` ABOVE children) \u2014 do NOT hand-roll a breadcrumb bar as the first child of children, and do NOT put breadcrumbs inside <Sidebar>.",
@@ -452,6 +478,11 @@ export function LoginPage() {
         name: "footer",
         type: "ReactNode",
         description: "Slot pinned to the bottom of the sidebar below the scrollable nav area. Commonly used for user identity, online status, or version info."
+      },
+      {
+        name: "aria-label",
+        type: "string",
+        description: `Override the nav landmark's accessible name (defaults to a localized "Main navigation"). Required when more than one Sidebar renders at once (e.g. a docked sidebar + its mobile-drawer twin) \u2014 two nav landmarks sharing one name/role fail landmark-unique.`
       }
     ],
     usage: [
@@ -459,6 +490,8 @@ export function LoginPage() {
       "DO: Add content: SidebarItemProp[] to any SidebarItemProp to create a collapsible submenu group. The parent item's icon is required even for groups. The group auto-opens and highlights when activeId matches any descendant.",
       "DO: Mirror the collapsed boolean between AppShell's sidebarCollapsed prop and Sidebar's collapsed prop \u2014 they must stay in sync so the shell layout grid adjusts correctly.",
       "DO: Use the footer prop for user info or status \u2014 it is pinned below the scroll area and does not scroll away.",
+      "DO: Render a leaf as a real link with `item.href` (a real <a>, so right-click / open-in-new-tab work) or, for a framework router <Link>, return that single element from `renderItem` \u2014 the Sidebar merges the row onto it via Slot so the link IS the row and the ONLY interactive element (no nested <button>). Never put a <button>/<a> inside a default row.",
+      "DO: Rely on route-synchronized group expansion \u2014 a group OPENS automatically whenever `activeId` moves to one of its children (e.g. after a deep-link navigation), revealing the newly-active child; users can still collapse/expand manually.",
       "DON'T: Manage collapse state inside the Sidebar \u2014 it is stateless. Hoist the boolean to your shell/page state and pass it down via both AppShell.sidebarCollapsed and Sidebar.collapsed.",
       "DON'T: Nest children more than one level deep \u2014 only top-level items can have children; grandchild items are not rendered."
     ],
@@ -698,6 +731,11 @@ import { PanelLeftClose, Search } from "lucide-react";
         type: "BreadcrumbItemProp[]",
         required: true,
         description: "Array of { label, to? } \u2014 omit `to` on the last (current) segment."
+      },
+      {
+        name: "aria-label",
+        type: "string",
+        description: `Override the nav landmark's accessible name (defaults to a localized "Breadcrumb"). Required when more than one Breadcrumb renders on the same page/view \u2014 two nav landmarks sharing one name/role fail landmark-unique.`
       }
     ],
     usage: [
@@ -1061,7 +1099,7 @@ import { Card, CardContent } from "@godxjp/ui/data-display";
         name: "columns",
         type: "ColumnDef<T>[]",
         required: true,
-        description: "Lean column definitions (adapted to TanStack internally). Each column: { key: string; header: ReactNode; render?: (row: T) => ReactNode; sortable?: boolean; width?: string; align?: 'left'|'center'|'right'; hiddenOnMobile?: boolean; enableHiding?: boolean; pin?: 'end' }. If render is omitted, the raw value at row[key] is rendered as a string. sortable opts the column into the sort cycle (client-side by default, or server-side via sort+onSortChange). enableHiding (default true) lists the column in DataTable.ViewOptions; set false to keep a key/actions column always visible. pin:'end' sticks the column (typically row actions) to the inline-end edge on horizontal scroll with a separating shadow \u2014 pin at most one column."
+        description: "Lean column definitions (adapted to TanStack internally). Each column: { key: string; header: ReactNode; ariaLabel?: string; render?: (row: T) => ReactNode; sortable?: boolean; width?: string; align?: 'left'|'center'|'right'; hiddenOnMobile?: boolean; enableHiding?: boolean; pin?: 'end' }. If render is omitted, the raw value at row[key] is rendered as a string. sortable opts the column into the sort cycle (client-side by default, or server-side via sort+onSortChange). enableHiding (default true) lists the column in DataTable.ViewOptions; set false to keep a key/actions column always visible. pin:'end' sticks the column (typically row actions) to the inline-end edge on horizontal scroll with a separating shadow \u2014 pin at most one column. ariaLabel gives a VISUALLY-EMPTY header (header='' \u2014 an action or selection column) a screen-reader name (e.g. 'Actions'/'Select'): it renders as an sr-only label inside the <th> so the column is never nameless (axe: empty-table-header). DataTable dev-warns when a column has an empty header and no ariaLabel."
       },
       {
         name: "getRowId",
@@ -1179,6 +1217,8 @@ import { Card, CardContent } from "@godxjp/ui/data-display";
       "DO use DataTable.Toolbar as the immediate child that wraps search/filter controls on the left and DataTable.DensityToggle/action buttons on the right. DataTable.BulkActions inside the toolbar auto-hides when selection count is 0; it accepts either plain ReactNode children (built-in 'N selected' status bar) or a (count)=>node render-prop (you own the whole bar).",
       "DO reach for the grid chrome (DataTable.Search, DataTable.ViewOptions, DataTable.Pagination pageSizeOptions) when you need global search, a column 'set view' picker, or numbered pagination \u2014 these are the merged former-DataGrid features, now on the one DataTable. Drive them client-side by default; pass the matching state + manual* flag for a server query.",
       "DO use ColumnDef.render for custom cell content (Badge, Link, RowActions). For plain string/number fields render can be omitted \u2014 DataTable falls back to String(row[key]).",
+      "DO give every visually-empty column an accessible header via `ariaLabel` \u2014 a row-actions column (`header: ''`, `pin: 'end'`) sets `ariaLabel: t('actions')`, so screen readers announce the column and axe reports no `empty-table-header`. DataTable dev-warns any column that renders a `<th>` with neither visible text nor an `ariaLabel`. The selection column added by `selectable` is already named by its SelectAll checkbox \u2014 no `ariaLabel` needed there.",
+      "COLUMN SEMANTICS + KEYBOARD: a `sortable` header renders as a real <button> inside the <th> with `aria-sort` (ascending/descending/none) on the <th>; it is Tab-reachable and toggles asc \u2192 desc \u2192 cleared on Enter/Space/click. A selection column exposes a header 'select all' Checkbox (indeterminate when a subset is selected) and a per-row Checkbox, each keyboard-operable with Space. An action column is visually empty but carries an `ariaLabel`; its per-row controls (kebab menu / buttons) own their own accessible names and keyboard behavior. Row click (`onRowClick`) is suppressed when the user activates an interactive descendant.",
       "DO NOT nest DataTable.Content in a conditional \u2014 it is already guarded internally. If you need to override the table body slot, drop exactly one <DataTable.Content /> in children; DataTable auto-detects it by displayName and skips the default."
     ],
     useCases: [
@@ -1300,6 +1340,7 @@ export default function InvoiceList({
     usage: [
       'DO always wrap body content in <CardContent> \u2014 the bare <Card> div has zero inner padding; content renders flush against card edges without it. Never add className="p-4" directly on <Card> as a substitute.',
       "DO put titles/descriptions in <CardHeader>/<CardTitle>/<CardDescription>. Use <CardHeader banded> for a visually separated muted-background header band (mirrors <CardFooter separated>). Pair with <CardAction> inside a flex-row CardHeader for header-level action buttons.",
+      'DO set <CardTitle level={n}> to keep a valid document outline (h1 \u2192 h2 \u2192 h3, no skipped levels): CardTitle renders <h3> by default, so a section card directly under a page <h1> needs level={2}. Pick the level by OUTLINE position, NEVER for visual size \u2014 the title size is fixed by tokens and does not change with level. When the card title is a styled label rather than a section heading, use <CardTitle as="p"> so it is not announced as a heading.',
       "DO use <CardContent flush> for edge-to-edge children such as DataTable, Table, or a Tabs list \u2014 this removes horizontal padding. Combine with <CardContent tight> when there is no visual gap needed after the header, and <CardContent solo> when there is no CardHeader above (top padding matches the card shell).",
       "DO use <CardFooter separated> to render a top-bordered action band (Save/Cancel buttons, table summary row). Use <CardFooter flush> for a full-bleed footer bar.",
       "DO use <CardCover> as the first child for full-bleed cover media \u2014 the header below it uses card-section top spacing, not the card shell.",
@@ -1688,17 +1729,31 @@ import { Smartphone } from "lucide-react";
         type: '"muted" | "success" | "warning" | "destructive" | "info"',
         defaultValue: '"muted"',
         description: "Medallion colour intent (a subset of the shared tone vocabulary; `destructive` is the DS name for a danger state). Tints the icon foreground + fill from the matching role token \u2014 set `success` for a confirmation zero-state (e.g. device approved) instead of hand-rolling a `.ui-success-state` class."
+      },
+      {
+        name: "titleLevel",
+        type: "1 | 2 | 3 | 4",
+        defaultValue: "3",
+        description: "Semantic heading level of the title. Pick it to keep the page outline valid (h1 \u2192 h2 \u2192 h3, no skipped levels), NEVER for visual size \u2014 the title size is fixed regardless of level. A page/onboarding empty state directly under the page h1 uses titleLevel={2}; one nested in an already-h2 section keeps the default 3."
+      },
+      {
+        name: "titleAs",
+        type: '"h1" | "h2" | "h3" | "h4" | "p" | "div"',
+        description: "Render the title as a non-heading element (p/div) instead of a heading \u2014 for a compact/section empty state inside a section that already owns its heading, so the message is not announced as a heading and cannot skip an outline level. Overrides titleLevel."
       }
     ],
     usage: [
-      "DO always pass `title` \u2014 it is the only required prop and renders an `<h3>`; omitting it causes a blank silent render with no visible error.",
+      "DO always pass `title` \u2014 it is the only required prop and renders a heading (`<h3>` by default); omitting it causes a blank silent render with no visible error.",
+      'DO set `titleLevel` to match the page outline (page h1 \u2192 section h2 \u2192 nested h3) so the empty state does not trigger a heading-order violation. Choose the level for OUTLINE position, never for visual size \u2014 the size never changes with the level. When the empty state sits in a section that already has its own heading, use `titleAs="p"` so the message is not a heading at all.',
       'DO use `tone="success"` (or warning/destructive/info) for a semantic confirmation/alert zero-state \u2014 it recolours the icon medallion from the role token; do NOT hand-roll a `.ui-success-state` class that scopes `--empty-state-icon-*`.',
       "DO use the `icon` prop (a Lucide icon component, not a JSX element) to give visual context \u2014 e.g. `icon={InboxIcon}` for empty inboxes, `icon={SearchIcon}` after a failed search. Pass the component reference, not `<InboxIcon />`.",
       "DO use `action` (a `ReactNode`, typically a `<Button>`) for actionable zero-states \u2014 e.g. 'Create first invoice' \u2014 so users have a clear next step instead of a dead end.",
       "DO NOT hand-roll a `data.length === 0 ? <EmptyState /> : <DataTable />` conditional \u2014 `DataTable` already embeds an `EmptyState` in its body when `data` is empty. Use the `empty=` prop on `DataTable` to customise it, not a wrapper conditional.",
       "DO NOT use EmptyState inside a `DataState` or `InfiniteQueryState` for the loading or error states \u2014 those widgets handle skeleton/error themselves; pass `EmptyState` only to their `empty=` prop for the zero-items case.",
       "DO NOT add padding directly on `EmptyState` via `className` when placing it inside a `Card` \u2014 wrap it in `<CardContent>` first; EmptyState is a self-contained block with its own internal spacing via `ui-empty-state` styles.",
-      "DO omit optional secondary sections when absence has no user value. Otherwise use variant='compact' or 'section'; reserve page for the primary page job."
+      "DO omit optional secondary sections when absence has no user value. Otherwise use variant='compact' or 'section'; reserve page for the primary page job.",
+      "DO match empty-state visual weight to the section's importance and expected content density \u2014 a low-priority 'no received invitations' block uses variant='compact' (no medallion, minimal padding), not the full page treatment that would outweigh real content.",
+      "DO NOT wrap every empty condition in its own bordered Card. A compact/section empty state sits directly in the existing CardContent / section it belongs to; a dedicated bordered Card is only for a page-level or standalone zero-state."
     ],
     useCases: [
       "Zero-row admin list pages (invoices, accounts, transactions) that are NOT backed by a `DataTable` \u2014 e.g. a card-grid or custom list layout where DataTable's built-in empty state doesn't apply.",
@@ -1926,7 +1981,9 @@ import { Smartphone } from "lucide-react";
       "DON'T: wrap DataState in your own conditional \u2014 e.g. `{query.isSuccess && <DataState \u2026>}`. DataState IS the conditional; the outer guard is redundant and breaks the retry/refetch skeleton.",
       "DON'T: use DataState for `useInfiniteQuery` results. The `query` prop type is `UseQueryResult<T>`, not `UseInfiniteQueryResult`. Use `InfiniteQueryState` (from `@godxjp/ui/query`) instead, which accepts `flatten` and renders a load-more footer.",
       "DO: classify errors by cause. Use session renewal/sign-in for 401, access guidance for 403, contextual correction for domain errors, and opt into showRetry only for transient network/5xx errors.",
-      "DO: pass prerequisite for enabled:false queries. Pending + fetchStatus idle is unstarted, not loading, and never renders a skeleton."
+      "DO: pass prerequisite for enabled:false queries. Pending + fetchStatus idle is unstarted, not loading, and never renders a skeleton.",
+      "DO: rely on the localized, cause-specific error message \u2014 the raw backend/token/stack text is never shown. For a domain-specific message (e.g. a 422 field error) pass a custom errorRenderer.",
+      "DO: expect a background refetch over existing data to keep the content on screen with a polite sr-only busy status \u2014 it does not flash the skeleton. Only the initial fetch (isPending) shows the skeleton."
     ],
     useCases: [
       "A detail page that loads a single invoice/journal entry via `useQuery` \u2014 DataState renders the skeleton row while fetching, an error alert with retry if the API fails, and the `<InvoiceCard>` only when data is confirmed non-null.",
@@ -1947,12 +2004,7 @@ import { Smartphone } from "lucide-react";
   {(d) => <MemberTable items={d.items} />}
 </DataState>`,
     storyPath: "query/DataState.stories.tsx",
-    rules: [
-      "Errors are classified by cause (via classifyQueryError). Retry is offered ONLY for transient/network/5xx; a 401/expired-token routes to session renewal through onAuthError; 403/404/422 present a cause-aware message with no blind retry.",
-      "The user-facing detail is a localized, cause-specific message \u2014 the raw backend/token/stack text is never shown. For a domain-specific message (e.g. a 422 field error) pass a custom errorRenderer.",
-      "A disabled/unstarted query (enabled:false \u2192 isPending with fetchStatus 'idle') renders the prerequisite slot, never the skeleton. Always pass prerequisite for tenant/org-gated queries.",
-      "A background refetch over existing data keeps the content on screen with a polite sr-only busy status \u2014 it does not flash the skeleton. Only the initial fetch (isPending) shows the skeleton."
-    ]
+    rules: []
   },
   {
     name: "InfiniteQueryState",
@@ -2087,7 +2139,7 @@ import { Smartphone } from "lucide-react";
   {
     name: "FormField",
     group: "data-entry",
-    tagline: "Wraps a control with label, helper, and error; injects aria-describedby/aria-invalid onto the child. Reads the parent Form's layout (vertical/horizontal) \u2014 overridable per field.",
+    tagline: "Wraps a control with label, helper, and error; injects the accessible name (aria-labelledby), description (aria-describedby) and validation (aria-errormessage/aria-invalid/aria-required) contract onto the child, which forwards it to its real semantic focus target. Reads the parent Form's layout (vertical/horizontal) \u2014 overridable per field.",
     props: [
       {
         name: "id",
@@ -2147,7 +2199,10 @@ import { Smartphone } from "lucide-react";
       "DO use the `error` prop (not a hand-rolled `<p>`) for validation messages \u2014 it renders with `role='alert'` and `text-destructive` styling and overrides `helper` automatically. Never render an error paragraph alongside FormField.",
       "DO use `labelAddon` (a ReactNode rendered inline after the label text) for supplementary controls such as a tooltip trigger or a 'copy' icon button \u2014 never insert such controls as siblings outside FormField, which breaks layout.",
       "DON'T wrap `Switch` in FormField \u2014 use `Field` instead, which already handles the label, hidden `<input name>` for HTML form submission, error, and helper internally.",
-      "DON'T use FormField for checkbox-beside-label or radio-beside-label patterns \u2014 use `Field` (single checkbox/radio with description) or `CheckboxGroup` / `RadioGroup` (multiple options), which have their own integrated labelling."
+      "DON'T use FormField for checkbox-beside-label or radio-beside-label patterns \u2014 use `Field` (single checkbox/radio with description) or `CheckboxGroup` / `RadioGroup` (multiple options), which have their own integrated labelling.",
+      "CONTRACT (which element owns each ARIA relationship): every data-entry control accepts and FORWARDS the injected props to its real semantic focus target, not a wrapper div \u2014 Input/Textarea/NumberInput \u2192 the `<input>/<textarea>`; Select/SearchSelect/Cascader/TreeSelect \u2192 the `role=combobox` trigger (with aria-expanded + aria-haspopup + aria-controls per the WAI-ARIA APG combobox pattern); DatePicker/MonthPicker/TimePicker \u2192 the typeable `role=combobox` input (aria-haspopup=dialog); ColorPicker \u2192 the `<input type=color>` swatch; SearchInput \u2192 the `role=searchbox` input. GROUP controls own the relationship on their container: RadioGroup \u2192 `role=radiogroup` (full validation incl. aria-invalid/-errormessage/-required); CheckboxGroup, DateRangePicker/MonthRangePicker (two inputs), and Transfer \u2192 `role=group` \u2014 per ARIA 1.2 a group is not a widget, so the error id is folded into aria-describedby instead of aria-invalid/-errormessage. Upload forwards the label/description onto its native `<input type=file>`; its visible dropzone/button keeps its own action label. This forwarding is implemented once in `src/lib/field-a11y.ts` (`pickFieldA11y` / `pickGroupFieldA11y` / `resolveFieldA11y`) \u2014 do not reinvent it per control.",
+      "NATIVE FORM PARTICIPATION: pass `name` to a control for HTML form submission \u2014 Input/Textarea/NumberInput/Select submit natively; SearchSelect submits via a hidden input; DatePicker/TimePicker emit ISO strings (`yyyy-MM-dd` / 24h `HH:mm`); the range pickers emit `${name}_from` / `${name}_to`. `required`/`readOnly`/`disabled` map to the underlying control. Cascader/TreeSelect/Transfer/Upload are NOT native-form-submittable \u2014 read their value via `onValueChange` and submit programmatically.",
+      "ERROR TIMING & RECOVERY: pass `error` only after a field is dirty or the form is submitted (don't show errors on pristine mount). The error node renders with `role='alert'` so it is announced live the moment it appears; clearing `error` (e.g. after the user corrects the value or a server round-trip succeeds) removes aria-invalid and restores the helper. On submit, focus the first invalid control and/or render an error summary that links to each field by `id`."
     ],
     useCases: [
       "Labelling a text `Input` or `Textarea` in an invoice-entry form, showing a red asterisk for required fields and surfacing server validation errors returned from a Laravel FormRequest.",
@@ -2520,6 +2575,52 @@ import { Smartphone } from "lucide-react";
         description: "Label for the clear row (data-driven combobox mode)."
       },
       { name: "disabled", type: "boolean", description: "Disables the entire select." },
+      {
+        name: "readOnly",
+        type: "boolean",
+        defaultValue: "false",
+        description: "Searchable mode only (showSearch/loadOptions). Value is shown (and the clear affordance hidden) but the popover cannot be opened \u2014 no new pick, no search. Mirrors the Input/NumberInput readOnly contract: stays focusable and still submits its value, unlike disabled."
+      },
+      {
+        name: "size",
+        type: '"xs" | "sm" | "md" | "lg"',
+        description: "Searchable mode only. Height tier forwarded to the SearchSelect trigger Button. For the compound API use SelectTrigger's own size prop instead (below)."
+      },
+      {
+        name: "open",
+        type: "boolean",
+        description: "Searchable mode only. Controlled popover open state (uncontrolled by default). Pair with onOpenChange."
+      },
+      {
+        name: "onOpenChange",
+        type: "(open: boolean) => void",
+        description: "Searchable mode only. Fires on every open/close attempt \u2014 including ones ignored because open is externally pinned \u2014 so a controlled consumer stays in sync."
+      },
+      {
+        name: "search",
+        type: "string",
+        description: "Searchable mode only. Controlled search-box query (uncontrolled by default). Pair with onSearchChange."
+      },
+      {
+        name: "onSearchChange",
+        type: "(query: string) => void",
+        description: "Searchable mode only. Fires on every keystroke in the search box."
+      },
+      {
+        name: "filterOption",
+        type: "(option: SearchSelectOptionProp, query: string) => boolean",
+        description: "Searchable mode only, static options (ignored with loadOptions, which owns its own server-side filtering). Overrides the default label/value substring filter. Only consulted while the query is non-empty."
+      },
+      {
+        name: "renderError",
+        type: "(params: { message: string; retry: () => void }) => React.ReactNode",
+        description: "Searchable mode only. Custom error slot, overriding the default errorMessage row. retry() reloads from the first page."
+      },
+      {
+        name: "renderLoadMore",
+        type: "(params: { hasMore: boolean; loading: boolean; loadMore: () => void }) => React.ReactNode",
+        description: "Searchable mode only. Custom 'load more' affordance appended below the list while another page is available \u2014 pairs with (does not replace) the built-in scroll-triggered pagination."
+      },
       {
         name: "name",
         type: "string",
@@ -2545,6 +2646,12 @@ import { Smartphone } from "lucide-react";
         type: '"sm" | "md"',
         defaultValue: '"md"',
         description: "Compound API only. Size variant on the SelectTrigger sub-component."
+      },
+      {
+        name: "SelectTrigger showIndicator",
+        type: "boolean",
+        defaultValue: "true",
+        description: "Compound API only. Set false to omit the built-in chevron disclosure indicator from the DOM entirely (not a CSS hide) \u2014 for specialized triggers (icon-only, etc.) that render their own affordance, so no consumer descendant CSS is needed."
       }
     ],
     usage: [
@@ -2555,7 +2662,12 @@ import { Smartphone } from "lucide-react";
       "DO treat loading / no-options / error / disabled as DISTINCT states. A data-driven Select never opens a blank popover: a static options=[] list auto-disables the trigger (opening it would show nothing), while an async loadOptions shows a loading row, then either the options, a localized empty affordance (override with emptyMessage), or an error affordance if the fetch rejects (override with errorMessage). Disable the Select when there is nothing to pick AND no async loader; keep it enabled (it opens to load/search) whenever loadOptions is set.",
       "DON'T mix the two APIs: once you pass options or loadOptions, Select is data-driven \u2014 all compound sub-parts (SelectTrigger, SelectContent, SelectItem) are rendered internally. Do not wrap them manually.",
       "DON'T use a raw <select> element. Select is the one control for all single-select use cases. The only allowed raw <select> is a hidden aria-hidden sr-only element kept as an e2e hook paired with a visible Select.",
-      "COMPOUND API sub-parts (when NOT using options/loadOptions): Select \u2192 SelectTrigger (contains SelectValue) \u2192 SelectContent \u2192 SelectItem. Optionally wrap items in SelectGroup + SelectLabel for headings, or add SelectSeparator between sections."
+      "COMPOUND API sub-parts (when NOT using options/loadOptions): Select \u2192 SelectTrigger (contains SelectValue) \u2192 SelectContent \u2192 SelectItem. Optionally wrap items in SelectGroup + SelectLabel for headings, or add SelectSeparator between sections.",
+      "DO reach for open/onOpenChange (searchable mode) to drive the popover from outside \u2014 e.g. opening it programmatically after a validation error \u2014 and search/onSearchChange to seed or read the query text. Both fall back to internal state when omitted; onOpenChange/onSearchChange still fire either way so a controlled consumer stays in sync.",
+      "DO use readOnly (searchable mode) for a value that must stay visible and submittable but not editable in this view \u2014 it differs from disabled: the control stays focusable and its value still submits. clearable is ignored while readOnly.",
+      "DO use filterOption (searchable mode, static options) when the default label/value substring match isn't right \u2014 e.g. filtering by a hidden code field. It is NOT consulted when loadOptions is set (that fetcher owns its own filtering).",
+      "DO use renderError + renderLoadMore (searchable mode) to replace the default error row with a branded retry affordance, or to pair a manual 'load more' button with (not instead of) the built-in scroll-triggered pagination.",
+      "DO set SelectTrigger showIndicator={false} (compound API) on a specialized trigger \u2014 icon-only, or one with its own affordance \u2014 instead of hiding [data-slot=select-chevron] with consumer CSS."
     ],
     useCases: [
       "Status filter on an invoice list \u2014 pass options=[{value:'draft',label:'Draft'},{value:'paid',label:'Paid'}] with onChange to drive a query param; no search needed so omit showSearch.",
@@ -3582,10 +3694,14 @@ toast.error("\u4FDD\u5B58\u306B\u5931\u6557\u3057\u307E\u3057\u305F");`,
       {
         name: "items",
         type: "{ value: string; label: React.ReactNode; content: React.ReactNode; disabled?: boolean }[]",
-        description: "Optional data-driven tab list. When provided, Tabs renders all triggers and content panels."
+        description: "Optional data-driven tab list. When provided, Tabs renders all triggers and content panels. When Tabs owns the initial selection (no `value`, and no `defaultValue` naming an existing ENABLED item), it falls back to the first item that is NOT `disabled` \u2014 never a disabled one \u2014 and selects nothing if every item is disabled (gh#175)."
       },
       { name: "value", type: "string", description: "Controlled active tab key." },
-      { name: "defaultValue", type: "string", description: "Uncontrolled initial tab key." },
+      {
+        name: "defaultValue",
+        type: "string",
+        description: "Uncontrolled initial tab key. Ignored (falls back to the first enabled item) when it names a disabled item or an unknown key."
+      },
       {
         name: "onValueChange",
         type: "(value: string) => void",
@@ -3598,7 +3714,9 @@ toast.error("\u4FDD\u5B58\u306B\u5931\u6557\u3057\u307E\u3057\u305F");`,
       "DO: use `defaultValue` (uncontrolled) for simple local state; use `value` + `onValueChange` together (controlled) when the active tab is driven by URL query params, router state, or parent state. NEVER set both simultaneously.",
       "DO use `variant` on Tabs when using `items`; when composing manually, set `variant` on `TabsList`.",
       'DO: pass `orientation="vertical"` to `<Tabs>` (not to `TabsList`) for a side-rail layout \u2014 the CSS group classes on root and triggers respond automatically, so no extra className gymnastics are needed.',
-      "DON'T: hand-roll the active-indicator underline or selected-state ring \u2014 `TabsTrigger` already applies `data-[state=active]` styles including the `after:` line element for the `line` variant. Adding your own underline breaks the design."
+      "DON'T: hand-roll the active-indicator underline or selected-state ring \u2014 `TabsTrigger` already applies `data-[state=active]` styles including the `after:` line element for the `line` variant. Adding your own underline breaks the design.",
+      "DO trust the horizontal `TabsList` to scroll its own overflow (hidden scrollbar, swipeable) instead of clipping when tab labels \u2014 especially long localized ones (Japanese, German) \u2014 don't fit a narrow container. Don't wrap it in your own `overflow-x-auto` div or truncate labels to work around clipping; that was gh#175 and is now the framework's job (#175).",
+      "DON'T assume the first item is ever auto-selected when it is `disabled` \u2014 Tabs always resolves the fallback to the first ENABLED item (or none, if all are disabled). A `disabled: true` first item is safe to author without also setting `defaultValue`."
     ],
     useCases: [
       "Detail drawers or pages that need full per-panel control \u2014 e.g. an accounting journal-entry sheet where one panel has `forceMount` to keep a live chart mounted, requiring custom `TabsContent` props that `Tabs` cannot pass.",
@@ -3656,10 +3774,33 @@ toast.error("\u4FDD\u5B58\u306B\u5931\u6557\u3057\u307E\u3057\u305F");`,
         name: "showSizeChanger",
         type: "boolean",
         description: "Show the page-size selector beside the pager."
+      },
+      {
+        name: "hideOnSinglePage",
+        type: "boolean",
+        defaultValue: "true",
+        description: "Hide the control when there is nothing to page through \u2014 zero items OR exactly one page. Set false to opt in to the bar on a single page (e.g. to keep showTotal visible); total=0 is always hidden."
+      },
+      {
+        name: "simple",
+        type: "boolean",
+        description: "Compact form for narrow contexts \u2014 Prev / n\xB7N / Next, no page-number buttons. The intentional mobile transformation (desktop never wraps)."
+      },
+      {
+        name: "disabled",
+        type: "boolean",
+        description: "Disable all navigation controls."
+      },
+      {
+        name: "aria-label",
+        type: "string",
+        description: `Override the nav landmark's accessible name (defaults to a localized "Pagination"). Required when more than one Pagination renders on the same page/view \u2014 two nav landmarks sharing one name/role fail landmark-unique.`
       }
     ],
     usage: [
       "DO always control Pagination externally: store `value` (page) and `pageSize` in React state (or URL params), and update both in the `onValueChange(page, pageSize)` callback. Pagination is fully controlled \u2014 it has no internal state and will not move unless `value` changes.",
+      "DO let Pagination hide itself for zero items and single pages (`hideOnSinglePage`, default true) \u2014 it is navigation between multiple result pages. Render it inside a table footer only in the DATA state: never during loading, empty, error, or an unmet prerequisite. Pass `hideOnSinglePage={false}` only when you still want the bar on one page to keep `showTotal` visible.",
+      "DO trust Pagination to stay ONE horizontal row on desktop (it never wraps). For genuinely narrow viewports use `simple` for the intentional compact transformation rather than letting controls wrap.",
       "DO pass `total` as the raw item count (not page count). The component computes `Math.ceil(total / pageSize)` internally; passing a pre-computed page count as `total` will over-paginate.",
       "DO use `showSizeChanger` together with `pageSizeOptions` when the user needs density control (default options are [10, 20, 50, 100]). When `showSizeChanger` is omitted the page-size Select is not rendered at all \u2014 do NOT hand-roll your own Select beside Pagination.",
       "DO use `simple` mode for compact contexts (mobile, sidebars, sheet footers) \u2014 it renders Prev / `n / total` / Next with no page-number buttons. Use the full form for primary admin list pages.",
@@ -7248,7 +7389,7 @@ export default function PasswordBlock() {
       {
         name: "appearance",
         type: '"labeled" | "icon"',
-        description: `Trigger presentation. "labeled" (default) shows the leading icon + selected value in a full-width control. "icon" is the supported icon-only topbar trigger (e.g. a globe locale switcher): it structurally drops the value text and the picker's owned width and hides the chevron, squares the box to the density-aware --control-height tap target (\u226544px on touch), and always keeps the localized aria-label so it can never ship nameless. Menu options still show localized names. Use it instead of overriding internal descendants / width classes with CSS.`
+        description: 'Trigger presentation. "labeled" (default) shows the leading icon + selected value: it hugs its content below `sm` (`w-auto max-w-full`) and takes a per-kind fixed width from `sm` up \u2014 it no longer stretches to `w-full` on narrow screens, so it fits a topbar (pass className="w-full" for a full-width form field). "icon" is the supported icon-only topbar trigger (e.g. a globe locale switcher): it structurally drops the value text and the picker\'s owned width and hides the chevron, squares the box to the density-aware --control-height tap target (\u226544px on touch), and always keeps the localized aria-label so it can never ship nameless. Menu options still show localized names (the selected value is checked in the popup). Use these instead of overriding internal descendants / width classes with CSS.'
       },
       {
         name: "className",
@@ -7833,8 +7974,8 @@ var PROP_VOCABULARY = [
     name: "GapProp",
     concept: "Shared layout gap scale.",
     values: ["xs", "sm", "md", "lg", "xl"],
-    usedBy: ["Stack", "Inline"],
-    notes: "Inline uses an Exclude<GapProp, 'xl'> subset."
+    usedBy: ["Flex"],
+    notes: 'The single shared gap scale on Flex \u2014 the one layout primitive (default direction="row"; use direction="col" for vertical rhythm; these replaced the removed Stack/Inline).'
   },
   {
     name: "TitleProp",
@@ -7893,7 +8034,7 @@ var TOKENS = [
     name: "--duration-{fast,base,slow}",
     category: "primitive",
     tier: "primitive",
-    role: "Motion durations (150 / 250 / 500ms). Read these instead of a literal `0.5s` for enter/transition timing (rule #2). dxs-kintai keeps motion short; honour `prefers-reduced-motion` at the call site."
+    role: "Motion durations (150 / 250 / 500ms). Read these instead of a literal `0.5s` for enter/transition timing (rule #2). the reference design keeps motion short; honour `prefers-reduced-motion` at the call site."
   },
   {
     name: "--ease-{standard,emphasized,decelerate,accelerate}",
@@ -8119,7 +8260,7 @@ var COMPONENT_TOKENS = [
   {
     "name": "--card-shadow",
     "value": "0 0 0 0 transparent",
-    "description": "Resting elevation \u2014 quiet by default (rule #44): cards are flat (1px border, no shadow) in the * dxs-kintai baseline. A service that wants lifted cards sets this to an elevation token once, * e.g. --card-shadow: var(--shadow-sm), and every Card picks up the shadow with no markup change."
+    "description": "Resting elevation \u2014 quiet by default (rule #44): cards are flat (1px border, no shadow) in the * reference-design baseline. A service that wants lifted cards sets this to an elevation token once, * e.g. --card-shadow: var(--shadow-sm), and every Card picks up the shadow with no markup change."
   },
   {
     "name": "--card-glow",
@@ -9118,7 +9259,7 @@ var CARDINAL_RULES = [
   {
     number: 11,
     title: "Submodule discipline",
-    body: "Two-PR workflow: (1) submodule PR \u2192 `main`, (2) umbrella PR \u2192 bump pin. Never push a pin to a SHA not on the submodule remote."
+    body: "Two-PR workflow: (1) submodule PR \u2192 `main`, (2) downstream PR \u2192 bump pin. Never push a pin to a SHA not on the submodule remote."
   },
   {
     number: 12,
@@ -9263,7 +9404,7 @@ var CARDINAL_RULES = [
   {
     number: 40,
     title: "Pages are mobile-first",
-    body: "Author and verify every page at 320\u2013390px FIRST. Spacing comes only from `Stack` / `Inline` `gap` + `ResponsiveGrid columns={2|3|4}` (which collapse to a single column on narrow screens) \u2014 never raw `p-*` / `gap-*` / `space-*` utilities for page layout. Wide tables scroll horizontally on small screens (don't force-fit them); dialogs and sheets are full-height on mobile. Touch targets \u2265 44\xD744px."
+    body: 'Author and verify every page at 320\u2013390px FIRST. 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) \u2014 never raw `p-*` / `gap-*` / `space-*` utilities for page layout. Wide tables scroll horizontally on small screens (don\'t force-fit them); dialogs and sheets are full-height on mobile. Touch targets \u2265 44\xD744px.'
   },
   {
     number: 41,
@@ -9320,48 +9461,46 @@ var PATTERNS = [
 // 0) \u2605 MOST COMMON: <Card> body has NO padding (content is flush against the edges)
 //    Cause: the bare <Card> has ZERO inner padding \u2014 it MUST contain <CardContent>.
 //    Don't hand-roll padding with className="p-4" on the Card either.
-// \u274C  <Card><Stack gap="md">\u2026fields\u2026</Stack></Card>          // flush, no padding
-// \u274C  <Card className="p-4">\u2026fields\u2026</Card>                   // hand-rolled padding
-// \u2705  <Card><CardContent><Stack gap="md">\u2026fields\u2026</Stack></CardContent></Card>
+// \u274C  <Card><Flex direction="col" gap="md">\u2026fields\u2026</Flex></Card>   // flush, no padding
+// \u274C  <Card className="p-4">\u2026fields\u2026</Card>                          // hand-rolled padding
+// \u2705  <Card><CardContent><Flex direction="col" gap="md">\u2026fields\u2026</Flex></CardContent></Card>
 //    Titles \u2192 <CardHeader><CardTitle>. Only go flush deliberately for a full-bleed table:
 // \u2705  <Card><CardContent flush><DataTable/></CardContent></Card>
 //    GENERAL RULE \u2014 compose godx-ui primitives FULLY; never hand-roll what one ships:
 //      padding \u2192 CardContent (not p-4) \xB7 controls \u2192 Input/Select/Button (not raw <input>/<select>/<button>)
-//      empty rows \u2192 DataTable's built-in empty / <EmptyState> (not a custom data.length===0 guard).
-//    If a primitive exists, USE it \u2014 don't reinvent it.
+//      vertical spacing \u2192 Flex direction="col" gap (not space-y-*) \xB7 empty rows \u2192 DataTable's built-in
+//      empty / <EmptyState> (not a custom data.length===0 guard). If a primitive exists, USE it.
 
 // 1) StatCard shows a DOUBLE border (too thick)
 //    Cause: StatCard IS already a bordered Card. Don't wrap it.
 // \u274C  <Card><CardContent><StatCard label="x" value="1" /></CardContent></Card>
 // \u2705  <ResponsiveGrid columns={4}><StatCard label="x" value="1" /></ResponsiveGrid>
 //    Need a section title? Use a heading, NOT a Card:
-// \u2705  <Stack gap="sm"><div className="text-sm font-medium">KPI</div>
-//        <ResponsiveGrid columns={4}><StatCard .../></ResponsiveGrid></Stack>
+// \u2705  <Flex direction="col" gap="sm"><div className="text-sm font-medium">KPI</div>
+//        <ResponsiveGrid columns={4}><StatCard .../></ResponsiveGrid></Flex>
 
 // 2) Badge renders grey with a \u25CB (no colour) for localized/tier labels
-//    Cause: it auto-maps only English lifecycle keys. (@godxjp/ui >= 6.1)
+//    Cause: it auto-maps only English lifecycle keys.
 // \u274C  <Badge status="\u30D7\u30EC\u30DF\u30A2\u30E0" />
 // \u2705  <Badge status="\u30D7\u30EC\u30DF\u30A2\u30E0" tone="success" icon={null} />   // tier \u2192 pill, no icon
-// \u2705  <Badge status="active">\u516C\u958B\u4E2D</Badge>                   // lifecycle \u2192 keep icon
+// \u2705  <Badge status="active">\u516C\u958B\u4E2D</Badge>                       // lifecycle \u2192 keep icon
 
 // 3) Table text collapses to one char per line, or a chip wraps
-//    Cause: pre-6.1.2. (@godxjp/ui >= 6.1.2 \u2192 cells + chips are nowrap)
-// \u2705  npm i @godxjp/ui@^6.2.0
 // \u2705  give long columns a width:  { key: "name", header: "\u6C0F\u540D", width: "w-64" }
+//    (cells + chips are pinned white-space: nowrap by the library.)
 
 // 4) Empty (icon/action) column header shows a blank grey block
-//    (@godxjp/ui >= 6.2.0 auto-hides it: [data-slot=table-head][data-empty] \u2192 transparent)
-// \u2705  npm i @godxjp/ui@^6.2.0   // header: "" now renders a transparent cell
+// \u2705  header: "" renders a transparent cell \u2014 leave it empty, don't inject a space.
 
 // 5) DataTable columns are crushed / squeezed
 //    Cause: the table is nested in a narrow grid column.
 // \u274C  <ResponsiveGrid columns={3}><div className="lg:col-span-2"><Card><DataTable/></Card></div></ResponsiveGrid>
 // \u2705  Table gets its OWN full-width row: <Card><CardContent flush><DataTable/></CardContent></Card>
 
-// 6) FilterBar has no padding (sticks to the edge)
+// 6) Toolbar (filter bar) has no padding (sticks to the edge)
 //    Cause: it's inside CardContent flush (flush strips padding \u2014 that's for tables).
-// \u274C  <Card><CardContent flush><FilterBar/><DataTable/></CardContent></Card>
-// \u2705  <FilterBar/>  then  <Card><CardContent flush><DataTable/></CardContent></Card>
+// \u274C  <Card><CardContent flush><Toolbar/><DataTable/></CardContent></Card>
+// \u2705  <Toolbar/>  then  <Card><CardContent flush><DataTable/></CardContent></Card>
 
 // 7) Sidebar footer looks washed-out / off-design
 //    Cause: raw opacity-*/text-[11px]. Use semantic tokens.
@@ -9377,7 +9516,7 @@ var PATTERNS = [
 //    Cause: Math.random()/argless new Date() during render (SSR \u2260 client).
 // \u2705  seed deterministically by index, or compute in an event handler.
 
-// 10) Hide a column on mobile / sign-aware KPI delta (@godxjp/ui >= 6.2.0)
+// 10) Hide a column on mobile / sign-aware KPI delta
 // \u2705  columns: [{ key: "email", header: "\u30E1\u30FC\u30EB", hiddenOnMobile: true }]
 // \u2705  <StatCard label="\u58F2\u4E0A" value="\xA58.2M" delta="+12%" />   // + green / - red; inverse flips`
   },
@@ -9391,7 +9530,7 @@ import { z } from "zod";
 import { Card, CardHeader, CardTitle, CardContent, CardFooter } from "@godxjp/ui/data-display";
 import { FormField, Input } from "@godxjp/ui/data-entry";
 import { Button } from "@godxjp/ui/general";
-import { Stack } from "@godxjp/ui/layout";
+import { Flex } from "@godxjp/ui/layout";
 
 const schema = z.object({
   name: z.string().min(1, "\u6C0F\u540D\u306F\u5FC5\u9808\u3067\u3059"),
@@ -9409,18 +9548,19 @@ export function SignUpCard() {
       <CardHeader><CardTitle>\u30A2\u30AB\u30A6\u30F3\u30C8\u4F5C\u6210</CardTitle></CardHeader>
       <CardContent>
         <form id="signup" onSubmit={onSubmit}>
-          <Stack gap="md">
+          {/* Vertical rhythm comes from Flex direction="col" gap \u2014 never space-y-*/gap-* utilities. */}
+          <Flex direction="col" gap="md">
             <FormField id="name" label="\u6C0F\u540D" required error={errors.name?.message}>
               <Input id="name" {...register("name")} />
             </FormField>
             <FormField id="email" label="\u30E1\u30FC\u30EB\u30A2\u30C9\u30EC\u30B9" required error={errors.email?.message}>
               <Input id="email" type="email" {...register("email")} />
             </FormField>
-          </Stack>
+          </Flex>
         </form>
       </CardContent>
       <CardFooter separated>
-        <Button type="submit" form="signup" disabled={isSubmitting}>\u30A2\u30AB\u30A6\u30F3\u30C8\u3092\u4F5C\u6210</Button>
+        <Button type="submit" form="signup" loading={isSubmitting}>\u30A2\u30AB\u30A6\u30F3\u30C8\u3092\u4F5C\u6210</Button>
       </CardFooter>
     </Card>
   );
@@ -9428,33 +9568,97 @@ export function SignUpCard() {
   },
   {
     name: "settings-page-responsive",
-    tagline: "Route-backed settings: persistent desktop local navigation, compact mobile navigation, and bounded form content.",
-    tags: ["settings", "form", "tabs", "admin"],
-    code: `// Research basis: GitHub/Google/Microsoft/Atlassian account settings + Carbon form grid.
-// Use URLs for every destination; do not keep broad settings IA in local tab state.
-import { NavLink, Outlet } from "react-router-dom";
-import { Flex, Stack } from "@godxjp/ui/layout";
+    aliases: ["settings-tabs", "settings-page", "settings-layout"],
+    tagline: "Route-backed settings: persistent desktop local navigation, compact mobile tab strip, deep links + browser history, and bounded form content \u2014 NO Card wrapper, NO undefined CSS.",
+    tags: ["settings", "form", "tabs", "admin", "responsive", "navigation"],
+    code: `// Research basis: GitHub, Google Account, Microsoft Account, Atlassian Account settings +
+// the IBM Carbon form grid. Every destination is a URL, so deep links and browser back/forward
+// work for free and the active item is derived from the route \u2014 never from local tab state.
+//
+// Desktop (>= lg): persistent vertical local nav on the left + bounded content on the right.
+// Mobile (< lg):   the SAME routes become a horizontal, scrollable tab strip above the content.
+// Styling uses ONLY real semantic token classes (bg-muted / text-foreground / text-muted-foreground)
+// and responsive/visibility utilities \u2014 the library ships NO bespoke settings shell/nav CSS classes.
+import { NavLink, Outlet, Navigate } from "react-router-dom";
+import { Flex } from "@godxjp/ui/layout";
 import { FormField, Input } from "@godxjp/ui/data-entry";
+import { Button } from "@godxjp/ui/general";
 
-export function WorkspaceSettings() {
+const SECTIONS = [
+  { to: "general", label: "\u57FA\u672C\u60C5\u5831" },
+  { to: "security", label: "\u30BB\u30AD\u30E5\u30EA\u30C6\u30A3" },
+  { to: "notifications", label: "\u901A\u77E5" },
+] as const;
+
+// One link renderer for BOTH breakpoints. NavLink gives us the active state (and sets
+// aria-current="page") straight from the URL; semantic tokens only, no invented classes.
+const link = ({ isActive }: { isActive: boolean }) =>
+  [
+    "rounded-md px-3 py-2 text-sm no-underline transition-colors whitespace-nowrap",
+    isActive
+      ? "bg-muted text-foreground font-medium"
+      : "text-muted-foreground hover:text-foreground",
+  ].join(" ");
+
+export function SettingsLayout() {
   return (
-    <Flex gap="lg" className="settings-layout">
-      <nav aria-label="Settings" className="settings-local-nav">
-        <NavLink to="general">\u57FA\u672C\u60C5\u5831</NavLink>
-        <NavLink to="security">\u30BB\u30AD\u30E5\u30EA\u30C6\u30A3</NavLink>
-        <NavLink to="notifications">\u901A\u77E5</NavLink>
+    <Flex direction="col" gap="lg" className="lg:flex-row lg:items-start">
+      {/* < lg: horizontal, scrollable route tabs. */}
+      <nav aria-label="\u8A2D\u5B9A" className="flex gap-1 overflow-x-auto lg:hidden">
+        {SECTIONS.map((s) => (
+          <NavLink key={s.to} to={s.to} className={link} end>{s.label}</NavLink>
+        ))}
       </nav>
-      <main className="settings-content"><Outlet /></main>
+      {/* >= lg: persistent vertical local nav (bounded width, does not shrink). */}
+      <nav aria-label="\u8A2D\u5B9A" className="hidden lg:flex lg:w-56 lg:shrink-0 lg:flex-col lg:gap-1">
+        {SECTIONS.map((s) => (
+          <NavLink key={s.to} to={s.to} className={link} end>{s.label}</NavLink>
+        ))}
+      </nav>
+      {/* Bounded content region (~42rem) \u2014 the routed section renders here. min-w-0 lets it shrink. */}
+      <main className="min-w-0 max-w-2xl flex-1"><Outlet /></main>
     </Flex>
   );
 }
 
-// Desktop: local nav + bounded content (roughly 40rem), horizontal form rows where useful.
-// Mobile (375/390px): same route links become a compact scrollable nav; labels stack above controls.
-// Do not add a Card around the whole page. Tabs are only for 2\u20134 peer views within one task.
-export function GeneralSettingsForm() {
-  return <Stack gap="md"><FormField id="ws-name" label="\u540D\u524D" layout="horizontal" controlWidth="md"><Input id="ws-name" /></FormField></Stack>;
-}`
+// A settings section. Horizontal label/control rows on desktop (collapse to stacked on mobile),
+// controls bounded to a semantic width. FormField OWNS the label\u2194control relationship \u2014 do NOT
+// hand-roll <Label> + <input>. Save feedback = Button loading prop + a toast in onSuccess.
+export function GeneralSettingsSection({
+  defaults, onSave, saving, error,
+}: { defaults: { name: string; email: string }; onSave: (v: FormData) => void; saving: boolean; error?: string }) {
+  return (
+    <form onSubmit={(e) => { e.preventDefault(); onSave(new FormData(e.currentTarget)); }}>
+      <Flex direction="col" gap="md">
+        <FormField id="ws-name" label="\u30EF\u30FC\u30AF\u30B9\u30DA\u30FC\u30B9\u540D" layout="horizontal" controlWidth="24rem"
+          helper="\u8ACB\u6C42\u66F8\u3084\u5171\u6709\u30EA\u30F3\u30AF\u306B\u8868\u793A\u3055\u308C\u307E\u3059\u3002" error={error}>
+          <Input id="ws-name" name="name" defaultValue={defaults.name} />
+        </FormField>
+        <FormField id="ws-email" label="\u9023\u7D61\u5148\u30E1\u30FC\u30EB" layout="horizontal" controlWidth="24rem">
+          <Input id="ws-email" name="email" type="email" defaultValue={defaults.email} />
+        </FormField>
+        <Flex gap="sm"><Button type="submit" loading={saving}>\u5909\u66F4\u3092\u4FDD\u5B58</Button></Flex>
+      </Flex>
+    </form>
+  );
+}
+
+// Router wiring \u2014 each destination is addressable, so deep links + back/forward just work:
+//   <Route path="settings" element={<SettingsLayout/>}>
+//     <Route index element={<Navigate to="general" replace/>} />
+//     <Route path="general" element={<GeneralSettingsSection .../>} />
+//     <Route path="security" element={<SecuritySection/>} />
+//     <Route path="notifications" element={<NotificationsSection/>} />
+//   </Route>
+
+// \u2500\u2500 DO / DON'T \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+// \u2705 Tabs (navigation) are fine for a SMALL number (2\u20134) of PEER views inside ONE task/section
+//    \u2014 e.g. "\u30D7\u30ED\u30D5\u30A3\u30FC\u30EB" \u21C4 "\u74B0\u5883\u8A2D\u5B9A" within a single account page \u2014 where losing the URL is OK.
+// \u26D4 Tabs as the PRIMARY IA for broad settings (Account / Security / Billing / Members / \u2026):
+//    use route-backed local navigation so every area is deep-linkable and back/forward works.
+// \u26D4 Do NOT wrap the whole settings page in a Card, and do NOT make desktop a horizontal tab bar
+//    \u2014 persistent local nav scales to many sections; a tab strip does not.
+// \u26D4 Do NOT invent CSS class names for the shell/nav/content \u2014 compose Flex + semantic tokens.`
   },
   {
     name: "confirm-destructive",
@@ -9464,7 +9668,7 @@ export function GeneralSettingsForm() {
 import { Dialog, DialogContent, DialogHeader, DialogTitle, DialogDescription, DialogFooter } from "@godxjp/ui/feedback";
 import { Input } from "@godxjp/ui/data-entry";
 import { Button } from "@godxjp/ui/general";
-import { Stack } from "@godxjp/ui/layout";
+import { Flex } from "@godxjp/ui/layout";
 import { toast } from "sonner";
 
 export function DeleteProjectDialog({ open, onOpenChange, slug }: { open: boolean; onOpenChange: (v: boolean) => void; slug: string }) {
@@ -9476,9 +9680,9 @@ export function DeleteProjectDialog({ open, onOpenChange, slug }: { open: boolea
           <DialogTitle>\u30D7\u30ED\u30B8\u30A7\u30AF\u30C8\u3092\u524A\u9664</DialogTitle>
           <DialogDescription>\u3053\u306E\u64CD\u4F5C\u306F\u53D6\u308A\u6D88\u305B\u307E\u305B\u3093\u3002\u78BA\u8A8D\u306E\u305F\u3081\u30D7\u30ED\u30B8\u30A7\u30AF\u30C8\u540D "{slug}" \u3068\u5165\u529B\u3057\u3066\u304F\u3060\u3055\u3044\u3002</DialogDescription>
         </DialogHeader>
-        <Stack gap="md">
+        <Flex direction="col" gap="md">
           <Input value={confirm} onValueChange={(e) => setConfirm(e.target.value)} placeholder={slug} />
-        </Stack>
+        </Flex>
         <DialogFooter>
           <Button variant="outline" onClick={() => onOpenChange(false)}>\u30AD\u30E3\u30F3\u30BB\u30EB</Button>
           <Button tone="destructive" disabled={confirm !== slug} onClick={() => { toast.success("\u524A\u9664\u3057\u307E\u3057\u305F"); onOpenChange(false); }}>\u5B8C\u5168\u306B\u524A\u9664</Button>
@@ -9518,14 +9722,14 @@ export default function Coupons({ coupons }: { coupons?: Coupon[] }) {
   },
   {
     name: "inertia-list-page",
-    tagline: "Inertia + @godxjp/ui list page \u2014 PageContainer + FilterBar + DataTable + Badge + Pagination (current primitive API).",
+    tagline: "Inertia + @godxjp/ui list page \u2014 PageContainer + Toolbar + DataTable + Badge + Pagination (current primitive API).",
     tags: ["inertia", "list", "table", "page", "filter", "pagination", "datatable", "crm"],
     code: `import { Head, router } from "@inertiajs/react"
 import { useMemo, useState } from "react"
-import { PageContainer, ResponsiveGrid, Stack } from "@godxjp/ui/layout"
+import { PageContainer, ResponsiveGrid, Flex } from "@godxjp/ui/layout"
 import { Card, CardContent, StatCard, DataTable, EmptyState, Badge, type ColumnDef } from "@godxjp/ui/data-display"
 import { SearchInput, Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from "@godxjp/ui/data-entry"
-import { FilterBar, FilterGroup, Pagination } from "@godxjp/ui/navigation"
+import { Toolbar, ToolbarGroup, Pagination } from "@godxjp/ui/navigation"
 import { formatDate } from "@godxjp/ui/datetime"
 import { withCrmLayout } from "@/layouts/crm-layout" // see "inertia-persistent-layout"
 
@@ -9556,19 +9760,20 @@ function Coupons({ coupons }: { coupons: Coupon[] }) {
   return (
     <>
       <Head title="\u30AF\u30FC\u30DD\u30F3\u7BA1\u7406" />
-      {/* RULE: every page wraps in PageContainer; spacing via Stack/ResponsiveGrid, never p-*/gap-* */}
+      {/* RULE: every page wraps in PageContainer; vertical rhythm via Flex direction="col"/ResponsiveGrid, never p-*/gap-* */}
       <PageContainer title="\u30AF\u30FC\u30DD\u30F3\u7BA1\u7406" subtitle="\u914D\u4FE1\u4E2D\u306E\u30AF\u30FC\u30DD\u30F3\u4E00\u89A7">
-        <Stack gap="lg">
+        <Flex direction="col" gap="lg">
           <ResponsiveGrid columns={3}>
             <StatCard label="\u516C\u958B\u4E2D" value={coupons.filter((c) => c.status === "\u516C\u958B\u4E2D").length} />
             <StatCard label="\u7DCF\u5229\u7528\u6570" value={coupons.reduce((s, c) => s + c.usage, 0).toLocaleString()} />
             <StatCard label="\u4EF6\u6570" value={coupons.length} />
           </ResponsiveGrid>
 
-          <FilterBar hasActiveFilters={q !== "" || status !== "all"} onClear={() => { setQ(""); setStatus("all"); setPage(1) }}>
+          {/* Toolbar is the filter-bar primitive (standalone, above the table surface). */}
+          <Toolbar hasActiveFilters={q !== "" || status !== "all"} onClear={() => { setQ(""); setStatus("all"); setPage(1) }}>
             {/* SearchInput is value + onSearch(v) \u2014 NOT onChange */}
             <SearchInput placeholder="\u30AF\u30FC\u30DD\u30F3\u540D\u3067\u691C\u7D22" value={q} onSearch={(v) => { setQ(v); setPage(1) }} />
-            <FilterGroup label="\u30B9\u30C6\u30FC\u30BF\u30B9">
+            <ToolbarGroup label="\u30B9\u30C6\u30FC\u30BF\u30B9">
               <Select value={status} onValueChange={(v) => { setStatus(v); setPage(1) }}>
                 <SelectTrigger><SelectValue /></SelectTrigger>
                 <SelectContent>
@@ -9577,8 +9782,8 @@ function Coupons({ coupons }: { coupons: Coupon[] }) {
                   <SelectItem value="\u4E0B\u66F8\u304D">\u4E0B\u66F8\u304D</SelectItem>
                 </SelectContent>
               </Select>
-            </FilterGroup>
-          </FilterBar>
+            </ToolbarGroup>
+          </Toolbar>
 
           <Card>
             <CardContent flush>
@@ -9588,10 +9793,11 @@ function Coupons({ coupons }: { coupons: Coupon[] }) {
             </CardContent>
           </Card>
 
+          {/* Pagination ONLY for real multi-page data \u2014 hide it while empty or single-page. */}
           {filtered.length > PAGE_SIZE && (
             <Pagination value={page} total={filtered.length} pageSize={PAGE_SIZE} showTotal onValueChange={(p) => setPage(p)} />
           )}
-        </Stack>
+        </Flex>
       </PageContainer>
     </>
   )
@@ -9605,7 +9811,7 @@ export default Coupons`
     tagline: "Inertia detail page \u2014 receives {id} prop, Descriptions (compound) + StatCard + EmptyState fallback.",
     tags: ["inertia", "detail", "show", "page", "keyvaluegrid", "crm"],
     code: `import { Head, router } from "@inertiajs/react"
-import { PageContainer, ResponsiveGrid, Stack } from "@godxjp/ui/layout"
+import { PageContainer, ResponsiveGrid, Flex } from "@godxjp/ui/layout"
 import { Card, CardContent, StatCard, EmptyState, Descriptions, Badge } from "@godxjp/ui/data-display"
 import { Button } from "@godxjp/ui/general"
 import { formatDate } from "@godxjp/ui/datetime"
@@ -9633,7 +9839,7 @@ function MemberShow({ id }: { id: string }) {
     <>
       <Head title={member.name} />
       <PageContainer title={member.name} subtitle={\`\${member.id} / \${member.rank}\`}>
-        <Stack gap="lg">
+        <Flex direction="col" gap="lg">
           <ResponsiveGrid columns={4}>
             <StatCard label="\u7D2F\u8A08\u8CFC\u5165\u984D" value={\`\xA5\${member.total.toLocaleString()}\`} />
             <StatCard label="\u6765\u5E97\u56DE\u6570" value={member.visits} />
@@ -9651,7 +9857,7 @@ function MemberShow({ id }: { id: string }) {
               </Descriptions>
             </CardContent>
           </Card>
-        </Stack>
+        </Flex>
       </PageContainer>
     </>
   )
@@ -9695,7 +9901,7 @@ const seeded = (n: number) => { const x = Math.sin((n + 1) * 99.71) * 1e4; retur
   },
   {
     name: "badge-coloring",
-    tagline: "Colour a Badge for localized labels and tiers via tone + icon (escape-hatch props, @godxjp/ui \u2265 6.1).",
+    tagline: "Colour a Badge for localized labels and tiers via tone + icon (escape-hatch props).",
     tags: ["statusbadge", "badge", "tone", "color", "status", "tier", "table"],
     code: `import { Badge } from "@godxjp/ui/data-display"
 
@@ -9704,7 +9910,7 @@ const seeded = (n: number) => { const x = Math.sin((n + 1) * 99.71) * 1e4; retur
 //   scheduled/sending (info) \xB7 cancelled (neutral) \xB7 failed/deleted/bounced (destructive \u2715)
 // Anything else (localized labels, tiers) falls back to neutral grey \u25CB unless you override.
 
-// 1) Lifecycle with localized text \u2014 map to the key, keep JP via \`label\` (icon stays):
+// 1) Lifecycle with localized text \u2014 map to the key, keep JP via children (icon stays):
 <Badge status="active">\u516C\u958B\u4E2D</Badge>        // green \u2713 \u516C\u958B\u4E2D
 
 // 2) Unknown label \u2014 set tone explicitly (no icon, since the key is unknown):
@@ -9715,78 +9921,348 @@ const seeded = (n: number) => { const x = Math.sin((n + 1) * 99.71) * 1e4; retur
 <Badge status="\u30B4\u30FC\u30EB\u30C9"   tone="warning" icon={null} />
 <Badge status="\u6CD5\u4EBA\u5171\u901A"   tone="info"    icon={null} />
 
-// tone: "success" | "warning" | "destructive" | "info" | "neutral"  (import type BadgeTone)
+// tone: "success" | "warning" | "destructive" | "info" | "neutral"  (import type ToneProp)
 // RULE: a chip never wraps \u2014 it is pinned white-space: nowrap, so it stays one line in
 // narrow table cells. Centralize the domain\u2192tone map in ONE small consumer wrapper and
 // import that instead of the raw Badge across pages.`
   },
   {
     name: "async-data-state",
-    tagline: "Mutually exclusive prerequisite, loading, data, empty, and cause-aware error states.",
-    tags: ["async", "loading", "query", "error", "empty"],
-    code: `import { DataState } from "@godxjp/ui/query";
-import { EmptyState, SkeletonTable } from "@godxjp/ui/data-display";
-
-// enabled:false is prerequisite/idle, not loading \u2014 DataState checks fetchStatus, not just isPending.
-// Errors are classified by cause: onAuthError handles 401/expired token (session renewal, NOT retry);
-// Retry appears automatically only for transient/network/5xx; 403/404/422 show a cause-aware message.
-<DataState query={query} prerequisite={<EmptyState variant="section" title="\u7D44\u7E54\u3092\u9078\u629E\u3057\u3066\u304F\u3060\u3055\u3044" />}
-  skeleton={<SkeletonTable />} empty={<EmptyState variant="section" title="\u7D50\u679C\u304C\u3042\u308A\u307E\u305B\u3093" />}
-  isEmpty={(data) => data.items.length === 0}
-  onAuthError={() => auth.signInAgain()}>
-  {(data) => <Results items={data.items} />}
-</DataState>
-
-// Need a bespoke error UI? Pass errorRenderer and branch on classifyQueryError(error).category
-// ("auth" | "forbidden" | "notFound" | "validation" | "transient" | "unknown").
-// The default detail is a localized message \u2014 never raw token/endpoint/stack text.
-// Never render pagination outside the successful populated-data branch.`
+    aliases: ["loading-states", "data-state", "query-states"],
+    tagline: "The full async state machine \u2014 ONE primary state at a time: prerequisite, disabled-vs-loading, stale refresh, populated, real-empty, and cause-aware error (401/403/404/422/transient) with correct recovery.",
+    tags: ["async", "loading", "query", "error", "empty", "prerequisite", "retry", "react-query"],
+    code: `import { DataState, classifyQueryError } from "@godxjp/ui/query";
+import { EmptyState } from "@godxjp/ui/data-display";
+import { SkeletonTable } from "@godxjp/ui/feedback";
+import { Building2, Inbox } from "lucide-react";
+
+// ONE primary state renders at a time; DataState makes them mutually exclusive:
+//   prerequisite \u2192 skeleton(loading) \u2192 data \u2192 empty \u2192 error   (never two at once).
+//
+// enabled:false is PREREQUISITE/idle, NOT loading. TanStack reports isPending while a query is
+// disabled, but fetchStatus stays "idle" (no request in flight) \u2014 DataState renders the prerequisite
+// slot, so a disabled query shows an instruction, NOT an endless skeleton.
+//   const query = useQuery({ queryKey: ["members", orgId], queryFn, enabled: Boolean(orgId) });
+//
+// A background refetch over EXISTING data keeps the content on screen (no skeleton flash) and
+// announces the busy state politely \u2014 stale/placeholder refresh is handled for you.
+//
+// Errors are classified by CAUSE, not blanket-retried:
+//   auth (401)         \u2192 onAuthError: renew session / sign in again  (NOT a retry)
+//   forbidden (403)    \u2192 permission message + access path            (no retry)
+//   notFound (404)     \u2192 contextual not-found                        (no retry)
+//   validation (400/422)\u2192 corrective guidance                        (no retry)
+//   transient (408/429/5xx/network) \u2192 Retry offered automatically
+//   unknown            \u2192 neutral; opt into Retry via showRetry/onRetry only if it can help
+export function MembersPanel({ query, orgId, onSignIn }: {
+  query: any; orgId?: string; onSignIn: () => void;
+}) {
+  return (
+    <DataState
+      query={query}
+      prerequisite={<EmptyState icon={Building2} variant="section" title="\u7D44\u7E54\u3092\u9078\u629E\u3057\u3066\u304F\u3060\u3055\u3044"
+        description="\u30E1\u30F3\u30D0\u30FC\u3092\u8868\u793A\u3059\u308B\u306B\u306F\u3001\u4E0A\u306E\u30BB\u30EC\u30AF\u30BF\u3067\u7D44\u7E54\u3092\u9078\u3073\u307E\u3059\u3002" />}
+      skeleton={<SkeletonTable rows={8} columns={4} />}
+      empty={<EmptyState icon={Inbox} variant="section" title="\u30E1\u30F3\u30D0\u30FC\u304C\u3044\u307E\u305B\u3093"
+        description="\u3053\u306E\u7D44\u7E54\u306B\u306F\u307E\u3060\u30E1\u30F3\u30D0\u30FC\u304C\u767B\u9332\u3055\u308C\u3066\u3044\u307E\u305B\u3093\u3002" />}
+      isEmpty={(data) => data.items.length === 0}
+      onAuthError={onSignIn}
+    >
+      {(data) => <MemberTable items={data.items} />}
+    </DataState>
+  );
+}
+
+// Need a bespoke error surface? Pass errorRenderer and branch on the classified category \u2014 the
+// default detail is always a localized message (never raw token / endpoint / stack text):
+//   errorRenderer={(error, retry) => {
+//     const { category } = classifyQueryError(error);
+//     if (category === "auth") return <SessionExpired onRenew={onSignIn} />;
+//     if (category === "forbidden") return <NoAccess />;
+//     if (category === "transient") return <Retryable onRetry={retry} />;
+//     return <GenericError />;
+//   }}
+// RULE: pagination/footer chrome NEVER renders outside the populated-data branch (see data-table-page).`
   },
   {
     name: "data-table-page",
-    tagline: "Filter + table + single-row footer pagination, visible only for successful multi-page data.",
-    tags: ["table", "pagination", "filter", "async"],
-    code: `// FilterBar is standalone. Card owns one table surface; do not nest Card/Alert surfaces.
-// Inside DataState's success branch:
-<Card><CardContent flush><DataTable data={data.items} columns={columns} />
-  {data.totalPages > 1 && <Flex justify="between" align="center"><span>{range}</span><Pagination /></Flex>}
-</CardContent></Card>
-// Hide pagination for prerequisite/loading/error/empty and one-page results.
-// Preserve filters/page during a transient retry; stack only at narrow mobile widths.`
+    aliases: ["filter-bar", "table-state", "list-page"],
+    tagline: "Filter (Toolbar) + table surface + bottom pagination driven by a query state machine \u2014 pagination shows ONLY for successful multi-page data; filters/page survive a transient retry.",
+    tags: ["table", "pagination", "filter", "async", "toolbar", "datatable"],
+    code: `import { useState } from "react";
+import { DataState } from "@godxjp/ui/query";
+import { Card, CardContent, DataTable, EmptyState, type ColumnDef } from "@godxjp/ui/data-display";
+import { SkeletonTable } from "@godxjp/ui/feedback";
+import { SearchInput, Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from "@godxjp/ui/data-entry";
+import { Toolbar, ToolbarGroup, Pagination } from "@godxjp/ui/navigation";
+import { Flex } from "@godxjp/ui/layout";
+import { useQuery, keepPreviousData } from "@tanstack/react-query";
+
+type Row = { id: string; name: string; status: string };
+
+export function MembersTablePage({ orgId }: { orgId?: string }) {
+  const [q, setQ] = useState("");
+  const [status, setStatus] = useState("all");
+  const [page, setPage] = useState(1);
+  const pageSize = 20;
+
+  // placeholderData: keepPreviousData \u2192 on page/filter change the PREVIOUS page stays visible
+  // (a stale refresh) instead of flashing a skeleton. enabled gates on the prerequisite (orgId).
+  const query = useQuery({
+    queryKey: ["members", orgId, q, status, page],
+    queryFn: () => fetchMembers({ orgId: orgId!, q, status, page, pageSize }),
+    enabled: Boolean(orgId),
+    placeholderData: keepPreviousData,
+  });
+
+  const columns: ColumnDef<Row>[] = [
+    { key: "name", header: "\u6C0F\u540D", render: (r) => <span className="font-medium">{r.name}</span> },
+    { key: "status", header: "\u30B9\u30C6\u30FC\u30BF\u30B9" },
+  ];
+
+  return (
+    <Flex direction="col" gap="lg">
+      {/* Toolbar (filter bar) is STANDALONE and always visible so the user can change filters even
+          while a query is idle/loading/empty. Changing a filter resets to page 1. */}
+      <Toolbar hasActiveFilters={q !== "" || status !== "all"}
+        onClear={() => { setQ(""); setStatus("all"); setPage(1); }}>
+        <SearchInput placeholder="\u6C0F\u540D\u3067\u691C\u7D22" value={q} onSearch={(v) => { setQ(v); setPage(1); }} />
+        <ToolbarGroup label="\u30B9\u30C6\u30FC\u30BF\u30B9">
+          <Select value={status} onValueChange={(v) => { setStatus(v); setPage(1); }}>
+            <SelectTrigger><SelectValue /></SelectTrigger>
+            <SelectContent>
+              <SelectItem value="all">\u3059\u3079\u3066</SelectItem>
+              <SelectItem value="active">\u6709\u52B9</SelectItem>
+              <SelectItem value="invited">\u62DB\u5F85\u4E2D</SelectItem>
+            </SelectContent>
+          </Select>
+        </ToolbarGroup>
+      </Toolbar>
+
+      {/* The table surface owns exactly ONE card. Pagination lives INSIDE the success branch, so it
+          is hidden during prerequisite / loading / empty / error and for single-page results. */}
+      <DataState
+        query={query}
+        prerequisite={<EmptyState variant="section" title="\u7D44\u7E54\u3092\u9078\u629E\u3057\u3066\u304F\u3060\u3055\u3044" />}
+        skeleton={<Card><CardContent flush><SkeletonTable rows={8} columns={2} /></CardContent></Card>}
+        empty={<EmptyState variant="section" title="\u8A72\u5F53\u3059\u308B\u30E1\u30F3\u30D0\u30FC\u304C\u3044\u307E\u305B\u3093" description="\u691C\u7D22\u6761\u4EF6\u3092\u5909\u66F4\u3057\u3066\u304F\u3060\u3055\u3044\u3002" />}
+        isEmpty={(d) => d.items.length === 0}
+      >
+        {(d) => {
+          const totalPages = Math.ceil(d.total / pageSize);
+          return (
+            <>
+              <Card><CardContent flush><DataTable data={d.items} columns={columns} getRowId={(r) => r.id} /></CardContent></Card>
+              {totalPages > 1 && (
+                <Pagination value={page} total={d.total} pageSize={pageSize} showTotal onValueChange={setPage} />
+              )}
+            </>
+          );
+        }}
+      </DataState>
+    </Flex>
+  );
+}
+// Responsive: Pagination's showTotal range + controls stack at narrow widths automatically.
+// A transient retry keeps q/status/page (they live in component state, not the query) \u2014 the
+// same page reloads in place; the user never loses their filters.`
   },
   {
     name: "organization-memberships",
-    tagline: "Workspace identity, current state, role and permission-aware actions; invitations are conditional.",
-    tags: ["organization", "workspace", "membership", "invitation", "account"],
-    code: `// Research basis: GitHub organizations and Slack workspace switching/invitations.
-// Each row: logo + recognizable name + Current badge + role + Open/Switch/Manage/Leave action.
-// Put Create organization at page level. Do not show raw membership timestamps without labels.
-// No pending invitations \u2192 omit the section entirely.
-// Few pending \u2192 compact actionable list; many/history \u2192 a focused route.
-<MembershipList memberships={memberships} currentId={currentId} />
-{pendingInvitations.length > 0 && <PendingInvitations variant="compact" items={pendingInvitations} />}`
+    aliases: ["organization-switcher", "workspace-switcher", "received-invitations", "memberships"],
+    tagline: "Workspace membership list \u2014 recognizable identity, current/active state, role, permission-aware Open/Switch/Manage/Leave row actions, page-level Create, and CONDITIONAL invitations (omit when none).",
+    tags: ["organization", "workspace", "membership", "invitation", "account", "switcher"],
+    code: `// Research basis: GitHub organization membership + Slack workspace switching/invitations.
+// Each row = recognizable identity (Avatar/logo, NOT an identical decorative icon) + name +
+// a "\u73FE\u5728" (Current) badge for the active org + role + a permission-aware action menu.
+import { Card, CardContent, CardHeader, CardTitle, ListRow, Badge, Avatar, AvatarImage, AvatarFallback, EmptyState } from "@godxjp/ui/data-display";
+import { Button } from "@godxjp/ui/general";
+import { Flex } from "@godxjp/ui/layout";
+import { DropdownMenu, DropdownMenuTrigger, DropdownMenuContent, DropdownMenuItem } from "@godxjp/ui/navigation";
+import { MoreHorizontal, Plus } from "lucide-react";
+
+type Role = "owner" | "admin" | "member";
+type Membership = { id: string; name: string; logoUrl?: string; role: Role; joinedAt: string; isCurrent: boolean; canManage: boolean };
+type Invite = { id: string; orgName: string; invitedBy: string };
+
+const ROLE_LABEL: Record<Role, string> = { owner: "\u30AA\u30FC\u30CA\u30FC", admin: "\u7BA1\u7406\u8005", member: "\u30E1\u30F3\u30D0\u30FC" };
+
+export function OrganizationMemberships({
+  memberships, invitations, onOpen, onSwitch, onManage, onLeave, onCreate, onAccept, onDecline,
+}: {
+  memberships: Membership[]; invitations: Invite[];
+  onOpen: (id: string) => void; onSwitch: (id: string) => void; onManage: (id: string) => void;
+  onLeave: (id: string) => void; onCreate: () => void; onAccept: (id: string) => void; onDecline: (id: string) => void;
+}) {
+  return (
+    <Flex direction="col" gap="lg">
+      <Card>
+        <CardHeader>
+          <Flex justify="between" align="center">
+            <CardTitle>\u7D44\u7E54</CardTitle>
+            {/* Create belongs at page/section level, not per row. */}
+            <Button variant="outline" size="sm" onClick={onCreate}><Plus className="size-4" />\u7D44\u7E54\u3092\u4F5C\u6210</Button>
+          </Flex>
+        </CardHeader>
+        {/* flush \u2192 ListRows draw their own edge-to-edge dividers. */}
+        <CardContent flush>
+          {memberships.length === 0 ? (
+            <EmptyState variant="section" title="\u6240\u5C5E\u3057\u3066\u3044\u308B\u7D44\u7E54\u304C\u3042\u308A\u307E\u305B\u3093" description="\u65B0\u3057\u3044\u7D44\u7E54\u3092\u4F5C\u6210\u3059\u308B\u304B\u3001\u62DB\u5F85\u3092\u53D7\u3051\u53D6\u3063\u3066\u304F\u3060\u3055\u3044\u3002" />
+          ) : (
+            memberships.map((m) => (
+              <ListRow
+                key={m.id}
+                leading={
+                  <Avatar>
+                    {m.logoUrl ? <AvatarImage src={m.logoUrl} alt="" /> : null}
+                    <AvatarFallback>{m.name.slice(0, 1)}</AvatarFallback>
+                  </Avatar>
+                }
+                title={
+                  <Flex gap="sm" align="center">
+                    <span className="font-medium">{m.name}</span>
+                    {m.isCurrent && <Badge tone="success" icon={null}>\u73FE\u5728</Badge>}
+                  </Flex>
+                }
+                description={ROLE_LABEL[m.role]}
+                trailing={
+                  <Flex gap="sm" align="center">
+                    {m.isCurrent
+                      ? <Button size="sm" onClick={() => onOpen(m.id)}>\u958B\u304F</Button>
+                      : <Button variant="outline" size="sm" onClick={() => onSwitch(m.id)}>\u5207\u308A\u66FF\u3048</Button>}
+                    <DropdownMenu>
+                      <DropdownMenuTrigger asChild>
+                        <Button variant="ghost" size="icon" aria-label={\`\${m.name} \u306E\u64CD\u4F5C\`}><MoreHorizontal className="size-4" /></Button>
+                      </DropdownMenuTrigger>
+                      <DropdownMenuContent align="end">
+                        <DropdownMenuItem onSelect={() => onOpen(m.id)}>\u958B\u304F</DropdownMenuItem>
+                        {m.canManage && <DropdownMenuItem onSelect={() => onManage(m.id)}>\u7BA1\u7406</DropdownMenuItem>}
+                        {m.role !== "owner" && <DropdownMenuItem onSelect={() => onLeave(m.id)}>\u9000\u51FA</DropdownMenuItem>}
+                      </DropdownMenuContent>
+                    </DropdownMenu>
+                  </Flex>
+                }
+              />
+            ))
+          )}
+        </CardContent>
+      </Card>
+
+      {/* CONDITIONAL invitations \u2014 no pending invites \u21D2 render NOTHING (no permanent empty Card).
+          Few pending \u21D2 a compact actionable list. Many/history \u21D2 link to a focused route instead. */}
+      {invitations.length > 0 && (
+        <Card>
+          <CardHeader><CardTitle>\u4FDD\u7559\u4E2D\u306E\u62DB\u5F85</CardTitle></CardHeader>
+          <CardContent flush>
+            {invitations.map((inv) => (
+              <ListRow
+                key={inv.id}
+                title={<span className="font-medium">{inv.orgName}</span>}
+                description={\`\${inv.invitedBy} \u304B\u3089\u306E\u62DB\u5F85\`}
+                trailing={
+                  <Flex gap="sm">
+                    <Button size="sm" onClick={() => onAccept(inv.id)}>\u53C2\u52A0</Button>
+                    <Button variant="ghost" size="sm" onClick={() => onDecline(inv.id)}>\u8F9E\u9000</Button>
+                  </Flex>
+                }
+              />
+            ))}
+          </CardContent>
+        </Card>
+      )}
+    </Flex>
+  );
+}
+// DON'T: passive rows with no action \xB7 identical decorative icons \xB7 unlabeled timestamps
+// (label them: "2024\u5E74\u306B\u53C2\u52A0") \xB7 a large empty invitation Card shown permanently.`
   },
   {
     name: "account-recovery-settings",
-    tagline: "Signed-in recovery method status rows, separate from password change and signed-out recovery.",
-    tags: ["account", "recovery", "security", "backup-codes", "password"],
-    code: `// Research basis: Google Account recovery, Microsoft Security info, GitHub recovery codes.
-// Use compact method rows: method + verified/available status + Add/Change/Regenerate action.
-// Do not stack generic Info Alerts for ordinary capability status.
-<RecoveryMethodRow method="email" value={maskedEmail} status="verified" action={<Button>\u5909\u66F4</Button>} />
-{backupCodesSupported && <RecoveryMethodRow method="backup-codes" status={codeStatus} action={<Button>\u518D\u751F\u6210</Button>} />}
-// Password change is a separate destination. Forgot-password is a signed-out journey.`
+    aliases: ["recovery-email", "backup-codes", "security-settings", "recovery-settings"],
+    tagline: "Signed-in recovery: compact method status/action rows (email \xB7 phone \xB7 backup codes) + a separate password-change destination \u2014 capability-aware, risk-appropriate, NO stacked Info Alerts.",
+    tags: ["account", "recovery", "security", "backup-codes", "password", "settings"],
+    code: `// Research basis: Google Account recovery (email/phone + backup codes), Microsoft Security info,
+// GitHub recovery codes. Signed-IN recovery SETTINGS (manage your methods) is a DIFFERENT surface
+// from the signed-OUT forgot-password JOURNEY \u2014 do not mix them on one page.
+import { Card, CardContent, CardHeader, CardTitle, ListRow, Badge } from "@godxjp/ui/data-display";
+import { Button } from "@godxjp/ui/general";
+import { Flex } from "@godxjp/ui/layout";
+import { Mail, Smartphone, KeyRound } from "lucide-react";
+
+type MethodStatus = "verified" | "unverified" | "unavailable";
+
+const STATUS: Record<MethodStatus, { tone: "success" | "warning" | "neutral"; label: string }> = {
+  verified: { tone: "success", label: "\u78BA\u8A8D\u6E08\u307F" },
+  unverified: { tone: "warning", label: "\u672A\u78BA\u8A8D" },
+  unavailable: { tone: "neutral", label: "\u672A\u8A2D\u5B9A" },
+};
+
+function MethodRow({ icon: Icon, name, value, status, action }: {
+  icon: React.ComponentType<{ className?: string }>; name: string; value?: string;
+  status: MethodStatus; action: React.ReactNode;
+}) {
+  const s = STATUS[status];
+  return (
+    <ListRow
+      leading={<Icon className="text-muted-foreground size-5" />}
+      title={<span className="font-medium">{name}</span>}
+      description={value ?? "\u672A\u8A2D\u5B9A"}
+      trailing={<Flex gap="sm" align="center"><Badge tone={s.tone} icon={null}>{s.label}</Badge>{action}</Flex>}
+    />
+  );
+}
+
+// Compact status/action rows \u2014 one row per method, capability-aware. Do NOT stack full-width
+// Info Alerts for ordinary status, and do NOT show unavailable features as permanent page content
+// beyond a single row that offers to set them up.
+export function AccountRecoverySettings({ email, phone, backupCodesSupported, backupCodesRemaining, onChangeEmail, onChangePhone, onRegenerateCodes, onChangePassword }: {
+  email?: string; phone?: string; backupCodesSupported: boolean; backupCodesRemaining: number;
+  onChangeEmail: () => void; onChangePhone: () => void; onRegenerateCodes: () => void; onChangePassword: () => void;
+}) {
+  return (
+    <Flex direction="col" gap="lg">
+      <Card>
+        <CardHeader><CardTitle>\u30A2\u30AB\u30A6\u30F3\u30C8\u5FA9\u65E7</CardTitle></CardHeader>
+        <CardContent flush>
+          <MethodRow icon={Mail} name="\u5FA9\u65E7\u7528\u30E1\u30FC\u30EB" value={email} status={email ? "verified" : "unavailable"}
+            action={<Button variant="outline" size="sm" onClick={onChangeEmail}>{email ? "\u5909\u66F4" : "\u8FFD\u52A0"}</Button>} />
+          <MethodRow icon={Smartphone} name="\u5FA9\u65E7\u7528\u96FB\u8A71\u756A\u53F7" value={phone} status={phone ? "verified" : "unavailable"}
+            action={<Button variant="outline" size="sm" onClick={onChangePhone}>{phone ? "\u5909\u66F4" : "\u8FFD\u52A0"}</Button>} />
+          {/* Capability-aware: only render backup codes when the account type supports them. */}
+          {backupCodesSupported && (
+            <MethodRow icon={KeyRound} name="\u30D0\u30C3\u30AF\u30A2\u30C3\u30D7\u30B3\u30FC\u30C9"
+              value={\`\u6B8B\u308A \${backupCodesRemaining} \u500B\`} status={backupCodesRemaining > 0 ? "verified" : "unverified"}
+              action={<Button variant="outline" size="sm" onClick={onRegenerateCodes}>\u518D\u751F\u6210</Button>} />
+          )}
+        </CardContent>
+      </Card>
+
+      {/* Password change is its OWN destination (risk-appropriate confirmation lives there). */}
+      <Card>
+        <CardHeader><CardTitle>\u30D1\u30B9\u30EF\u30FC\u30C9</CardTitle></CardHeader>
+        <CardContent>
+          <Flex justify="between" align="center">
+            <span className="text-muted-foreground text-sm">\u6700\u7D42\u66F4\u65B0: 90\u65E5\u524D</span>
+            <Button variant="outline" onClick={onChangePassword}>\u30D1\u30B9\u30EF\u30FC\u30C9\u3092\u5909\u66F4</Button>
+          </Flex>
+        </CardContent>
+      </Card>
+    </Flex>
+  );
+}
+// The signed-OUT recovery journey (forgot password \u2192 email link \u2192 reset) is a separate flow on the
+// auth screens (AuthShell), NOT part of these signed-in settings. Do not surface it here.`
   }
 ];
 function findPattern(name) {
   const slug = name.trim().toLowerCase();
-  return PATTERNS.find((p) => p.name === slug);
+  return PATTERNS.find((p) => p.name === slug || p.aliases?.includes(slug));
 }
 function searchPatterns(query) {
   const q = query.trim().toLowerCase();
   if (q === "") return PATTERNS;
   return PATTERNS.filter(
-    (p) => p.name.includes(q) || p.tagline.toLowerCase().includes(q) || p.tags.some((t) => t.includes(q))
+    (p) => p.name.includes(q) || p.aliases?.some((a) => a.includes(q)) || p.tagline.toLowerCase().includes(q) || p.tags.some((t) => t.includes(q))
   );
 }
 
@@ -10482,8 +10958,8 @@ rule (get_rule) involved, with a minimal repro, expected vs actual, version, and
     id: "design-to-page",
     audience: "consumer",
     name: "Design handoff \u2192 real page (consumer build guide)",
-    whenToUse: "You (a consumer agent) received a Claude Design handoff \u2014 a bundle/mock/screenshot/HTML prototype or a written brief \u2014 and must build it as a REAL page with @godxjp/ui. Read this BEFORE writing any JSX. It teaches: read intent, map every block to a real primitive via this MCP, consume existing tokens, apply the dxs-kintai DNA, treat tables as the centerpiece, resolve gaps by extend-or-ask, and verify.",
-    source: "@godxjp/ui .design/research (chats-intent, tables, atomic-components) + dxs-kintai SKILL/colors_and_type.css",
+    whenToUse: "You (a consumer agent) received a Claude Design handoff \u2014 a bundle/mock/screenshot/HTML prototype or a written brief \u2014 and must build it as a REAL page with @godxjp/ui. Read this BEFORE writing any JSX. It teaches: read intent, map every block to a real primitive via this MCP, consume existing tokens, apply the reference-design DNA, treat tables as the centerpiece, resolve gaps by extend-or-ask, and verify.",
+    source: "@godxjp/ui .design/research (chats-intent, tables, atomic-components) + reference-design SKILL/colors_and_type.css",
     sections: [
       {
         id: "read-intent",
@@ -10532,7 +11008,7 @@ never a literal px. Radii: card 6px, control 4px, inner pill 2px.`
       },
       {
         id: "dna",
-        title: "Apply the dxs-kintai DNA",
+        title: "Apply the reference-design DNA",
         tagline: "\u6E0B\u307F / \u9593 / \u7C21\u7D20 \u2014 fixed color signaling, dense, small headings, 14/1.7, no emoji.",
         body: `These rules survive when you drop the prototype's divs:
 \u2022 \u6E0B\u307F (restraint): primary chroma \u2264 0.18 \u2014 --primary is the single most-important
@@ -10638,7 +11114,7 @@ just buries a library bug inside every app). Instead:
     audience: "consumer",
     name: "Compose a screen \u2014 primitives \u2192 a finished app view (consumer)",
     whenToUse: "You (a consumer agent) are building a NEW screen/page in an app that imports @godxjp/ui \u2014 from a written brief or product requirement, not a design handoff. Read this to assemble it from real primitives via this MCP: pick the right components, lay out one-intent-per-screen, wire every state + a11y + i18n, and verify. For a Claude Design handoff bundle/mock specifically, use design-to-page instead.",
-    source: "@godxjp/ui MCP (consumer surface) \u2014 taste/one-intent + component-discipline + dxs-kintai DNA",
+    source: "@godxjp/ui MCP (consumer surface) \u2014 taste/one-intent + component-discipline + reference-design DNA",
     sections: [
       {
         id: "pick-primitives",
@@ -11037,7 +11513,7 @@ function routeTask(task, opts) {
     ],
     "design-to-page",
     "map-to-primitives",
-    "Map every block to a real @godxjp/ui primitive (MCP-first), consume existing tokens, apply the dxs-kintai DNA, tables central, gaps \u2192 extend-or-ask, verify.",
+    "Map every block to a real @godxjp/ui primitive (MCP-first), consume existing tokens, apply the reference-design DNA, tables central, gaps \u2192 extend-or-ask, verify.",
     ["design-to-page/read-intent", "design-to-page/dna", "design-to-page/tables-central"]
   );
   route(
@@ -12004,12 +12480,12 @@ var AUDIT_RULES = [
     standard: "W3C CSS Logical Properties L1 \xB7 WCAG 2.2 (1.3.2)",
     fix: "Use logical utilities (ms-/me-/ps-/pe-, start-/end-, text-start/end, border-s/e, rounded-s/e)."
   },
-  // ── copy (dxs-kintai DNA) ────────────────────────────────────────────────
+  // ── copy (reference-design DNA) ──────────────────────────────────────────
   {
     id: "no-em-dash-in-copy",
     severity: "warn",
     category: "copy",
-    standard: "@godxjp/ui dxs-kintai typography",
+    standard: "@godxjp/ui reference-design typography",
     fix: "No em-dash (\u2014) in copy; use a middot \xB7 or two calm sentences."
   }
 ];
@@ -12038,7 +12514,7 @@ var VISUAL_RULES = [
     id: "oversaturated-accent",
     severity: "warn",
     category: "color",
-    standard: "@godxjp/ui dxs-kintai \u6E0B\u307F (OKLCH chroma \u2264 0.18)",
+    standard: "@godxjp/ui reference-design \u6E0B\u307F (OKLCH chroma \u2264 0.18)",
     fix: "Desaturate brand/primary surfaces (OKLCH chroma \u2264 0.18); read --primary tokens, no raw vivid bars."
   },
   {
@@ -12063,8 +12539,8 @@ function visualRulesByCategory(category) {
 // package.json
 var package_default = {
   name: "@godxjp/ui-mcp",
-  version: "17.0.0",
-  godxUiCompatibility: "17.0.x",
+  version: "18.0.0",
+  godxUiCompatibility: "18.0.x",
   description: "Model Context Protocol server for @godxjp/ui \u2014 gives Claude Code / Codex CLI / Cursor / any MCP-aware agent live access to the component catalog, prop vocabulary, design tokens, 45 cardinal rules, copy-paste-ready patterns, 12 design / taste skills synthesised from Leonxlnx/taste-skill, 20+ anti-AI-tell patterns, and a 50-check redesign audit \u2014 token-efficient (list \u2192 drill-down).",
   type: "module",
   main: "./dist/index.js",
@@ -12152,7 +12628,7 @@ var TOOL_DEFINITIONS = [
   },
   {
     name: "list_patterns",
-    description: "List every canonical code pattern (registration-form / settings-page / data-table / confirm-destructive / app-shell / filter-bar / loading-states). ~500 bytes. Use before `get_pattern`.",
+    description: "List every canonical code pattern (signup-form / settings-page-responsive / data-table-page / async-data-state / organization-memberships / account-recovery-settings / confirm-destructive \u2026). Common aliases resolve too (loading-states\u2192async-data-state, filter-bar\u2192data-table-page, settings-tabs\u2192settings-page-responsive). ~500 bytes. Use before `get_pattern`.",
     inputSchema: { type: "object", properties: {} }
   },
   {
@@ -13162,7 +13638,12 @@ function suggestPrimitive(useCase) {
     "Select=discrete options, AutoComplete=free-text+suggestions.",
     3
   );
-  check(["filter"], "Form layout='inline' + pattern 'filter-bar'", "Inline form above table.", 4);
+  check(
+    ["filter"],
+    "Toolbar/ToolbarGroup + pattern 'filter-bar' (\u2192 data-table-page)",
+    "Standalone Toolbar filter bar above a table; see the data-table-page pattern.",
+    4
+  );
   check(
     ["delete", "destructive"],
     "Pattern 'confirm-destructive'",