@godxjp/ui-mcp 16.7.2 → 17.0.0

package/dist/index.js

@@ -127,8 +127,8 @@ export default function OrdersPage() {
       {
         name: "direction",
         type: '"row" | "col"',
-        defaultValue: '"col"',
-        description: "Main axis direction. Use row for horizontal runs, col for vertical stacks."
+        defaultValue: '"row"',
+        description: "Main axis direction. Defaults to the CSS platform initial value, row; use col explicitly for vertical stacks."
       },
       {
         name: "gap",
@@ -338,6 +338,73 @@ export function CrmLayout({ children }: { content: React.ReactNode }) {
     storyPath: "layout/AppShell.stories.tsx",
     rules: [23]
   },
+  {
+    name: "AuthShell",
+    group: "layout",
+    tagline: "Centred auth/login page shell \u2014 brand bar (top) + centred card (main) + footer, over min-h-dvh, at comfortable control density.",
+    props: [
+      {
+        name: "children",
+        type: "ReactNode",
+        required: true,
+        description: "Centred content \u2014 typically a single auth <Card> holding the form."
+      },
+      {
+        name: "brand",
+        type: "ReactNode",
+        description: "Brand bar slot pinned to the top (e.g. a <Logo> / product mark)."
+      },
+      {
+        name: "footer",
+        type: "ReactNode",
+        description: "Footer slot pinned to the bottom (legal links, locale switch, support)."
+      }
+    ],
+    usage: [
+      "DO pass a single <Card> (with the form inside <CardContent>) as `children` \u2014 AuthShell centres it and constrains its width via `--auth-shell-card-max-width`; do NOT hand-roll a `.auth-shell-main` / `.ui-auth-scope` wrapper.",
+      "DO put the product/brand mark in `brand` (a <Logo> or an <Avatar>) \u2014 it renders as the top banner landmark; omit it and the banner is not rendered.",
+      "DO use `footer` for compliance/legal/support links or a locale switch \u2014 it renders as the contentinfo landmark below the card.",
+      "DO wrap the card in <Reveal> for the entrance animation (`<AuthShell><Reveal><Card/></Reveal></AuthShell>`) \u2014 Reveal honours prefers-reduced-motion; AuthShell itself stays layout-only.",
+      "DO NOT re-scope control height or heading size in the app \u2014 AuthShell already sets the comfortable control tier (44px, WCAG touch floor) and the larger auth heading via `--auth-shell-control-height` / `--auth-shell-heading-size`; a service retunes those tokens, not a bespoke class.",
+      "DO NOT nest AuthShell inside AppShell (or vice-versa) \u2014 AuthShell is the ROOT shell for unauthenticated pages (login/mfa/passkey/device/reset); AppShell is for the authenticated app."
+    ],
+    useCases: [
+      "Login page: <AuthShell brand={<Logo/>} footer={<AuthFooter/>}> wrapping a <Card> with the email/password form and a primary <Button fullWidth>.",
+      "MFA / passkey / device-authorisation step: same shell, a <Card> with the one-time-code <InputOTP> or a passkey prompt.",
+      "Password reset / forgot-password / accept-invite: the centred single-card flow with a brand bar and a legal footer.",
+      'SSO landing / success confirmation: pair with an <EmptyState tone="success"> inside the card for an approved-device confirmation.'
+    ],
+    related: [
+      "AppShell \u2014 the shell for AUTHENTICATED app pages (sidebar + topbar + main). AuthShell is its unauthenticated counterpart (brand bar + centred card + footer). Never nest the two.",
+      "Reveal \u2014 wrap the auth <Card> in <Reveal> for the entrance animation; AuthShell delegates motion (and prefers-reduced-motion handling) to it rather than baking an animation in.",
+      "Card \u2014 the canonical container for the auth form; place the form inside <CardContent>. AuthShell centres and width-constrains it.",
+      'EmptyState \u2014 with `tone="success"` for a confirmation card inside the shell (e.g. device approved).'
+    ],
+    example: `import { AuthShell } from "@godxjp/ui/layout";
+import { Reveal, Logo, Button } from "@godxjp/ui/general";
+import { Card, CardContent, CardHeader, CardTitle } from "@godxjp/ui/data-display";
+import { Field } from "@godxjp/ui/data-entry";
+
+export function LoginPage() {
+  return (
+    <AuthShell brand={<Logo />} footer={<span>\xA9 2026 GodX</span>}>
+      <Reveal>
+        <Card>
+          <CardHeader>
+            <CardTitle>\u30ED\u30B0\u30A4\u30F3</CardTitle>
+          </CardHeader>
+          <CardContent>
+            {/* form fields */}
+            <Button fullWidth>\u7D9A\u3051\u308B</Button>
+          </CardContent>
+        </Card>
+      </Reveal>
+    </AuthShell>
+  );
+}`,
+    storyPath: "layout/AuthShell.stories.tsx",
+    rules: [23]
+  },
   {
     name: "Sidebar",
     group: "layout",
@@ -867,6 +934,117 @@ import { Trash2 } from "lucide-react";
 <Heading level={2}>\u8ACB\u6C42\u66F8\u4E00\u89A7</Heading>
 <Heading level={3} tone="muted">\u88DC\u8DB3\u30BB\u30AF\u30B7\u30E7\u30F3</Heading>`
   },
+  {
+    name: "Logo",
+    group: "general",
+    tagline: "The product brand-mark box \u2014 a glyph on the primary fill. Tokenised size/radius/type; the fill reads --primary so a re-theme re-tints it. Decorative by default; pair with a wordmark.",
+    props: [
+      {
+        name: "glyph",
+        type: "React.ReactNode",
+        defaultValue: '"g"',
+        description: "The brand glyph \u2014 a short mark (letter/initials) or a custom inline <svg>."
+      },
+      {
+        name: "size",
+        type: '"xs" | "sm" | "md" | "lg"',
+        defaultValue: '"md"',
+        description: "Box size tier (tokenised)."
+      },
+      {
+        name: "label",
+        type: "string",
+        description: "Accessible name. Set \u2192 exposed as a named image (role img); omitted \u2192 decorative (aria-hidden), the correct default when a readable wordmark sits beside it."
+      }
+    ],
+    usage: [
+      'DO import from `@godxjp/ui/general`: `import { Logo } from "@godxjp/ui/general";`',
+      'DO use Logo INSTEAD of hand-rolling `<span aria-hidden className="grid size-7 place-items-center rounded-md bg-primary text-sm font-bold text-primary-foreground">g</span>` \u2014 that repeats literal size/radius and puts type utilities on a bare span (rules #45/#46).',
+      "DO leave `label` unset when a readable wordmark sits beside the mark (shell header, topbar) \u2014 the mark stays decorative and the wordmark carries the accessible name. Set `label` only when the mark stands alone.",
+      "DON'T pass more than 1\u20132 glyphs \u2014 the box is square and centres its content; a long string overflows. For a full wordmark use `Text`/`Heading` beside the Logo, not inside it.",
+      'DON\'T re-tint via `className="bg-*"` \u2014 the fill reads the `--primary` role token; retune it through a service theme (`--primary`, `--logo-radius`, `--logo-size-*`), not utilities.'
+    ],
+    useCases: [
+      'App-shell header brand lockup \u2014 `<Logo glyph="c" /> <Text weight="medium">CoreBooks</Text>` in the sidebar/topbar, mark decorative, wordmark readable.',
+      'Auth screen \u2014 a standalone labelled mark above the sign-in form: `<Logo label="CoreBooks" size="lg" />`.',
+      'Tenant/workspace switcher row \u2014 a small `size="sm"` mark as the leading slot of a ListRow or menu item.',
+      "Custom SVG brand \u2014 pass an inline `<svg>` as `glyph` to render a real logomark on the primary fill instead of a letter."
+    ],
+    related: [
+      "Text / Heading \u2014 use for the readable wordmark BESIDE the Logo (the full lockup); the Logo is only the square mark, not the product name.",
+      "Avatar \u2014 use Avatar for a PERSON/entity image or initials; use Logo for the PRODUCT brand mark. They look similar (square/rounded glyph) but carry different meaning."
+    ],
+    storyPath: "general/Logo.stories.tsx",
+    rules: [45, 46],
+    example: `import { Logo } from "@godxjp/ui/general";
+import { Text } from "@godxjp/ui/general";
+
+<span className="inline-flex items-center gap-2">
+  <Logo glyph="c" />
+  <Text weight="medium">CoreBooks</Text>
+</span>
+
+<Logo label="CoreBooks" size="lg" />`
+  },
+  {
+    name: "Reveal",
+    group: "general",
+    tagline: "The official entrance-motion primitive (staggered fade-up) \u2014 reads DS motion tokens and honours prefers-reduced-motion, replacing hand-rolled @keyframes + .app-reveal/.d1..d6 classes.",
+    props: [
+      {
+        name: "children",
+        type: "ReactNode",
+        required: true,
+        description: "Content to reveal on enter."
+      },
+      {
+        name: "delay",
+        type: "0 | 1 | 2 | 3 | 4 | 5 | 6",
+        defaultValue: "0",
+        description: "Stagger ordinal \u2014 an INDEX into the motion ladder, never a raw ms. Each step adds one `--reveal-stagger-step` of delay so a column of reveals cascades. 0 = enter immediately."
+      },
+      {
+        name: "asChild",
+        type: "boolean",
+        defaultValue: "false",
+        description: "Merge the reveal onto the single child element (no wrapper <div>) \u2014 use when an extra box would break a grid/flex layout."
+      }
+    ],
+    usage: [
+      "DO use <Reveal> INSTEAD of hand-rolling `@keyframes auth-fade-up` + `.app-reveal` + `.d1..d6` in a consumer global.css \u2014 that repeats literal durations/delays and violates the tokens-only rule. Reveal reads `--duration-slow` / `--ease-emphasized` / `--reveal-distance` / `--reveal-stagger-step`.",
+      "DO stagger a list/column by passing an increasing `delay` (1, 2, 3\u2026) to successive siblings \u2014 the ordinal maps to `--reveal-stagger-step`, so a service retunes the cascade rhythm from one token.",
+      "DO pass `asChild` when wrapping an element that must keep its own box in a grid/flex row (the reveal merges onto that element instead of adding a <div>).",
+      "DO rely on the built-in reduced-motion behaviour \u2014 under `prefers-reduced-motion: reduce` the animation is dropped and content renders in its final, fully-visible position with no layout shift. Never gate visibility on the animation.",
+      "DO NOT set a raw ms delay or a literal translate distance \u2014 the whole point is that `delay` is a controlled ordinal and the distance/duration come from tokens."
+    ],
+    useCases: [
+      "Auth card entrance: `<AuthShell><Reveal><Card/></Reveal></AuthShell>` \u2014 the sign-in card fades up on load, respecting reduced-motion.",
+      "Staggered dashboard: map stat cards with `<Reveal delay={i + 1}>` so the row cascades in.",
+      "Section reveal on a settings/detail page \u2014 wrap each Card in <Reveal> for a calm entrance without hand-written CSS.",
+      "asChild on a grid item: `<Reveal asChild delay={2}><ResponsiveGrid.Item/></Reveal>` keeps the grid cell intact while animating it in."
+    ],
+    related: [
+      "AuthShell \u2014 pairs with Reveal for the auth card entrance; AuthShell delegates all motion to Reveal.",
+      "Card \u2014 the most common thing to wrap in <Reveal> (dashboard cards, auth card, settings sections).",
+      "ResponsiveGrid \u2014 combine with `<Reveal delay={n}>` (or `asChild`) per grid item for a staggered grid reveal."
+    ],
+    example: `import { Reveal } from "@godxjp/ui/general";
+import { Card, CardContent } from "@godxjp/ui/data-display";
+
+// single entrance
+<Reveal>
+  <Card><CardContent>\u2026</CardContent></Card>
+</Reveal>
+
+// staggered column
+{items.map((item, i) => (
+  <Reveal key={item.id} delay={Math.min(i + 1, 6) as 1 | 2 | 3 | 4 | 5 | 6}>
+    <Card><CardContent>{item.label}</CardContent></Card>
+  </Reveal>
+))}`,
+    storyPath: "general/Reveal.stories.tsx",
+    rules: []
+  },
   // ─── data-display ───────────────────────────────────────────────────────
   {
     name: "DataTable",
@@ -1498,15 +1676,29 @@ import { Smartphone } from "lucide-react";
       { name: "title", type: "string", required: true, description: "Primary empty message." },
       { name: "description", type: "string", description: "Secondary helper text." },
       { name: "icon", type: "LucideIcon", description: "Icon above the title." },
-      { name: "action", type: "ReactNode", description: "CTA element (e.g. a Button)." }
+      { name: "action", type: "ReactNode", description: "CTA element (e.g. a Button)." },
+      {
+        name: "variant",
+        type: '"page" | "section" | "compact"',
+        defaultValue: '"page"',
+        description: "Contextual visual weight. Compact omits the icon medallion."
+      },
+      {
+        name: "tone",
+        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."
+      }
     ],
     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 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 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."
     ],
     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.",
@@ -1531,20 +1723,26 @@ import { Smartphone } from "lucide-react";
   {
     name: "Progress",
     group: "data-display",
-    tagline: "Horizontal progress bar 0\u2013100 with optional label and semantic tone.",
+    tagline: "Horizontal progress bar 0\u2013100 with optional label, semantic tone, and an over-capacity (striped) state for over-limit meters.",
     props: [
       {
         name: "value",
         type: "number",
         required: true,
-        description: "Progress percentage 0\u2013100 (clamped)."
+        description: "Progress percentage 0\u2013100 (clamped unless `over`)."
       },
       { name: "label", type: "string", description: "Text label beside/below the bar." },
       {
         name: "tone",
-        type: '"success" | "warning"',
+        type: '"success" | "warning" | "destructive"',
         defaultValue: '"success"',
-        description: "Bar colour tone."
+        description: "Bar colour tone. Over-capacity defaults to destructive."
+      },
+      {
+        name: "over",
+        type: "boolean",
+        defaultValue: "false",
+        description: "Allow value > 100 to render an over-capacity fill: bar caps at 100% width but gets a diagonal hatch + destructive tone (e.g. 252%). aria-valuetext reports the real ratio. Off by default (clamps to 100)."
       }
     ],
     usage: [
@@ -1561,7 +1759,8 @@ import { Smartphone } from "lucide-react";
       "Storage or quota indicator in an admin panel \u2014 visualise disk usage, API quota, or seat licence consumption against a fixed limit.",
       "Sync / import job completion feedback \u2014 surface the completion percentage of a long-running background job (polling the server) without giving the user an interactive control.",
       "StatCard companion \u2014 pair with a `StatCard` metric to add a visual fill below the KPI number, reinforcing how close a target is to being met.",
-      "Multi-step onboarding or setup checklist \u2014 render one Progress per section (e.g. 3/5 steps complete = 60%) to give users a quick scan of overall progress across areas."
+      "Multi-step onboarding or setup checklist \u2014 render one Progress per section (e.g. 3/5 steps complete = 60%) to give users a quick scan of overall progress across areas.",
+      "Over-capacity meter \u2014 an air-cargo weight/volume load or an over-booked resource pushed past its limit (e.g. 252%): pass `over` with the real ratio to get a red diagonal-hatched bar that reads unmistakably as over-limit, not merely full."
     ],
     related: [
       "Slider \u2014 use Slider when the user must drag or set a bounded numeric value (volume, priority, price range); use Progress when the value is read-only and must not be interacted with.",
@@ -1572,7 +1771,8 @@ import { Smartphone } from "lucide-react";
     ],
     example: `import { Progress } from "@godxjp/ui/data-display";
 
-<Progress value={pct} label={pct + "% \u4F7F\u7528\u4E2D"} variant={pct >= 80 ? "warning" : "success"} />`,
+<Progress value={pct} label={pct + "% \u4F7F\u7528\u4E2D"} tone={pct >= 80 ? "warning" : "success"} />
+<Progress value={252} over label="252% \u7A4D\u8F09" />`,
     storyPath: "data-display/Progress.stories.tsx",
     rules: []
   },
@@ -1694,6 +1894,22 @@ import { Smartphone } from "lucide-react";
         description: "The useQuery result."
       },
       { name: "skeleton", type: "ReactNode", required: true, description: "Shown while loading." },
+      {
+        name: "prerequisite",
+        type: "ReactNode",
+        description: "Shown when the query is disabled/unstarted (pending + fetchStatus idle)."
+      },
+      {
+        name: "showRetry",
+        type: "boolean",
+        defaultValue: "false",
+        description: "Force Retry even for non-transient causes. Retry is offered automatically for transient/network/5xx errors regardless of this flag."
+      },
+      {
+        name: "onAuthError",
+        type: "() => void",
+        description: "Recovery for 401 / expired-token errors: renew the session or sign in again. A 401 renders this action instead of Retry."
+      },
       {
         name: "children",
         type: "(data) => ReactNode",
@@ -1709,7 +1925,8 @@ import { Smartphone } from "lucide-react";
       'DO: provide `empty` + `isEmpty` together when the data can legitimately return 0 items \u2014 e.g. `isEmpty={(d) => d.items.length === 0}` paired with `empty={<EmptyState title="\u2026" />}`. Omitting `empty` means an empty array still falls through to `children`, silently rendering a blank table.',
       "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: supply `errorRenderer` only when the default `AlertQueryError` + retry button is not enough \u2014 e.g. a full-page error boundary with navigation. Otherwise rely on `showRetry` (default `true`) and the built-in `AlertQueryError`, and override `onRetry` only if `query.refetch()` is not the right action."
+      "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."
     ],
     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.",
@@ -1730,7 +1947,12 @@ import { Smartphone } from "lucide-react";
   {(d) => <MemberTable items={d.items} />}
 </DataState>`,
     storyPath: "query/DataState.stories.tsx",
-    rules: []
+    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."
+    ]
   },
   {
     name: "InfiniteQueryState",
@@ -2281,6 +2503,11 @@ import { Smartphone } from "lucide-react";
         type: "string",
         description: "Message rendered while loadOptions is resolving."
       },
+      {
+        name: "errorMessage",
+        type: "string",
+        description: "Message rendered when an async loadOptions REJECTS \u2014 a distinct state from empty/loading. Defaults to a localized 'Couldn\u2019t load options'. The panel shows this instead of a blank surface or a misleading 'no results'."
+      },
       {
         name: "clearable",
         type: "boolean",
@@ -2325,6 +2552,7 @@ import { Smartphone } from "lucide-react";
       "DO pass name= on the data-driven Select so the value is submitted with a native form or Inertia useForm. Without name= the value is React-only and will not appear in form data.",
       "DO use loadOptions + selectedLabel together for async selects: selectedLabel prevents a flash of the raw id string while the first page loads.",
       "DO pair id= with a <label htmlFor={id}> for a11y. The trigger renders as a button; screen readers announce the label.",
+      "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."
@@ -2335,7 +2563,8 @@ import { Smartphone } from "lucide-react";
       "Account category picker backed by an API \u2014 pass loadOptions to stream pages of accounts as the user types; use renderOption to show account code + name side by side; pass selectedLabel so the trigger shows the name on first render.",
       "Grouped currency picker \u2014 set option.group='Asia' / 'Europe' on each option; the plain (non-search) data-driven mode renders SelectGroup headings automatically.",
       "Form field in an accounting entry \u2014 use the compound API when the trigger must show a currency flag icon alongside the SelectValue; wire SelectTrigger size='sm' for dense table rows.",
-      "Required department select in a HR form \u2014 pass clearable=false so the user cannot clear the field once set; pair with name='department_id' for Inertia useForm submission."
+      "Required department select in a HR form \u2014 pass clearable=false so the user cannot clear the field once set; pair with name='department_id' for Inertia useForm submission.",
+      "Async account picker whose API can fail \u2014 pass loadOptions plus errorMessage so a rejected fetch shows a clear error affordance in the panel (not a blank surface or a false 'no results'); the loading and empty states are handled automatically."
     ],
     related: [
       "SearchSelect \u2014 the combobox engine Select delegates to when showSearch=true or loadOptions is set. Prefer Select with showSearch instead of reaching for SearchSelect directly (SearchSelect is now deprecated as a public API).",
@@ -7016,6 +7245,11 @@ export default function PasswordBlock() {
         type: "(value: string) => void",
         description: "Controlled change handler. When omitted, calls the matching AppProvider setter (setLocale/setTimezone/setDateFormat/setTimeFormat). Required together with value when no AppProvider is present."
       },
+      {
+        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.`
+      },
       {
         name: "className",
         type: "string",
@@ -7033,10 +7267,12 @@ export default function PasswordBlock() {
       "DO: Use controlled mode (value + onValueChange) when managing state outside AppProvider, e.g. a standalone settings form or a Storybook story. Both are required together in this mode.",
       "DO NOT: Render without AppProvider and without both controlled props \u2014 it throws 'AppSettingPicker requires <AppProvider> or controlled value + onValueChange'.",
       "DO: Render four instances with different kind values to build a full preferences panel; they all share the same AppProvider context and stay in sync.",
+      'DO: For an icon-only topbar utility (a globe language switcher), pass appearance="icon" \u2014 the supported compact trigger. NEVER hand-roll it by hiding the value/width with descendant-selector CSS.',
       "DON'T hand-roll a locale/timezone/format Select \u2014 AppSettingPicker already composes Select + the right icon + translated, context-wired options. There is no separate LocalePicker/TimezonePicker/DateFormatPicker/TimeFormatPicker anymore; use kind."
     ],
     useCases: [
       'App-shell top-nav language switcher: <AppSettingPicker kind="locale" /> under AppProvider, persisting to localStorage with no extra state.',
+      'Icon-only topbar locale switcher (globe): <AppSettingPicker kind="locale" appearance="icon" /> in a Topbar `end` slot \u2014 square, value-less, keyboard + aria-label preserved.',
       "User settings page with all four preferences \u2014 render kind=locale, kind=timezone, kind=dateFormat, kind=timeFormat together under one AppProvider.",
       "Onboarding step that picks language/timezone before the rest of the app is configured \u2014 AppProvider persist={false} + controlled values to keep state local.",
       'Storybook/test harness without AppProvider \u2014 fully controlled: <AppSettingPicker kind="timeFormat" value="24h" onValueChange={fn} />.'
@@ -7068,6 +7304,14 @@ import { AppSettingPicker } from "@godxjp/ui/navigation";
 export function LocaleField() {
   const [locale, setLocale] = useState("en");
   return <AppSettingPicker kind="locale" value={locale} onValueChange={setLocale} />;
+}
+
+// Icon-only topbar locale switcher (globe) \u2014 supported compact trigger, no CSS overrides
+import { Topbar } from "@godxjp/ui/layout";
+import { AppSettingPicker } from "@godxjp/ui/navigation";
+
+export function TopbarLocale() {
+  return <Topbar end={<AppSettingPicker kind="locale" appearance="icon" />} />;
 }\`}`,
     storyPath: "navigation/AppSettingPicker.stories.tsx",
     rules: [3, 5, 6, 23]
@@ -7633,6 +7877,18 @@ var TOKENS = [
     tier: "primitive",
     role: "Raw typography scale."
   },
+  {
+    name: "--font-sans-base",
+    category: "semantic",
+    tier: "semantic",
+    role: "The default sans face. FONT-AGNOSTIC by default (pure system stack) \u2014 the library ships no hardcoded brand font. Override this for one face everywhere. --font-family-sans defaults to it; --font-family-display / --font-family-body default to --font-family-sans (override those for a dual display+body brand). Consumers supply the actual @font-face (next/font, @fontsource, self-host); the opt-in @godxjp/ui/styles/fonts fills this with the bundled Noto Sans JP."
+  },
+  {
+    name: "--font-sans-{ja,ko,vi,zh-hans,zh-hant}",
+    category: "semantic",
+    tier: "semantic",
+    role: "Per-language font SLOT tokens. styles/base.css wires each [lang] to read its slot with --font-sans-base as fallback, so a consumer switches a locale's face by setting e.g. `--font-sans-ja: \"Noto Sans JP\", var(--font-sans-base)` \u2014 NO [lang] selectors to write. Empty by default. zh-hans matches lang zh|zh-Hans|zh-CN; zh-hant matches zh-Hant|zh-TW. Deciding which @font-face ships on which locale route is the consumer's font pipeline, not the library."
+  },
   {
     name: "--duration-{fast,base,slow}",
     category: "primitive",
@@ -7651,6 +7907,12 @@ var TOKENS = [
     tier: "primitive",
     role: "Distance (10px) a revealed element travels on enter (translateY/-X). Read instead of a literal `translateY(10px)` for staggered reveals."
   },
+  {
+    name: "--reveal-stagger-step",
+    category: "primitive",
+    tier: "primitive",
+    role: "One step (60ms) of the Reveal stagger ladder \u2014 `<Reveal delay={n}>` waits n \xD7 this before entering, so a column of reveals cascades. Read instead of a literal `.04s`/`.09s` per-item delay."
+  },
   {
     name: "--shadow-color",
     category: "primitive",
@@ -8424,6 +8686,26 @@ var COMPONENT_TOKENS = [
     "value": "var(--space-6)",
     "description": "Brand glow layer for the raised dialog/sheet panel \u2014 invisible no-op at rest (rule #44). * Paired AFTER --shadow-lg in the surface box-shadow so a service can wash the overlay with the * global glow, e.g. --dialog-content-glow: var(--shadow-glow), with no markup change."
   },
+  {
+    "name": "--empty-state-section-space-y",
+    "value": "var(--space-6)",
+    "description": "Brand glow layer for the raised dialog/sheet panel \u2014 invisible no-op at rest (rule #44). * Paired AFTER --shadow-lg in the surface box-shadow so a service can wash the overlay with the * global glow, e.g. --dialog-content-glow: var(--shadow-glow), with no markup change."
+  },
+  {
+    "name": "--empty-state-section-space-x",
+    "value": "var(--space-4)",
+    "description": "Brand glow layer for the raised dialog/sheet panel \u2014 invisible no-op at rest (rule #44). * Paired AFTER --shadow-lg in the surface box-shadow so a service can wash the overlay with the * global glow, e.g. --dialog-content-glow: var(--shadow-glow), with no markup change."
+  },
+  {
+    "name": "--empty-state-compact-space-y",
+    "value": "var(--space-3)",
+    "description": "Brand glow layer for the raised dialog/sheet panel \u2014 invisible no-op at rest (rule #44). * Paired AFTER --shadow-lg in the surface box-shadow so a service can wash the overlay with the * global glow, e.g. --dialog-content-glow: var(--shadow-glow), with no markup change."
+  },
+  {
+    "name": "--empty-state-compact-space-x",
+    "value": "var(--space-2)",
+    "description": "Brand glow layer for the raised dialog/sheet panel \u2014 invisible no-op at rest (rule #44). * Paired AFTER --shadow-lg in the surface box-shadow so a service can wash the overlay with the * global glow, e.g. --dialog-content-glow: var(--shadow-glow), with no markup change."
+  },
   {
     "name": "--empty-state-icon-foreground",
     "value": "initial",
@@ -8489,6 +8771,51 @@ var COMPONENT_TOKENS = [
     "value": "initial",
     "description": "Row divider \u2014 `initial` so the --border default re-resolves at the call site under a scoped * theme (a :root binding to a role var freezes at :root). Default = 1px solid hsl(var(--border))."
   },
+  {
+    "name": "--logo-radius",
+    "value": "var(--radius)",
+    "description": "Logo component tokens \u2014 the product brand-mark box (a glyph on the primary fill), used in the * app shell header, auth screens, and topbars. Size + radius + per-tier font-size are knobs so a * service theme retunes the mark without forking CSS (rules #44/#45). Colours read the primary * role tokens directly, so a re-themed --primary re-tints the mark automatically."
+  },
+  {
+    "name": "--logo-size-xs",
+    "value": "1.25rem",
+    "description": "Logo component tokens \u2014 the product brand-mark box (a glyph on the primary fill), used in the * app shell header, auth screens, and topbars. Size + radius + per-tier font-size are knobs so a * service theme retunes the mark without forking CSS (rules #44/#45). Colours read the primary * role tokens directly, so a re-themed --primary re-tints the mark automatically."
+  },
+  {
+    "name": "--logo-size-sm",
+    "value": "1.5rem",
+    "description": "Logo component tokens \u2014 the product brand-mark box (a glyph on the primary fill), used in the * app shell header, auth screens, and topbars. Size + radius + per-tier font-size are knobs so a * service theme retunes the mark without forking CSS (rules #44/#45). Colours read the primary * role tokens directly, so a re-themed --primary re-tints the mark automatically."
+  },
+  {
+    "name": "--logo-size-md",
+    "value": "1.75rem",
+    "description": "Logo component tokens \u2014 the product brand-mark box (a glyph on the primary fill), used in the * app shell header, auth screens, and topbars. Size + radius + per-tier font-size are knobs so a * service theme retunes the mark without forking CSS (rules #44/#45). Colours read the primary * role tokens directly, so a re-themed --primary re-tints the mark automatically."
+  },
+  {
+    "name": "--logo-size-lg",
+    "value": "2.25rem",
+    "description": "Logo component tokens \u2014 the product brand-mark box (a glyph on the primary fill), used in the * app shell header, auth screens, and topbars. Size + radius + per-tier font-size are knobs so a * service theme retunes the mark without forking CSS (rules #44/#45). Colours read the primary * role tokens directly, so a re-themed --primary re-tints the mark automatically."
+  },
+  {
+    "name": "--logo-font-size-xs",
+    "value": "var(--font-size-2xs)",
+    "description": "Logo component tokens \u2014 the product brand-mark box (a glyph on the primary fill), used in the * app shell header, auth screens, and topbars. Size + radius + per-tier font-size are knobs so a * service theme retunes the mark without forking CSS (rules #44/#45). Colours read the primary * role tokens directly, so a re-themed --primary re-tints the mark automatically."
+  },
+  {
+    "name": "--logo-font-size-sm",
+    "value": "var(--font-size-xs)",
+    "description": "Logo component tokens \u2014 the product brand-mark box (a glyph on the primary fill), used in the * app shell header, auth screens, and topbars. Size + radius + per-tier font-size are knobs so a * service theme retunes the mark without forking CSS (rules #44/#45). Colours read the primary * role tokens directly, so a re-themed --primary re-tints the mark automatically."
+  },
+  {
+    "name": "--logo-font-size-md",
+    "value": "var(--font-size-sm)",
+    "description": "Logo component tokens \u2014 the product brand-mark box (a glyph on the primary fill), used in the * app shell header, auth screens, and topbars. Size + radius + per-tier font-size are knobs so a * service theme retunes the mark without forking CSS (rules #44/#45). Colours read the primary * role tokens directly, so a re-themed --primary re-tints the mark automatically."
+  },
+  {
+    "name": "--logo-font-size-lg",
+    "value": "var(--font-size-base)",
+    "description": "Logo component tokens \u2014 the product brand-mark box (a glyph on the primary fill), used in the * app shell header, auth screens, and topbars. Size + radius + per-tier font-size are knobs so a * service theme retunes the mark without forking CSS (rules #44/#45). Colours read the primary * role tokens directly, so a re-themed --primary re-tints the mark automatically."
+  },
   {
     "name": "--pagination-gap",
     "value": "var(--space-inline-sm)",
@@ -8639,6 +8966,36 @@ var COMPONENT_TOKENS = [
     "value": "initial",
     "description": "Main nav-item active row \u2014 defaults mirror the hover state (accent bg, foreground text); a * service overrides these to brand the selected row (e.g. a gold tint + gold text on a navy * sidebar). `initial` so the defaults re-resolve under a scoped theme. * Defaults = hsl(var(--accent)) fill \xB7 hsl(var(--foreground)) text."
   },
+  {
+    "name": "--auth-shell-control-height",
+    "value": "var(--control-height-comfortable)",
+    "description": "AuthShell \u2014 centred auth/login page shell. Comfortable control density (44px, WCAG touch floor) * + a larger auth heading, scoped to the shell; a service re-tunes the auth card width, insets * and heading size without forking."
+  },
+  {
+    "name": "--auth-shell-heading-size",
+    "value": "var(--font-size-2xl)",
+    "description": "AuthShell \u2014 centred auth/login page shell. Comfortable control density (44px, WCAG touch floor) * + a larger auth heading, scoped to the shell; a service re-tunes the auth card width, insets * and heading size without forking."
+  },
+  {
+    "name": "--auth-shell-card-max-width",
+    "value": "24rem",
+    "description": "AuthShell \u2014 centred auth/login page shell. Comfortable control density (44px, WCAG touch floor) * + a larger auth heading, scoped to the shell; a service re-tunes the auth card width, insets * and heading size without forking."
+  },
+  {
+    "name": "--auth-shell-bar-padding",
+    "value": "var(--space-5) var(--space-6)",
+    "description": "AuthShell \u2014 centred auth/login page shell. Comfortable control density (44px, WCAG touch floor) * + a larger auth heading, scoped to the shell; a service re-tunes the auth card width, insets * and heading size without forking."
+  },
+  {
+    "name": "--auth-shell-main-padding",
+    "value": "var(--space-6)",
+    "description": "AuthShell \u2014 centred auth/login page shell. Comfortable control density (44px, WCAG touch floor) * + a larger auth heading, scoped to the shell; a service re-tunes the auth card width, insets * and heading size without forking."
+  },
+  {
+    "name": "--auth-shell-footer-padding",
+    "value": "var(--space-3) var(--space-6) var(--space-4)",
+    "description": "AuthShell \u2014 centred auth/login page shell. Comfortable control density (44px, WCAG touch floor) * + a larger auth heading, scoped to the shell; a service re-tunes the auth card width, insets * and heading size without forking."
+  },
   {
     "name": "--table-row-height-compact",
     "value": "1.75rem",
@@ -9070,48 +9427,33 @@ export function SignUpCard() {
 }`
   },
   {
-    name: "settings-tabs",
-    tagline: "Sectioned settings inside a Card with Tabs + FormField + Select + Switch (real @godxjp/ui API).",
+    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: `import { Card, CardContent } from "@godxjp/ui/data-display";
-import { Tabs, TabsList, TabsTrigger, TabsContent } from "@godxjp/ui/navigation";
-import { FormField, Input, Select, SelectTrigger, SelectValue, SelectContent, SelectItem, Switch, Label } from "@godxjp/ui/data-entry";
-import { Stack } from "@godxjp/ui/layout";
+    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";
+import { FormField, Input } from "@godxjp/ui/data-entry";
 
 export function WorkspaceSettings() {
   return (
-    <Card>
-      <CardContent>
-        <Tabs defaultValue="general">
-          <TabsList>
-            <TabsTrigger value="general">\u57FA\u672C\u60C5\u5831</TabsTrigger>
-            <TabsTrigger value="notify">\u901A\u77E5</TabsTrigger>
-          </TabsList>
-          <TabsContent value="general">
-            <Stack gap="md">
-              <FormField id="ws-name" label="\u540D\u524D" required><Input id="ws-name" /></FormField>
-              <FormField id="visibility" label="\u516C\u958B\u7BC4\u56F2">
-                <Select defaultValue="internal">
-                  <SelectTrigger><SelectValue /></SelectTrigger>
-                  <SelectContent>
-                    <SelectItem value="private">\u30D7\u30E9\u30A4\u30D9\u30FC\u30C8</SelectItem>
-                    <SelectItem value="internal">\u793E\u5185\u516C\u958B</SelectItem>
-                    <SelectItem value="public">\u516C\u958B</SelectItem>
-                  </SelectContent>
-                </Select>
-              </FormField>
-            </Stack>
-          </TabsContent>
-          <TabsContent value="notify">
-            <div className="flex items-center gap-2">
-              <Switch id="notify-comment" defaultChecked />
-              <Label htmlFor="notify-comment">\u30B3\u30E1\u30F3\u30C8\u901A\u77E5\u3092\u53D7\u3051\u53D6\u308B</Label>
-            </div>
-          </TabsContent>
-        </Tabs>
-      </CardContent>
-    </Card>
+    <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>
+      </nav>
+      <main className="settings-content"><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>;
 }`
   },
   {
@@ -9377,6 +9719,63 @@ const seeded = (n: number) => { const x = Math.sin((n + 1) * 99.71) * 1e4; retur
 // 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.`
+  },
+  {
+    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.`
+  },
+  {
+    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} />}`
+  },
+  {
+    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.`
   }
 ];
 function findPattern(name) {
@@ -10403,6 +10802,130 @@ npm-pack TARBALL install, not a file: symlink (the symlink's nested node_modules
 dual-React artifact under vitest).`
       }
     ]
+  },
+  // ── design-complex-admin (consumer) ────────────────────────────
+  {
+    id: "design-complex-admin",
+    audience: "consumer",
+    name: "Design a complex admin console \u2014 wireframe-first, layered IA",
+    whenToUse: "You are building or redesigning a COMPLEX multi-layer admin/console/back-office UI (platform admin, workspace admin, multi-tenant management, control panel) \u2014 the kind that spans several administrative tiers (Platform \u2192 Org/Tenant \u2192 Brand \u2192 Org-unit \u2192 Shop \u2192 Staff), not one flat resource list. Read this BEFORE writing JSX: it forces the right order \u2014 lock the entity model \u2192 study exemplars \u2192 design a LAYERED information architecture \u2192 wireframe (as an Artifact) \u2192 validate \u2192 only THEN code. Stops the flat-console anti-pattern (every resource in one list, create-form + list + detail crammed on one screen, no dashboards). For a single ordinary screen use compose-a-screen; for a design handoff bundle use design-to-page.",
+    source: "@godxjp/ui .claude/skills/design-complex-admin/SKILL.md \u2014 the multi-tenant admin-console redesign process (entity-tree concept \u2192 layered wireframe \u2192 code)",
+    sections: [
+      {
+        id: "entity-model-first",
+        title: "Step 0 \u2014 Lock the entity model before you draw a pixel",
+        tagline: "Enumerate entities, cardinality, boundaries, and what does NOT exist; get it confirmed first.",
+        body: `Do NOT open an editor at a flat "here are the resources" list. First produce a
+CONCEPT artifact (a tree of entities + a glossary + the rules) and get it confirmed:
+- every entity + its cardinality (1-N / N-N) + its boundary (tenant / RLS / subscription scope);
+- the identity split matters \u2014 Principal/User (can log in, carries authz) \u2260 Employee/Staff
+  (a domain record that may never log in); never fuse them in the IA;
+- explicitly list what is OUT OF SCOPE / does NOT exist, so the console doesn't invent tiers.
+Worked example (a multi-tenant admin console): Org = Tenant = \u6CD5\u4EBA \xB7 Brand \xB7 Org-unit (branch) \xB7 Shop = Branch \xB7
+Staff \xB7 Principal = User. No code until this tree is agreed \u2014 a wrong entity model is a wrong
+console, and it is far cheaper to fix here than in built screens.
+\u{1F534} Entity-category colour is NON-SEMANTIC: never use red/amber/orange to distinguish a category
+(reads as error/warning/danger). Reserve red strictly for a real \`danger\` action. Differentiate
+tiers/categories with cool hues (sky/teal/indigo/violet) + a LABEL \u2014 never colour alone
+(colour-only meaning also fails WCAG).`
+      },
+      {
+        id: "study-exemplars",
+        title: "Step 1 \u2014 Study the best-in-class consoles for this domain",
+        tagline: "Borrow proven IA from Auth0/WorkOS/Stripe/Cloudflare/Vercel/Supabase/Clerk.",
+        body: `Before inventing structure, learn the information architecture of the strongest
+consoles in the same shape (identity/back-office/multi-tenant): Auth0, WorkOS, Stripe Connect,
+Cloudflare, Vercel, Supabase, Clerk \u2014 pick the closest to your domain. Extract the RECURRING
+patterns they all converge on and plan to reuse them:
+- a top scope switcher (change tenant/org/project) that re-scopes the whole shell;
+- a per-scope sidebar (nav that changes with the active scope);
+- breadcrumb trails + a \u2318K command palette for deep navigation;
+- a "needs attention" surface (what's broken / pending right now) on the landing dashboard;
+- first-run / empty / onboarding states, not just the happy populated view.
+These aren't decoration \u2014 they are the skeleton the layered IA hangs on.`
+      },
+      {
+        id: "layered-ia",
+        title: "Step 2 \u2014 Layered information architecture (never flat)",
+        tagline: "Map each surface to an administrative TIER; every tier gets dashboard + list + detail as SEPARATE routes.",
+        body: `Reject the flat console (every resource dumped into one list). Map each admin surface
+onto an administrative TIER of the domain (Platform \u2192 Org/Tenant \u2192 Brand \u2192 Org-unit \u2192 Shop \u2192 Staff)
+so the navigation mirrors how the business is actually administered.
+Each tier gets its OWN route set, and CRUD is split across routes \u2014 never one mega-screen:
+- an overview DASHBOARD (summary of that tier: counts, health, needs-attention);
+- a LIST route (browse/search the tier's entities);
+- a DETAIL route per entity (read + its sub-resources);
+- CREATE / EDIT as their own route or a focused Dialog/Sheet \u2014 NOT inlined beside the list.
+\u{1F534} The single worst anti-pattern this skill exists to kill: create-form + list + detail crammed
+onto one screen. If you can't name the tier a screen belongs to, the IA isn't finished.`
+      },
+      {
+        id: "scope-and-chrome",
+        title: "Step 3 \u2014 Scope model + shell chrome (real @godxjp/ui primitives)",
+        tagline: "AppShell + Sidebar + Topbar slots + Breadcrumb; summary before detail; encode attention visually.",
+        body: `Build the shell from REAL primitives (MCP-first \u2014 get_component before you wire a
+prop), never hand-rolled nav:
+- \`AppShell\` composes the frame; \`Sidebar\` is the DATA-DRIVEN nav rail (pass its items, never
+  build nav from raw buttons) and it SWaps with the active scope; \`Topbar\` is a pure slot bar \u2014
+  drop the scope switcher into a slot (compose it from \`Select\`/\`DropdownMenu\`; use
+  \`AppSettingPicker\` for locale/theme/density axes), the shell bakes no chrome itself.
+- \`Breadcrumb\` for the trail; a \u2318K command palette is a COMPOSITION (\`Dialog\` + \`Input\` +
+  a results list / \`DropdownMenu\`) \u2014 there is no Command primitive, so build it from these or,
+  if you want a first-class one, file it via draft_bug_report rather than faking it.
+- Landing = a DASHBOARD: summary BEFORE detail \u2014 a few \`StatCard\` KPIs in a \`ResponsiveGrid\`
+  (StatCard is already bordered \u2014 never wrap it in Card) + ONE primary list, not an 8-card wall.
+- Encode "needs attention" VISUALLY (a \`Badge\` with \`status\`, a StatCard \`accent\` rail, a
+  \`Progress\` tone) \u2014 never a bare number the eye can't triage. Status uses the FIXED semantic
+  mapping; never recolour a category hue into a role.`
+      },
+      {
+        id: "wireframe-first",
+        title: "Step 4 \u2014 Wireframe FIRST (as an Artifact), then validate",
+        tagline: "Low-fi but REAL content, theme-aware, token-driven; stakeholder approves before code.",
+        body: `Produce a low-fidelity WIREFRAME as an Artifact and get it approved BEFORE writing
+components \u2014 fixing structure in a wireframe is far cheaper than in built screens. The wireframe must:
+- use REAL content, never lorem \u2014 real tier names, real entity fields, real empty/attention copy;
+- be theme-aware (light + dark) and token-driven (semantic tokens, not raw hex) so it maps 1:1 to
+  the eventual @godxjp/ui build;
+- cover the whole IA: the nav/scope model, the tier palette, EACH tier's dashboard/list/detail,
+  plus before/after and do/don't panels so reviewers see the reasoning.
+Only after sign-off do you move to code. A wireframe skipped = a redesign relitigated in code.`
+      },
+      {
+        id: "validate-then-build",
+        title: "Steps 5\u20136 \u2014 Validate against godx-ui, THEN build route-by-route",
+        tagline: "Run cardinal rules / patterns / anti-AI-tells; then each page = its own route from real primitives; hand off.",
+        body: `Validate the wireframe against the system before building: cross-check the cardinal
+rules + canonical patterns (get_rule / list_patterns / get_pattern), run the ui-audit / visual-audit
+lens, and scan for anti-AI tells (list_anti_ai_tells) \u2014 flat 8-stat walls, rainbow tag walls,
+category-as-error colour, placeholder-as-label.
+Then BUILD, one route at a time \u2014 and hand off the per-screen craft to the screen skills rather
+than re-deriving it here:
+- each page is its OWN route (dashboard / list / detail / create split, per Step 2);
+- every block is a real @godxjp/ui primitive \u2014 no hand-rolled UI, no raw <input>/<select>/<table>;
+- a tier list = \`PageContainer\` + \`Card\` + \`CardContent\` flush + \`DataTable\`; detail =
+  \`Descriptions\` + \`StatCard\`; empty = \`EmptyState\`;
+- ui-audit clean (0/0 semantic tokens), tests \u226595%.
+HAND-OFF: use compose-a-screen (build a screen from a brief) or design-to-page (from a handoff
+bundle) for each individual screen; if a needed block has no primitive, use design-to-page's
+gaps-extend-or-ask + report-bug \u2014 never fake it.`
+      },
+      {
+        id: "anti-patterns",
+        title: "Anti-patterns this skill must block + the per-run outputs",
+        tagline: "The six failures to reject on sight, and the four artifacts every run produces.",
+        body: `Reject on sight (each is a FINDING, stop and fix):
+1. Code written before an agreed entity model AND an approved wireframe exist.
+2. A FLAT IA \u2014 every resource in one list, no administrative tiers.
+3. create-form + list + detail crammed onto one screen (CRUD not split into routes).
+4. A tier with no dashboard/summary \u2014 detail with nothing to orient it.
+5. Category/tier coloured with red/amber/orange (reads as error/warning) \u2014 use cool hues + labels.
+6. Hand-rolled UI instead of @godxjp/ui primitives (raw nav buttons, styled-div "Card", raw table).
+Every run of this skill produces, in order: (1) a stakeholder-confirmed concept/entity artifact \u2192
+(2) a layered IA doc \u2192 (3) an approved wireframe Artifact \u2192 (4) a per-route implementation checklist.
+Do not advance a step until the prior artifact is signed off.`
+      }
+    ]
   }
 ];
 function findSkill(id) {
@@ -10575,7 +11098,37 @@ function routeTask(task, opts) {
     "app-performance",
     "measure-first",
     "Measure FIRST (longtask + temporary Profiler), then apply the matching proven fix \u2014 page architecture, not the library, is almost always the culprit.",
-    ["app-performance/filter-pane-memo", "app-performance/heavy-panels", "app-performance/bundle-budget"]
+    [
+      "app-performance/filter-pane-memo",
+      "app-performance/heavy-panels",
+      "app-performance/bundle-budget"
+    ]
+  );
+  route(
+    [
+      "admin console",
+      "admin panel",
+      "control panel",
+      "back-office",
+      "back office",
+      "management console",
+      "management ui",
+      "multi-tenant",
+      "multi tenant",
+      "platform admin",
+      "workspace admin",
+      "console qu\u1EA3n tr\u1ECB",
+      "layered ia",
+      "information architecture"
+    ],
+    "design-complex-admin",
+    "entity-model-first",
+    "A complex multi-tier admin console: lock the entity model \u2192 study exemplars \u2192 design a LAYERED IA \u2192 wireframe (Artifact) \u2192 validate \u2192 build route-by-route. Kills the flat-console anti-pattern.",
+    [
+      "design-complex-admin/layered-ia",
+      "design-complex-admin/wireframe-first",
+      "compose-a-screen/pick-primitives"
+    ]
   );
   const filtered = opts?.consumerOnly ? matches.filter((m) => {
     const sk = findSkill(m.skill);
@@ -11465,7 +12018,7 @@ function auditRulesByCategory(category) {
 }
 
 // src/data/visual-rules.ts
-var VISUAL_AUDIT_COMMAND = "node node_modules/@godxjp/ui/scripts/visual-audit.mjs <baseUrl> [route \u2026]  (needs optional peers: playwright + @axe-core/playwright + a chromium; --strict for a CI gate, --format json, --rules to print this catalog)";
+var VISUAL_AUDIT_COMMAND = "node node_modules/@godxjp/ui/scripts/visual-audit.mjs <baseUrl> [route \u2026]  (optional peers, TESTED range: playwright >=1.55 <2 [1.61.1] + @axe-core/playwright >=4.10 <5 [4.12.1] + axe-core >=4.10 <5 [4.12.1] + a chromium via `playwright install chromium`; --strict for a CI gate, --format json ALWAYS emits valid JSON with a status of ok|partial|error separating infra errors[] from product findings[], --rules to print this catalog)";
 var VISUAL_RULES = [
   {
     id: "axe-violations",
@@ -11507,6 +12060,65 @@ function visualRulesByCategory(category) {
   return category ? VISUAL_RULES.filter((r) => r.category === category) : VISUAL_RULES;
 }
 
+// package.json
+var package_default = {
+  name: "@godxjp/ui-mcp",
+  version: "17.0.0",
+  godxUiCompatibility: "17.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",
+  module: "./dist/index.js",
+  types: "./dist/index.d.ts",
+  bin: {
+    "godx-ui-mcp": "./dist/index.js"
+  },
+  files: [
+    "dist",
+    "README.md"
+  ],
+  publishConfig: {
+    registry: "https://registry.npmjs.org/",
+    access: "public"
+  },
+  repository: {
+    type: "git",
+    url: "git+https://github.com/godx-jp/godxjp-ui.git",
+    directory: "mcp"
+  },
+  homepage: "https://github.com/godx-jp/godxjp-ui/tree/main/mcp#readme",
+  license: "Apache-2.0",
+  scripts: {
+    build: "tsup",
+    dev: "tsup --watch",
+    start: "node dist/index.js",
+    inspect: "npx @modelcontextprotocol/inspector node dist/index.js",
+    "type-check": "tsc --noEmit",
+    test: "vitest run",
+    prepublishOnly: "npm run build"
+  },
+  dependencies: {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    zod: "^4.4.3"
+  },
+  devDependencies: {
+    "@types/node": "^22.10.0",
+    tsup: "^8.5.1",
+    typescript: "^6.0.3",
+    vitest: "^4.1.6"
+  },
+  keywords: [
+    "mcp",
+    "model-context-protocol",
+    "godxjp",
+    "ui",
+    "design-system",
+    "react",
+    "claude",
+    "cursor"
+  ]
+};
+
 // src/tools/registry.ts
 var TOOL_DEFINITIONS = [
   // ── DISCOVERY (small responses) ────────────────────────────────
@@ -11745,6 +12357,19 @@ var TOOL_DEFINITIONS = [
       required: ["summary"]
     }
   },
+  {
+    name: "check_compatibility",
+    description: "Report whether the @godxjp/ui version installed in the target project matches THIS catalog. This MCP describes exactly one release train (see the `godx-ui://compatibility` resource); if the consumer runs a different @godxjp/ui minor, the props / tokens / patterns it returns may describe a build they never installed (issue #140). Pass the installed version (from the app's `node_modules/@godxjp/ui/package.json` or `npm ls @godxjp/ui`) to get an actionable match / mismatch verdict. Call it at the START of a consumer session before trusting catalog output.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        version: {
+          type: "string",
+          description: "Installed @godxjp/ui version in the target project, e.g. '16.10.0'. Omit to just read the catalog's own version + compatible range."
+        }
+      }
+    }
+  },
   // ── TASK ROUTING (smallest response — pointer) ─────────────────
   {
     name: "route_task",
@@ -11827,6 +12452,8 @@ async function dispatchTool(name, args) {
       return routeTaskTool(String(args.task ?? ""), { consumerOnly: true });
     case "draft_bug_report":
       return draftBugReport(args);
+    case "check_compatibility":
+      return checkCompatibility(args.version == null ? void 0 : String(args.version));
     // Task routing
     case "route_task":
       return routeTaskTool(String(args.task ?? ""));
@@ -11983,6 +12610,43 @@ ${cmd}
 `;
   return out;
 }
+function checkCompatibility(installed) {
+  const catalog = package_default.version;
+  const range = package_default.godxUiCompatibility;
+  const header = `# @godxjp/ui compatibility
+
+- MCP / catalog version (serverInfo.version): **${catalog}**
+- Compatible @godxjp/ui range: **${range ?? "(unset)"}**
+`;
+  const v = installed?.trim();
+  if (!v) {
+    return header + `
+Provide the installed version \u2014 \`check_compatibility version="16.10.0"\` \u2014 to get a match/mismatch verdict. Read it from the target project's \`node_modules/@godxjp/ui/package.json\` or \`npm ls @godxjp/ui\`.
+`;
+  }
+  const parse = (s) => {
+    const m = /^(\d+)\.(\d+)\.(\d+)/.exec(s);
+    return m ? { major: m[1], minor: m[2] } : null;
+  };
+  const rangeMinor = range ? /^(\d+)\.(\d+)\.x$/.exec(range) : null;
+  const iv = parse(v);
+  if (!iv || range && !rangeMinor) {
+    return header + `
+\u26A0\uFE0F Could not compare \u2014 installed="${v}" is not a plain x.y.z version, or the catalog range is malformed. Verify with \`npm ls @godxjp/ui\`.
+`;
+  }
+  const matches = rangeMinor ? iv.major === rangeMinor[1] && iv.minor === rangeMinor[2] : v === catalog;
+  if (matches) {
+    return header + `
+\u2705 In lockstep \u2014 installed @godxjp/ui@${v} is described by this catalog. Prop / token / pattern guidance is safe to trust.
+`;
+  }
+  return header + `
+\u{1F534} MISMATCH \u2014 the target project runs @godxjp/ui@${v}, but this catalog describes ${range ?? catalog}. Props, defaults, tokens, and patterns it returns may not match the installed build. Align them before trusting output:
+- upgrade the app: \`npm i @godxjp/ui@${catalog}\`, or
+- point your agent at the matching MCP release: \`@godxjp/ui-mcp@${iv.major}.${iv.minor}\` (same minor as the app).
+`;
+}
 function listPrimitives(group) {
   const list = group ? componentsByGroup(group) : COMPONENTS;
   if (list.length === 0) return `No components${group ? ` in group "${group}"` : ""}.`;
@@ -12633,6 +13297,12 @@ Note: heuristic only \u2014 not a substitute for the full CI gate.
 // src/resources/registry.ts
 var RULE_COUNT = CARDINAL_RULES.length;
 var RESOURCE_DEFINITIONS = [
+  {
+    uri: "godx-ui://compatibility",
+    name: "Package compatibility",
+    description: "MCP package/server version and the compatible @godxjp/ui release range.",
+    mimeType: "application/json"
+  },
   {
     uri: "godx-ui://components",
     name: "All components",
@@ -12665,6 +13335,18 @@ var RESOURCE_DEFINITIONS = [
   }
 ];
 async function readResource(uri) {
+  if (uri === "godx-ui://compatibility") {
+    return JSON.stringify(
+      {
+        mcpVersion: package_default.version,
+        serverVersion: package_default.version,
+        compatibleUi: package_default.godxUiCompatibility,
+        policy: "UI and MCP are released from the same source commit and minor release train."
+      },
+      null,
+      2
+    );
+  }
   if (uri === "godx-ui://components") {
     return JSON.stringify(COMPONENTS, null, 2);
   }
@@ -12758,64 +13440,6 @@ ${c.example}
   return out;
 }
 
-// package.json
-var package_default = {
-  name: "@godxjp/ui-mcp",
-  version: "16.7.2",
-  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",
-  module: "./dist/index.js",
-  types: "./dist/index.d.ts",
-  bin: {
-    "godx-ui-mcp": "./dist/index.js"
-  },
-  files: [
-    "dist",
-    "README.md"
-  ],
-  publishConfig: {
-    registry: "https://registry.npmjs.org/",
-    access: "public"
-  },
-  repository: {
-    type: "git",
-    url: "git+https://github.com/godx-jp/godxjp-ui.git",
-    directory: "mcp"
-  },
-  homepage: "https://github.com/godx-jp/godxjp-ui/tree/main/mcp#readme",
-  license: "Apache-2.0",
-  scripts: {
-    build: "tsup",
-    dev: "tsup --watch",
-    start: "node dist/index.js",
-    inspect: "npx @modelcontextprotocol/inspector node dist/index.js",
-    "type-check": "tsc --noEmit",
-    test: "vitest run",
-    prepublishOnly: "npm run build"
-  },
-  dependencies: {
-    "@modelcontextprotocol/sdk": "^1.29.0",
-    zod: "^4.4.3"
-  },
-  devDependencies: {
-    "@types/node": "^22.10.0",
-    tsup: "^8.5.1",
-    typescript: "^6.0.3",
-    vitest: "^4.1.6"
-  },
-  keywords: [
-    "mcp",
-    "model-context-protocol",
-    "godxjp",
-    "ui",
-    "design-system",
-    "react",
-    "claude",
-    "cursor"
-  ]
-};
-
 // src/index.ts
 async function main() {
   const server = new Server(