@godxjp/ui 28.9.0 → 28.12.0

package/agent/components/Attachments.json

@@ -0,0 +1,77 @@
+{
+  "docPath": "data-entry/attachments.tsx",
+  "example": "import { Attachments } from \"@godxjp/ui/data-entry\";\n\n<Attachments\n  items={files}\n  onChange={({ fileList }) => setFiles(fileList)}\n  overflow=\"scrollX\"\n  maxCount={5}\n/>",
+  "group": "data-entry",
+  "importPath": "@godxjp/ui/data-entry",
+  "name": "Attachments",
+  "props": [
+    {
+      "description": "Controlled attachment list. Ant Design X `items` (= antd Upload `fileList`).",
+      "name": "items",
+      "type": "AttachmentsItemProp[]"
+    },
+    {
+      "description": "antd Upload `onChange` — NOT `onValueChange`.",
+      "name": "onChange",
+      "type": "(info: { file: AttachmentsItemProp; fileList: AttachmentsItemProp[] }) => void"
+    },
+    {
+      "description": "Ant Design X `overflow`.",
+      "name": "overflow",
+      "type": "\"wrap\" | \"scrollX\" | \"scrollY\""
+    },
+    {
+      "description": "Empty-state copy for inline and drop surfaces.",
+      "name": "placeholder",
+      "type": "AttachmentsPlaceholderProp | ((type) => AttachmentsPlaceholderProp)"
+    },
+    {
+      "description": "Host for a full-screen drop overlay.",
+      "name": "getDropContainer",
+      "type": "() => HTMLElement | null"
+    },
+    {
+      "description": "Maximum files (antd Upload `maxCount`).",
+      "name": "maxCount",
+      "type": "number"
+    },
+    {
+      "defaultValue": "false",
+      "description": "Blocks selection and drop; the control stays focusable so a reader can still reach it.",
+      "name": "disabled",
+      "type": "boolean"
+    },
+    {
+      "description": "Forwarded to the hidden file input.",
+      "name": "accept",
+      "type": "string"
+    },
+    {
+      "description": "Child mode: visible trigger; upload runs through a hidden input beside it.",
+      "name": "children",
+      "type": "ReactElement"
+    }
+  ],
+  "related": [
+    "Upload",
+    "ChatComposer",
+    "ChatBubbleList"
+  ],
+  "rules": [
+    6,
+    44,
+    45
+  ],
+  "storyPath": "data-entry/Attachments.stories.tsx",
+  "tagline": "The chat-surface attachment collection (Ant Design X Attachments): file cards, inline placeholder, optional full-screen drop target, and ref.select/ref.upload — inherits antd Upload props but names the list `items`.",
+  "usage": [
+    "DO keep antd field names on each item (`thumbUrl`, `originFileObj`, `uid`) — an Ant X call site should compile unchanged.",
+    "DO use `ref.select({ accept, multiple })` to open the picker programmatically (Ant X 2.0).",
+    "DON'T expect `styles`/`classNames` from Ant X — retune through `--attachments-*` tokens.",
+    "The card is a FIXED box — 268x68 (Ant X's own), from `--attachments-card-size` (inline) and `--attachments-card-block-size`. The block size is also the `+` tile's square and the `overflow=\"scrollY\"` one-row viewport, so retune it once and all three follow. The file input is `sr-only`: never style it visible."
+  ],
+  "useCases": [
+    "The attachment tray above a ChatComposer in an assistant surface.",
+    "A Sender.Header slot showing picked files before send."
+  ]
+}

package/agent/components/AuthAccountSummary.json

@@ -0,0 +1,64 @@
+{
+  "example": "import { AuthAccountSummary } from \"@godxjp/ui/layout\";\n\n<AuthAccountSummary email={user.email} actionLabel={t(\"auth.switchAccount\")} onAction={switchAccount} />",
+  "group": "layout",
+  "importPath": "@godxjp/ui/layout",
+  "name": "AuthAccountSummary",
+  "props": [
+    {
+      "description": "Authoritative signed-in email.",
+      "name": "email",
+      "required": true,
+      "type": "string"
+    },
+    {
+      "description": "Optional real avatar URL.",
+      "name": "avatarSrc",
+      "type": "string"
+    },
+    {
+      "description": "Optional localized/text fallback; defaults to a user glyph.",
+      "name": "avatarFallback",
+      "type": "ReactNode"
+    },
+    {
+      "description": "Localized visible switch-account action label.",
+      "name": "actionLabel",
+      "required": true,
+      "type": "ReactNode"
+    },
+    {
+      "description": "Consumer-owned account-switch navigation/action.",
+      "name": "onAction",
+      "required": true,
+      "type": "() => void"
+    },
+    {
+      "description": "Disable the action while the consumer cannot switch.",
+      "name": "disabled",
+      "type": "boolean"
+    },
+    {
+      "description": "Optional structural class override.",
+      "name": "className",
+      "type": "string"
+    }
+  ],
+  "related": [
+    "AuthIdentity — page identity heading and requesting-client context; use AuthAccountSummary inside the card for the signed-in user.",
+    "Avatar — use Avatar directly for general profile surfaces; AuthAccountSummary owns only the compact hosted-auth row."
+  ],
+  "rules": [
+    45
+  ],
+  "storyPath": "layout/AuthAccountSummary.stories.tsx",
+  "tagline": "Compact signed-in account row for hosted auth: avatar fallback, authoritative email and switch action.",
+  "usage": [
+    "Pass only the authoritative signed-in email; AuthAccountSummary never fetches or invents identity data.",
+    "Pass localized actionLabel and the existing account-switch handler. The component owns no route, mutation or permission behavior.",
+    "The package owns avatar fallback, long-email truncation, responsive action wrapping and keyboard focus. Retune only through --auth-account-summary-* tokens."
+  ],
+  "useCases": [
+    "OAuth device consent and authorization cards where the user must confirm or switch the signed-in account.",
+    "Hosted consent screens that need a compact identity confirmation row without a second profile card."
+  ]
+}

package/agent/components/AuthDivider.json

@@ -0,0 +1,35 @@
+{
+  "example": "import { AuthDivider } from \"@godxjp/ui/layout\";\n\n<AuthDivider label=\"or\" />",
+  "group": "layout",
+  "importPath": "@godxjp/ui/layout",
+  "name": "AuthDivider",
+  "props": [
+    {
+      "description": "Localized conjunction such as “or”.",
+      "name": "label",
+      "required": true,
+      "type": "string"
+    },
+    {
+      "description": "Optional structural class override.",
+      "name": "className",
+      "type": "string"
+    }
+  ],
+  "related": [
+    "Separator — the primitive this presets; use it directly for any labelled rule outside auth."
+  ],
+  "rules": [
+    44,
+    45
+  ],
+  "storyPath": "layout/AuthDivider.stories.tsx",
+  "tagline": "The auth-scoped PRESET over `Separator label` — a localized conjunction between two equal rules.",
+  "usage": [
+    "DO use AuthDivider only INSIDE an auth form. It is a thin preset over `<Separator label>`: it re-points the --separator-* knobs at the --auth-shell-divider-* layer (the 11px auth micro-scale, the auth rule/label colours), so using it elsewhere drags auth geometry into an unrelated screen.",
+    "DON'T use it for a message stream's day divider or a \"new messages\" watermark — that is `<Separator label>` with a `labelAlign` and a `tone`. Misusing AuthDivider recreates the exact defect the preset removed: a service retuning its login divider silently retuned every divider in its chat."
+  ],
+  "useCases": [
+    "An “or” conjunction between a credential form and a provider action row"
+  ]
+}

package/agent/components/AuthFooter.json

@@ -0,0 +1,48 @@
+{
+  "example": "import { AuthFooter } from \"@godxjp/ui/layout\";\n\n<AuthFooter product=\"Acme ID\" terms={<a href=\"/terms\">Terms</a>} privacy={<a href=\"/privacy\">Privacy</a>} locale=\"English\" />",
+  "group": "layout",
+  "importPath": "@godxjp/ui/layout",
+  "name": "AuthFooter",
+  "props": [
+    {
+      "description": "Product identity content.",
+      "name": "product",
+      "required": true,
+      "type": "ReactNode"
+    },
+    {
+      "description": "Terms link or localized text.",
+      "name": "terms",
+      "required": true,
+      "type": "ReactNode"
+    },
+    {
+      "description": "Privacy link or localized text.",
+      "name": "privacy",
+      "required": true,
+      "type": "ReactNode"
+    },
+    {
+      "description": "Optional consumer-owned locale control.",
+      "name": "locale",
+      "type": "ReactNode"
+    },
+    {
+      "description": "Optional structural class override merged onto the footer root.",
+      "name": "className",
+      "type": "string"
+    }
+  ],
+  "rules": [
+    45
+  ],
+  "storyPath": "layout/AuthFooter.stories.tsx",
+  "tagline": "Compact hosted-auth footer for consumer-owned product, legal, privacy, and locale content.",
+  "usage": [
+    "Pass real links and locale controls from the consumer; AuthFooter never invents navigation.",
+    "DO drop it into AuthShell's `footer` slot — that slot supplies the contentinfo landmark, so AuthFooter itself renders a plain div and can also sit inside an existing footer without nesting landmarks.",
+    "AuthFooter owns ONLY the geometry: mono ramp, wrap, and a `·` separator between the slots that are actually PRESENT (omit `locale` and its separator disappears). Don't hand-write separators into the slot content.",
+    "Public type: `AuthFooterProp` (alias `AuthFooterProps`) from `@godxjp/ui/layout` — registered in the prop registry, not a local interface.",
+    "Retune the line through `--auth-footer-content-gap` / `--auth-footer-text-font-size`, never page CSS (rule #45)."
+  ]
+}

package/agent/components/AuthIdentity.json

@@ -0,0 +1,42 @@
+{
+  "example": "import { AuthIdentity } from \"@godxjp/ui/layout\";\nimport { Logo } from \"@godxjp/ui/general\";\n\n<AuthIdentity title=\"Sign in\" requester=\"Acme Portal is requesting access\" />\n\n// The product's own lockup, with no artwork in the consumer's repo:\n<AuthIdentity title=\"GoDX ID\" brand={<Logo mark=\"godx-lockup\" productSuffix=\"ID\" />} />",
+  "group": "layout",
+  "importPath": "@godxjp/ui/layout",
+  "name": "AuthIdentity",
+  "props": [
+    {
+      "description": "Primary auth heading.",
+      "name": "title",
+      "required": true,
+      "type": "ReactNode"
+    },
+    {
+      "description": "Brand artwork in the MARK's place, for a service whose design ships a real lockup (mark + wordmark, sometimes a product suffix). Omit it and the canonical GoDX mark renders. data-slot, .ui-auth-identity spacing and the h1 are untouched, so swapping artwork never forks the block.",
+      "name": "brand",
+      "type": "ReactNode"
+    },
+    {
+      "description": "Optional real requesting-client context.",
+      "name": "requester",
+      "type": "ReactNode"
+    },
+    {
+      "description": "Optional structural class override merged onto the identity root.",
+      "name": "className",
+      "type": "string"
+    }
+  ],
+  "rules": [
+    45
+  ],
+  "storyPath": "layout/AuthIdentity.stories.tsx",
+  "tagline": "Hosted-auth identity heading with the shared mark (or the product's own lockup) and optional requesting-client context.",
+  "usage": [
+    "Only show `requester` when the consumer has authoritative client context.",
+    "It ALREADY renders the canonical brand-green GoDX mark (`Logo mark=\"godx\" tone=\"success\"`, independent of --primary) plus the page h1 — don't add a second Logo or heading above it.",
+    "To show YOUR OWN lockup instead, pass it as `brand` — never wrap or rebuild the block. `brand` replaces the mark only, so the h1 stays; if your lockup already spells the product name, make `title` the SCREEN'S PURPOSE (\"Sign in\") rather than repeating the brand.",
+    "DO keep `brand` non-interactive. The slot is DECORATIVE at every fill: the mark it replaces was always aria-hidden, and a real lockup is not a mark — `Logo mark=\"godx-lockup\" productSuffix=\"ID\"` exposes \"GoDX ID\" as real text, so left in the tree beside the h1 the block announces the product twice (measured: \"GoDXIDGoDX ID\"). aria-hidden is merged onto your element, and aria-hidden over a focusable child is a WCAG failure.",
+    "Centring and rhythm are token-owned (`--auth-identity-gap` / `--auth-requester-*`); no page CSS (rule #45).",
+    "Public type: `AuthIdentityProp` (alias `AuthIdentityProps`) from `@godxjp/ui/layout` — registered in the prop registry, not a local interface."
+  ]
+}

package/agent/components/AuthShell.json

@@ -0,0 +1,108 @@
+{
+  "absorbed": [
+    "OrganizationChoiceList"
+  ],
+  "example": "import { AuthShell, AuthIdentity, AuthFooter } from \"@godxjp/ui/layout\";\nimport { Reveal, Logo, Button } from \"@godxjp/ui/general\";\nimport { Card, CardContent, CardHeader, CardTitle } from \"@godxjp/ui/data-display\";\nimport { AppSettingPicker } from \"@godxjp/ui/navigation\";\n\nexport function DeviceAuthorizationPage() {\n  return (\n    // 380px card at 1440/1024 · 5px inline gutter at 390 — all token-owned, no page CSS.\n    <AuthShell\n      variant=\"canonical\"\n      preset=\"device-authorization\"\n      brand={<Logo mark=\"godx\" tone=\"success\" />}\n      footer={\n        <AuthFooter\n          product=\"GoDX ID\"\n          terms=\"Terms\"\n          privacy=\"Privacy\"\n          locale={<AppSettingPicker kind=\"locale\" appearance=\"labeled\" compact />}\n        />\n      }\n    >\n      <Reveal>\n        <Card>\n          <CardHeader>\n            <AuthIdentity title=\"デバイスを認証\" requester=\"勤怠管理が認証を要求しています\" />\n            <CardTitle level={2}>確認コードを入力</CardTitle>\n          </CardHeader>\n          <CardContent>\n            {/* InputOTP + actions */}\n            <Button fullWidth>デバイスを承認</Button>\n          </CardContent>\n        </Card>\n      </Reveal>\n    </AuthShell>\n  );\n}",
+  "group": "layout",
+  "importPath": "@godxjp/ui/layout",
+  "name": "AuthShell",
+  "props": [
+    {
+      "description": "Centred content — typically a single auth <Card> holding the form.",
+      "name": "children",
+      "required": true,
+      "type": "ReactNode"
+    },
+    {
+      "description": "Brand bar slot pinned to the top (e.g. a <Logo> / product mark).",
+      "name": "brand",
+      "type": "ReactNode"
+    },
+    {
+      "description": "Page-level controls pinned to the TOP-RIGHT of the same banner row as `brand` — a locale <Select>/<AppSettingPicker>, a theme <ToggleGroup>, a \"need help?\" link. They belong to the PAGE, not the auth form, so they sit in the bar, not in the card. The banner renders as soon as `brand` OR `actions` is present.",
+      "name": "actions",
+      "type": "ReactNode"
+    },
+    {
+      "description": "Footer slot pinned to the bottom (legal links, locale switch, support).",
+      "name": "footer",
+      "type": "ReactNode"
+    },
+    {
+      "defaultValue": "\"default\"",
+      "description": "Visual contract for the auth surface. \"canonical\" applies the shared DXS compact geometry (36px controls, 22.5rem/360px card measure, responsive page insets, tighter field labels) through component tokens. \"default\" keeps the comfortable 44px shell with the 24rem card.",
+      "name": "variant",
+      "type": "\"default\" | \"canonical\""
+    },
+    {
+      "defaultValue": "\"default\"",
+      "description": "Named flow GEOMETRY — the package-owned layout contract for a canonical hosted-identity flow. \"device-authorization\" = a 380px card at 1440/1024 with a 5px inline page gutter at 390, AND the code field itself: the preset hands --otp-slot-{inline,block}-size the canonical 27.5x52 device-grant slot, so two 4-slot grouped boxes measure 112x54 instead of the 146x38 the square --control-height tier produced. \"registration\" = the 360px sign-up measure with a 15px inline gutter at 390 (the same page rhythm as \"login\", so sign-in to sign-up never jumps on a phone). START-aligned like login: a sign-up card is the tallest surface in the set (name/email/password/confirm/strength/consent/submit/providers) and a vertically centred tall card overflows ABOVE the scroll origin on a short viewport, putting its first field out of reach.",
+      "name": "preset",
+      "type": "\"default\" | \"login\" | \"registration\" | \"device-authorization\" | \"context-selection\" | \"account-recovery\""
+    },
+    {
+      "defaultValue": "\"default\"",
+      "description": "Inline MEASURE of the shell content slot. \"default\" is the single auth card (24rem, or 22.5rem under variant=\"canonical\"). \"wide\" opens the slot to --auth-shell-wide-card-max-width (64rem) for a SPLIT login: a brand/marketing panel beside the auth card, laid out with <ResponsiveGrid columns={{ sm: 1, lg: 2 }}>. The wide slot centres with auto margins, so a tall two-column layout starts at the top instead of overflowing above the scroll origin. Ignored under a `preset` — a preset already owns its flow geometry.",
+      "name": "measure",
+      "type": "\"default\" | \"wide\""
+    },
+    {
+      "description": "Block-axis placement of the auth column — ORTHOGONAL to `preset` the way `variant` is: the preset owns the page MEASURE (card width, inline gutters, section rhythm), `align` owns where that column sits vertically. Omit it to keep the preset's own choice: \"login\" and \"registration\" anchor so a requester/identity line that wraps to two lines cannot move the card (gh#237), every other preset centres. Pass \"center\" for a vertically centred column — the block-start inset collapses to the preset's block-end one on desktop AND mobile, so the padding is symmetric and justify-content has nothing to fight — or \"anchored\" for a top-anchored one. This is what replaces re-declaring a preset's offset tokens from consumer CSS, the page-local-vertical-offset anti-pattern presets exist to remove. HAZARD on a tall flow: a vertically centred tall card overflows ABOVE the scroll origin on a short viewport, putting its first field out of reach — which is why \"registration\" anchors by default; \"center\" is legal there but is the caller's judgement.",
+      "name": "align",
+      "type": "\"anchored\" | \"center\""
+    },
+    {
+      "description": "Vertical density scoped to auth-card descendants. Defaults to \"compact\" under variant=\"canonical\" and \"comfortable\" otherwise.",
+      "name": "density",
+      "type": "\"comfortable\" | \"compact\""
+    },
+    {
+      "description": "Extra CSS classes merged onto the shell root.",
+      "name": "className",
+      "type": "string"
+    }
+  ],
+  "related": [
+    "AppShell — the shell for AUTHENTICATED app pages (sidebar + topbar + main). AuthShell is its unauthenticated counterpart (brand bar + centred card + footer). Never nest the two.",
+    "Reveal — 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 — the canonical container for the auth form; place the form inside <CardContent>. AuthShell centres and width-constrains it.",
+    "EmptyState — with `tone=\"success\"` for a confirmation card inside the shell (e.g. device approved).",
+    "AuthIdentity / AuthFooter / AuthStack / AuthDivider — the auth composites that fill the shell: the GoDX identity mark + heading + requesting-client line, the mono legal footer (its `locale` slot takes an <AppSettingPicker kind=\"locale\" appearance=\"labeled\" compact />), the 12px section rhythm, and the labelled \"or\" rule.",
+    "ListRow — compose the organisation choice list for `preset=\"context-selection\"` as <Card><CardContent flush><Flex as=\"ul\" marker=\"none\"> of <ListRow as=\"li\">: shared row dividers, no per-row card outline. There is no separate OrganizationChoiceList component — that is a composition pattern (rule #46), not a framework component."
+  ],
+  "rules": [
+    23
+  ],
+  "storyPath": "layout/AuthShell.stories.tsx",
+  "tagline": "Centred auth/login page shell — brand bar (top) + centred card (main) + footer, over min-h-dvh, at comfortable control density.",
+  "usage": [
+    "DO pass a single <Card> (with the form inside <CardContent>) as `children` — 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 use `variant=\"canonical\" preset=\"login\"` for SCR-001 and pass <AuthIdentity>, <Card>, <AuthFooter> as direct children in that order (an anchor may wrap AuthIdentity). The preset owns the identity slot, card anchor, 20px section rhythm and compact card block inset for standalone and real requester states. Do not wrap the three sections in a consumer Flex/Stack or the semantic grid cannot anchor them.",
+    "DO select a `preset` instead of overriding geometry: `preset=\"login\"` for the stable SCR-001 identity/card/footer anchor, `preset=\"registration\"` for the sign-up form and its pending-email state, `preset=\"device-authorization\"` for the 380px OAuth device-grant measure, `preset=\"context-selection\"` for the 25rem organisation/context picker, `preset=\"account-recovery\"` for the 432px SCR-008 recovery/MFA panel. Page-local width/inset/vertical-offset variables are the exact anti-pattern these presets replace.",
+    "DO build the SOCIAL / PROVIDER ACTION row as a COMPOSITION — there is NO SocialLinks component: `<AuthDivider label=\"or\" />` followed by a `Flex direction=\"col\" gap=\"sm\"` of real `Button variant=\"outline\"` with the provider glyph as an aria-hidden icon. The package deliberately does not own it: which providers a product offers, in what order, and what consent they imply are product decisions, and a component would have to invent them. `disabled` / `loading` are the Button's own props — do not add a provider-specific API.",
+    "DO build the ORGANIZATION CHOICE LIST as a COMPOSITION — there is NO OrganizationChoiceList component: `Card` > `CardContent flush` > a `<Flex as=\"ul\" marker=\"none\">` of `ListRow as=\"li\"` (leading Avatar, title, description, trailing Button). `CardContent flush` is what gives shared row dividers instead of a card outline per row. Its states are existing exports, never bespoke markup: Skeleton rows for loading, `EmptyState` for no invitations, `Alert tone=\"destructive\"` for a failed fetch and `Alert tone=\"warning\"` for permission-denied. See the auth-shell-context and auth-shell-registration frames.",
+    "DO build the password-recovery and sign-in MFA CHALLENGE panels as a COMPOSITION inside `preset=\"account-recovery\"` — there is NO PasswordRecoveryPanel and NO MfaChallengePanel component: Card > CardHeader(CardTitle + CardDescription, INSIDE the bordered surface) > CardContent > AuthStack[ Alert notice · FormField fields · Button fullWidth · Flex justify=\"between\" wrap fallback row ]. Do NOT put AuthIdentity above the panel there (it always renders the hosted mark), and NEVER reuse TwoFactorSetup — that is the ENROLLMENT dialog, not a sign-in challenge. See the `auth-recovery-panels` pattern.",
+    "DO combine `variant` and `preset` — they are orthogonal: `variant` owns control density + heading size, `preset` owns the page measure. `variant=\"canonical\" preset=\"device-authorization\"` is the canonical device screen.",
+    "DO let `preset=\"context-selection\"` space the auth column: it turns the card slot into a flex column with a tokenized `--auth-shell-card-stack-gap`, so an intro (<AuthIdentity>), the choice <Card> and a trailing \"remember\" row pass as three siblings with NO page-local spacing.",
+    "DO NOT add a page-local width, inset or colour to hit an artboard — if a measure is missing, it is a library gap: a new preset or token, never consumer CSS (rules #44/#45).",
+    "DO state the block placement with `align` when a product wants the opposite of its preset's default — align=\"center\" on preset=\"login\" for a vertically centred SCR-001, align=\"anchored\" to top-anchor a preset that centres. It collapses the preset's block-start inset to its block-end one on desktop AND mobile, so justify-content has nothing to fight. Re-declaring --auth-shell-login-flow-offset-block (or any preset offset token) from a consumer stylesheet is the anti-pattern it replaces.",
+    "DO put the product/brand mark in `brand` (a <Logo> or an <Avatar>) — it renders as the top banner landmark; omit it and the banner is not rendered.",
+    "DO put page-level controls in `actions` — the locale picker, the theme <ToggleGroup>, a \"need help?\" link. They land at the banner's inline end at a tokenized gap (`--auth-shell-bar-gap`), and the banner appears even with no `brand`. Do NOT hand-roll a top-right row with `ms-auto` on the `brand` content, and do NOT reach for CenteredShell just to get a topbar with actions: CenteredShell is the AUTHENTICATED shell.",
+    "DO use `measure=\"wide\"` for the SPLIT login — a brand/marketing panel beside the auth card. The content slot opens to 64rem (`--auth-shell-wide-card-max-width`) and centres with auto margins, so the tall two-column layout starts at the top instead of overflowing above the scroll origin; lay the two halves out with <ResponsiveGrid columns={{ sm: 1, lg: 2 }}> and hide the panel below `lg`. It is IGNORED under a `preset` (a preset owns its flow geometry), so pick one or the other.",
+    "DO use `footer` for compliance/legal/support links or a locale switch — it renders as the contentinfo landmark below the card.",
+    "DO wrap the card in <Reveal> for the entrance animation (`<AuthShell><Reveal><Card/></Reveal></AuthShell>`) — Reveal honours prefers-reduced-motion; AuthShell itself stays layout-only.",
+    "DO NOT re-scope control height or heading size in the app — 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 tune the COMPACT auth card through its three independent knobs, never a consumer selector on `[data-slot=\"card-content\"]`: `--auth-shell-compact-card-inset` = the inline column, `--auth-shell-card-padding-block-compact` = the card's block (top/bottom) padding — it is wired to the card's `--card-space-shell-y` and really moves CardContent's block edges — and `--auth-shell-card-body-gap-compact` = the header↔body gap. Each defaults to today's canonical rhythm, so overriding one moves ONLY that axis.",
+    "DO NOT nest AuthShell inside AppShell (or vice-versa) — AuthShell is the ROOT shell for unauthenticated pages (login/mfa/passkey/device/reset); AppShell is for the authenticated app."
+  ],
+  "useCases": [
+    "Canonical Login (SCR-001): <AuthShell variant=\"canonical\" preset=\"login\"> with direct AuthIdentity · Card · AuthFooter children; the card remains anchored when requester is absent, one line or wraps to two lines.",
+    "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.",
+    "OAuth device-grant screen (SCR-004): <AuthShell variant=\"canonical\" preset=\"device-authorization\"> — a 380px card at 1440/1024 and a 5px inline gutter at 390, with zero page-local CSS.",
+    "Organisation / context selection (/select-context): <AuthShell variant=\"canonical\" preset=\"context-selection\" brand={<Logo mark=\"godx\" />}> with an <AuthIdentity> intro, a <Card><CardContent flush> list of <ListRow as=\"li\"> organisations, and a trailing \"remember this choice\" <Checkbox> — the preset spaces the three sections.",
+    "Split product login: <AuthShell measure=\"wide\" brand={<Logo/>} actions={<><Select locale/><ToggleGroup theme/></>}> around a <ResponsiveGrid columns={{ sm: 1, lg: 2 }}> whose first cell is the brand/value panel (hidden below lg) and whose second is the auth <Card>. See docs/showcase/case4-login.",
+    "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."
+  ]
+}

package/agent/components/AuthStack.json

@@ -0,0 +1,21 @@
+{
+  "example": "import { AuthStack } from \"@godxjp/ui/layout\";\n\n<AuthStack><PasskeyAction /><CredentialsForm /></AuthStack>",
+  "group": "layout",
+  "importPath": "@godxjp/ui/layout",
+  "name": "AuthStack",
+  "props": [
+    {
+      "description": "Auth sections in visual order.",
+      "name": "children",
+      "type": "ReactNode"
+    },
+    {
+      "description": "Optional structural class override.",
+      "name": "className",
+      "type": "string"
+    }
+  ],
+  "rules": [],
+  "storyPath": "layout/AuthStack.stories.tsx",
+  "tagline": "Token-spaced vertical stack for direct sections inside a canonical auth card."
+}

package/agent/components/Avatar.json

@@ -0,0 +1,89 @@
+{
+  "example": "import { Avatar, AvatarFallback, AvatarImage } from \"@godxjp/ui/data-display\";\n\n<Avatar>\n  <AvatarImage src=\"/user.png\" alt=\"User\" />\n  <AvatarFallback>UI</AvatarFallback>\n</Avatar>\n\n// Organization entity header mark\n<Avatar shape=\"square\">\n  <AvatarFallback>山</AvatarFallback>\n</Avatar>\n\n// A chat member with realtime presence — dot + localized sr-only text, never colour alone\n<Avatar presence=\"busy\">\n  <AvatarImage src=\"/rei.png\" alt=\"佐藤 玲\" />\n  <AvatarFallback>佐</AvatarFallback>\n</Avatar>",
+  "group": "data-display",
+  "importPath": "@godxjp/ui/data-display",
+  "name": "Avatar",
+  "props": [
+    {
+      "defaultValue": "\"circle\"",
+      "description": "Identity geometry. `circle` (default, inert) is the PERSON avatar — the round --radius-pill mark on the muted surface. `square` is the ENTITY-HEADER organization/service mark: a compact rounded square on the brand surface, whose radius, box size, fill and glyph colour are all --avatar-square-{radius,size,background,foreground} tokens. Pick the shape by WHAT the mark represents; never hand-roll it with className=\"rounded-md bg-primary\".",
+      "name": "shape",
+      "type": "\"circle\" | \"square\""
+    },
+    {
+      "defaultValue": "\"md\"",
+      "description": "Box size on the SHARED CONTROL LADDER — md 32px (--control-height, the inert default), sm 28px, xs 24px, lg 36px, the same --control-height-* tier Button and Input read. STATE IT WHENEVER THE ROW'S HEIGHT IS ALREADY DECIDED: a mark inside a `<Button size=\"icon-sm\">` trigger, a mark in a 24/28px dense table row, a mark beside a `size=\"sm\"` Button. A `size=\"sm\"` avatar measures exactly as tall as a `size=\"sm\"` Button, so the row stays level. Before gh#716 the box was welded to --control-height: a 32px mark inside a 28px icon-sm trigger OVERFLOWED it, and a consumer sweeping control heights across 38 routes had no legal move but to raise the whole row to 32px. The initials' type step and a glyph's box move WITH the box (one step of the type scale, one step of the --icon-size-* scale), and shape=\"square\" rides the identical ladder — so a small mark is small, never clipped. A size BEYOND the control ladder (a 96px profile mark) is still a className size utility; the prop is for the control row.",
+      "name": "size",
+      "type": "\"xs\" | \"sm\" | \"md\" | \"lg\""
+    },
+    {
+      "defaultValue": "\"default\"",
+      "description": "Fill treatment, ORTHOGONAL to `shape`. `default` (inert) is the identity fill — --muted for a person, the solid brand mark for `shape=\"square\"`. `tinted` is the CAPABILITY MEDALLION: a soft role wash behind a role-coloured glyph, with the glyph sized by the component. `shape=\"square\" appearance=\"tinted\"` is the canonical rounded-square medallion a feature/capability icon sits on.",
+      "name": "appearance",
+      "type": "\"default\" | \"tinted\""
+    },
+    {
+      "description": "Which side of the trigger the panel opens on. Defaults from `appearance` — a bar drops the grid below, anything else opens to the inline-end. State it when the chrome can be RE-DOCKED: `appearance` says the trigger is not in a bar but cannot say which way is out, and a rail pinned to the top edge still opens downward. Ignored by responsive=\"fullscreen\" and by the Sheet surface, which are not anchored to the trigger.",
+      "name": "side",
+      "type": "\"top\" | \"right\" | \"bottom\" | \"left\""
+    },
+    {
+      "description": "How the panel aligns to the trigger. Defaults from `appearance` — end in a bar, start otherwise. Same rule as `side`: state it only for chrome that knows its own orientation.",
+      "name": "align",
+      "type": "\"start\" | \"center\" | \"end\""
+    },
+    {
+      "description": "Realtime reachability, drawn as an indicator at the block-end/inline-end corner of the mark. Ships the dot, its geometry tokens and a localized sr-only label TOGETHER, so presence is never colour-only (WCAG 1.4.1): each value also has its own silhouette — online = filled disc (--success), away = half-filled (--warning), busy = filled + a horizontal do-not-disturb bar (--destructive), offline = hollow ring (--muted-foreground). OMIT the prop for an entity with no presence concept (an organization mark, a capability medallion): no node and no attribute are emitted. `presence=\"offline\"` is the DIFFERENT, positive statement \"known to be unreachable\" — the same distinction ListRow draws between an omitted and a `false` `unread`.",
+      "name": "presence",
+      "type": "\"online\" | \"away\" | \"busy\" | \"offline\""
+    },
+    {
+      "description": "Override the localized presence text (t(\"dataDisplay.avatar.presence.online\") …) when the product has a more precise phrasing (\"In a meeting until 15:00\"). Visually hidden either way — a presence dot never carries visible text; that is Badge status.",
+      "name": "presenceLabel",
+      "type": "string"
+    },
+    {
+      "description": "Compose AvatarImage and AvatarFallback.",
+      "name": "children",
+      "type": "ReactNode"
+    },
+    {
+      "description": "Extra classes on the avatar root.",
+      "name": "className",
+      "type": "string"
+    }
+  ],
+  "related": [
+    "Badge — use beside Avatar for role/status metadata. Badge `status` is the LIFECYCLE chip (a record's state, with a visible label); Avatar `presence` is the realtime person dot. Different vocabularies on purpose — do not swap them.",
+    "ListRow — its `unread` prop is the same bargain one level up (a dot + localized sr-only text + tokens). Use ListRow `unread` for a row's read state, Avatar `presence` for the person on it."
+  ],
+  "rules": [
+    3,
+    35
+  ],
+  "storyPath": "data-display/Avatar.stories.tsx",
+  "subParts": [
+    "AvatarFallback",
+    "AvatarImage"
+  ],
+  "tagline": "Radix Avatar wrapper with image and fallback slots for users, teams, and entities.",
+  "usage": [
+    "DO compose Avatar > AvatarImage + AvatarFallback so broken or missing images still show a readable fallback.",
+    "DO use `presence` for who is reachable RIGHT NOW — a chat member list, a DM row, a message-stream author, the topbar account mark. It is the only supported way to put a status dot on an avatar: the dot's inset is a function of the mark's own --avatar-* radius/size and of the root's clip, neither of which a page can read, which is why the hand-rolled `<span className=\"relative\"><Avatar/><span className=\"absolute -end-0.5 -bottom-0.5 size-2.5 rounded-full bg-green-500 ring-2 ring-background\"/></span>` wrapper can never be got right from outside (and fails the DS audit on the raw palette).",
+    "DON'T announce a presence CHANGE from the avatar — it carries no aria-live on purpose. A roster of 40 marks resyncing over a socket would flood a screen reader; announce the change in the consumer's own live region if the product wants it.",
+    "DON'T reach for `Badge status` for presence, or `presence` for lifecycle. Presence is volatile, per-person and realtime and renders as a dot; a lifecycle status is a record's state and renders as a labelled chip.",
+    "DO render a capability / feature icon as `<Avatar shape=\"square\" appearance=\"tinted\"><AvatarFallback><Sparkles aria-hidden /></AvatarFallback></Avatar>` — the medallion is a COMPOSITION (Avatar + a Lucide glyph, per docs/COMPOSITION-VS-COMPONENT.md), and `appearance=\"tinted\"` is the token-owned tint that composition needs. A BARE glyph beside a card title, or a hand-derived `hsl(var(--primary) / 0.1)` plate in page CSS, are both the anti-pattern this replaces. Left-aligned capability card: `<Card><CardHeader><Flex align=\"center\" gap={3}><Avatar shape=\"square\" appearance=\"tinted\">…</Avatar><CardTitle>…</CardTitle></Flex></CardHeader>…`. The row is a `Flex`, NOT `className=\"flex flex-row items-center gap-3\"` on the CardHeader — that spelling shipped here for a while and it is two ui-audit errors in a consumer (`no-utility-layout` + `no-utility-spacing`), i.e. this catalog was prescribing what the audit forbids. `CardTitle` has no `icon` prop and does not need one: the medallion is its SIBLING, not its content, and inside CardTitle it would get neither the gap nor the glyph sizing.",
+    "DO use `shape=\"square\"` for an organization / service / tenant mark in an entity header, and keep the default `shape=\"circle\"` for people. The square appearance already carries the brand surface and an AA-contrast glyph colour — a className/colour override on the call site is never needed (and is forbidden by the API-first redesign policy).",
+    "DON'T retune the entity mark per call site: set --avatar-square-{radius,size,background,foreground} ONCE in the service theme (e.g. --avatar-square-background: hsl(var(--muted)) for a neutral mark).",
+    "DON'T use Avatar for decorative thumbnails; use CardCover or an img when the image is content rather than identity.",
+    "DO set `size` from the ROW, not from the mark: a row whose height is already fixed (an icon-sm trigger, a 24/28px dense table row, a toolbar of sm controls) takes the matching avatar step, and the mark then measures exactly what a Button of the same step measures. `<Button size=\"icon-sm\"><Avatar size=\"sm\">…</Avatar></Button>` fits; the default md mark in that same trigger overflows it.",
+    "DON'T raise a whole row's control height just to fit a person's mark, and DON'T reach for a className size utility for a step that is ON the ladder (size-6 / size-7 re-derive 24/28px outside the density axis, so they stop tracking --control-height and drift from the controls beside them). className stays the escape hatch for sizes OFF the ladder — a 96px profile mark."
+  ],
+  "useCases": [
+    "User profile chips",
+    "Team member lists",
+    "Account owner cells in a DataTable",
+    "Organization / service entity headers (shape=\"square\" beside the entity name and code)",
+    "Chat / collaboration people surfaces (presence=\"online|away|busy|offline\" on DM rows, channel member lists, message-stream authors)"
+  ]
+}

package/agent/components/Badge.json

@@ -0,0 +1,96 @@
+{
+  "example": "import { Badge } from \"@godxjp/ui/data-display\";\n\n<Badge variant=\"secondary\">A/B</Badge>\n<Badge status=\"active\">公開中</Badge>\n<Badge status=\"プレミアム\" tone=\"success\" icon={null}>プレミアム</Badge>\n<Badge shape=\"pill\" color=\"#4488c5\">処理中</Badge>",
+  "group": "data-display",
+  "importPath": "@godxjp/ui/data-display",
+  "name": "Badge",
+  "props": [
+    {
+      "defaultValue": "\"div\"",
+      "description": "Render element. Swaps the TAG only — the chip keeps its own inline-flex box, icon and label. Pass \"span\" when the chip sits in a PHRASING context where a <div> is invalid HTML: inside a TabsTrigger, a PopoverTrigger or a Button (each renders a <button>, whose content model is phrasing content only), inside a <label>, or inside a <p>.",
+      "name": "as",
+      "type": "\"div\" | \"span\""
+    },
+    {
+      "defaultValue": "\"default\"",
+      "description": "STRUCTURAL emphasis only (fill/border style) — NOT colour. Use `tone` for semantic colour. `dashed` = dashed border.",
+      "name": "variant",
+      "type": "\"default\" | \"secondary\" | \"outline\" | \"dashed\""
+    },
+    {
+      "description": "SEMANTIC colour intent (BadgeTone = ToneProp + `primary`). This is the colour knob — success/warning/destructive/info/etc. `primary` is a SOFT brand pill (tinted brand fill + brand text) for the dashboard role-pill pattern; for a SOLID brand fill use `variant=\"default\"`. Keep variant for structure, tone for meaning.",
+      "name": "tone",
+      "type": "\"default\" | \"primary\" | \"success\" | \"warning\" | \"destructive\" | \"info\" | \"muted\" | \"neutral\""
+    },
+    {
+      "defaultValue": "\"default\"",
+      "description": "Corner radius from the tokens — `default` (badge radius), `pill` (fully rounded), `sharp` (square). Use the prop instead of a `rounded-*` className.",
+      "name": "shape",
+      "type": "\"default\" | \"pill\" | \"sharp\""
+    },
+    {
+      "defaultValue": "false",
+      "description": "Lining, fixed-width figures — for a chip whose content is a COUNT sitting in a column with other counts (a queue length per row, an unread tally per tab). Proportional figures make a `1` narrower than a `0`, so the digits do not line up and the chips jitter. The same axis Text, TableCell and StatCard already carry. Off by default: tabular figures are wider, and a chip carrying WORDS should not pay for them. Prefer it over `<Badge><Text size=\"xs\" tabular>` — that composition works, but it asks the call site to know the chip's own type step.",
+      "name": "tabular",
+      "type": "boolean"
+    },
+    {
+      "description": "The entity's OWN colour as a CSS colour — DATA, not a semantic tone: a status colour, an issue type, a tag, whatever a person picked in a settings screen. A third axis beside `variant` (structure) and `tone` (meaning), and it wins over both. The chip is WASHED rather than filled (`--badge-tint-fill` into `--badge-tint-surface`, label from `--badge-tint-foreground`) because no foreground clears WCAG AA against every colour a picker can produce — near-black and white measure equal at luminance 0.2029, both 4.15:1. Washed, the ratio is a function of the tokens instead: 8.52:1 worst case across the sRGB cube, both themes.",
+      "name": "color",
+      "type": "string"
+    },
+    {
+      "description": "Lifecycle key. Known keys auto-map to tone + icon + i18n label; unknown keys fall back to neutral.",
+      "name": "status",
+      "type": "string"
+    },
+    {
+      "description": "Leading icon override. Pass null to suppress the auto status icon.",
+      "name": "icon",
+      "type": "React.ComponentType<{ className?: string }> | null"
+    },
+    {
+      "description": "Badge label. When omitted with status, Badge renders the translated lifecycle label or raw status.",
+      "name": "children",
+      "type": "ReactNode"
+    },
+    {
+      "description": "antd Tag `closable` + `onClose` — draws a × on the chip and calls this when the user activates it. Omit for a plain badge (no ×). Accessible name quotes the string label via `navigation.filterBar.removeFilter`.",
+      "name": "onRemove",
+      "type": "() => void"
+    },
+    {
+      "description": "The × button's full accessible name, verbatim — antd 5.15+ `closable={{ 'aria-label' }}` (gh#706). Without it the name quotes the chip's label: a string `children`, or the label's RENDERED TEXT when `children` is a link or other node (so a row of saved-filter link chips never shares one bare \"Delete\"). Use it when the chip text alone doesn't say what removing does.",
+      "name": "removeLabel",
+      "type": "string"
+    }
+  ],
+  "related": [
+    "Button — use instead of Badge when the chip must be interactive (clickable, toggleable). Badge carries no button role or keyboard handler; a naked `onClick` on Badge is inaccessible."
+  ],
+  "rules": [
+    35
+  ],
+  "storyPath": "data-display/Badge.stories.tsx",
+  "subParts": [
+    "StatusBadge"
+  ],
+  "tagline": "Plain or lifecycle badge. Use `variant` for static chips, or `status` to auto-map lifecycle keys to semantic tone + icon. Labels never wrap.",
+  "usage": [
+    "DO pick the correct variant semantically: `success` (approved/paid), `warning` (pending/overdue), `destructive` (rejected/error), `secondary` (neutral category), `outline` (subtle label), `default` (primary accent). Never force a colour just for aesthetics — agents and screen readers read the variant as intent.",
+    "DO use `status` for entity lifecycle statuses (active, draft, pending, cancelled, failed, scheduled, etc.) so the component resolves the correct tone, icon, and i18n label.",
+    "DO pass `variant` explicitly for localized labels or categorical tiers, and pass `icon={null}` when a lifecycle glyph would be misleading.",
+    "Badge renders as a `<div>` by default (HTMLAttributes<HTMLDivElement>) — pass `as=\"span\"` when it sits inside a <button>, <label> or <p>, where a <div> is invalid HTML. With `onRemove`, the chip draws its own × (antd Tag closable); without it the chip is non-interactive. Do not add a naked `onClick` without an accessible role.",
+    "With `onRemove`, the × is part of the chip (antd Tag closable) — do not bolt a separate Button beside the label. Pass a string `children` label so the remover's accessible name quotes the chip.",
+    "Without `onRemove`, Badge is a leaf — pass plain text or a short ReactNode as children. Do NOT nest another Badge or interactive controls inside it.",
+    "Use semantic tokens for any className overrides (`text-muted-foreground`, `bg-destructive`) — never raw Tailwind palette classes like `bg-green-500`.",
+    "DO pass `color` — never an inline `backgroundColor` — when the colour belongs to the RECORD rather than to its meaning (a status an administrator coloured, an issue type, a tag). A hand-filled chip has to choose a foreground, and no choice is readable for every colour a picker can produce; `color` moves the ground instead and keeps the label on the surface's own foreground."
+  ],
+  "useCases": [
+    "Category or tier labels on table rows — e.g. plan tier (`<Badge variant=\"secondary\">Pro</Badge>`), document type (`<Badge variant=\"outline\">Invoice</Badge>`), or locale tag (`<Badge variant=\"secondary\">EN</Badge>`).",
+    "Approval or review state in an accounting list where the value is not a lifecycle key in Badge's STATUS_MAP — e.g. a custom approval tier like `<Badge tone=\"success\">承認済</Badge>` or `<Badge tone=\"warning\">要確認</Badge>`.",
+    "Inline count or highlight next to a heading or nav item — e.g. `<Badge variant=\"destructive\">3</Badge>` beside 'Overdue invoices' to draw attention to a non-zero count.",
+    "Feature flags or experiment variant labels on admin records — e.g. `<Badge variant=\"outline\">A/B</Badge>` alongside a campaign row to indicate it is in a split test.",
+    "Read-only metadata chips inside a Descriptions.Item or Card header where a lifecycle icon would be visually heavy — e.g. currency code, payment method, or region tag.",
+    "A status or category an administrator coloured themselves, in an issue tracker or a CRM — `<Badge shape=\"pill\" color={status.color}>{status.name}</Badge>`. The colour comes out of a picker and is stored on the row, so it cannot be mapped to a tone."
+  ]
+}