@godxjp/ui 19.1.0 → 19.3.1

package/docs/layout/auth-account-summary.tsx

@@ -0,0 +1,103 @@
+import { Card, CardContent, CardDescription, CardHeader, CardTitle } from "@godxjp/ui/data-display";
+import { AuthAccountSummary, AuthStack, PageContainer } from "@godxjp/ui/layout";
+
+/**
+ * AuthAccountSummary — compact signed-in identity row for hosted auth and device authorization.
+ *
+ * The row owns three things: the avatar (image, caller fallback, or the default person glyph),
+ * the account address, and exactly one ghost action. Everything else is consumer data.
+ *
+ * The address CLIPS with an ellipsis, so it declares its own line box rather than inheriting one
+ * (gh#254): a tight inherited line-height makes the clip box shorter than the font's ascent plus
+ * descent and shears Vietnamese tone marks and Latin descenders off, while the DOM text stays
+ * correct. The Vietnamese row below is the regression case for that.
+ */
+export default function Demo() {
+  return (
+    <PageContainer
+      title="AuthAccountSummary"
+      subtitle="サインイン中のアカウント行（アバター・アドレス・単一アクション）"
+    >
+      <Card>
+        <CardHeader>
+          <CardTitle level={2}>アバターの3系統</CardTitle>
+          <CardDescription>
+            画像、呼び出し側のフォールバック文字、既定の人物グリフ。いずれも装飾扱いで、読み上げ対象は
+            アドレスとアクションのみです。
+          </CardDescription>
+        </CardHeader>
+        <CardContent>
+          <AuthStack>
+            <AuthAccountSummary
+              email="hanako.yamada@example.co.jp"
+              avatarSrc="https://i.pravatar.cc/64?img=47"
+              actionLabel="アカウントを切り替える"
+              onAction={() => {}}
+            />
+            <AuthAccountSummary
+              email="taro.suzuki@example.co.jp"
+              avatarFallback="鈴"
+              actionLabel="アカウントを切り替える"
+              onAction={() => {}}
+            />
+            <AuthAccountSummary
+              email="operations@example.co.jp"
+              actionLabel="アカウントを切り替える"
+              onAction={() => {}}
+            />
+          </AuthStack>
+        </CardContent>
+      </Card>
+
+      <Card>
+        <CardHeader>
+          <CardTitle level={2}>無効状態</CardTitle>
+          <CardDescription>
+            アクションだけが無効になります。アドレスは引き続き選択・読み上げできます。
+          </CardDescription>
+        </CardHeader>
+        <CardContent>
+          <AuthStack>
+            <AuthAccountSummary
+              email="locked.account@example.co.jp"
+              actionLabel="切り替えできません"
+              onAction={() => {}}
+              disabled
+            />
+          </AuthStack>
+        </CardContent>
+      </Card>
+
+      <Card>
+        <CardHeader>
+          <CardTitle level={2}>長いアドレスと多言語</CardTitle>
+          <CardDescription>
+            省略記号で切り詰めても、ベトナム語の声調記号とラテン文字のディセンダーが欠けないことを
+            確認します。ホバーで全文をtitle属性から参照できます。
+          </CardDescription>
+        </CardHeader>
+        <CardContent>
+          <AuthStack>
+            <AuthAccountSummary
+              email="very.long.authoritative.account.address@example.enterprise.invalid"
+              actionLabel="アカウントを切り替える"
+              onAction={() => {}}
+            />
+            <AuthAccountSummary
+              email="phuong.nguyen.quynh@doanhnghiep.example.vn"
+              avatarFallback="Ph"
+              actionLabel="Chuyển đổi tài khoản"
+              onAction={() => {}}
+            />
+            <AuthAccountSummary
+              email="jennifer.pettigrew@enterprise-security.example.com"
+              avatarFallback="JP"
+              actionLabel="Switch account"
+              onAction={() => {}}
+            />
+          </AuthStack>
+        </CardContent>
+      </Card>
+    </PageContainer>
+  );
+}

package/docs/layout/auth-divider.tsx

@@ -0,0 +1,28 @@
+import { Card, CardContent, CardDescription, CardHeader, CardTitle } from "@godxjp/ui/data-display";
+import { AuthDivider, AuthStack, PageContainer } from "@godxjp/ui/layout";
+
+/**
+ * AuthDivider — localized conjunction between equal separator rules. The label remains visible and
+ * centred under long Japanese, English and RTL content.
+ */
+export default function Demo() {
+  return (
+    <PageContainer title="AuthDivider" subtitle="認証手段を分けるローカライズ済み区切り">
+      <Card>
+        <CardHeader>
+          <CardTitle level={2}>言語とcontent stress</CardTitle>
+          <CardDescription>区切り線はlabelの長さに応じて同じ比率で縮みます。</CardDescription>
+        </CardHeader>
+        <CardContent>
+          <AuthStack>
+            <AuthDivider label="または" />
+            <AuthDivider label="or continue with your organization account" />
+            <div dir="rtl">
+              <AuthDivider label="أو تابع باستخدام حساب المؤسسة" />
+            </div>
+          </AuthStack>
+        </CardContent>
+      </Card>
+    </PageContainer>
+  );
+}

package/docs/layout/auth-footer.tsx

@@ -0,0 +1,37 @@
+import { Card, CardContent, CardDescription, CardHeader, CardTitle } from "@godxjp/ui/data-display";
+import { Button } from "@godxjp/ui/general";
+import { AuthFooter, AuthStack, PageContainer } from "@godxjp/ui/layout";
+
+/**
+ * AuthFooter — shared hosted-identity legal line. Every item remains consumer-owned React content,
+ * allowing real links and locale controls without the layout component inventing navigation.
+ */
+export default function Demo() {
+  return (
+    <PageContainer title="AuthFooter" subtitle="製品名 · 規約 · プライバシー · 言語">
+      <Card>
+        <CardHeader>
+          <CardTitle level={2}>認証画面の法務フッター</CardTitle>
+          <CardDescription>
+            localeは任意です。リンク先と遷移方法はconsumerが所有します。
+          </CardDescription>
+        </CardHeader>
+        <CardContent>
+          <AuthStack>
+            <AuthFooter
+              product="Acme Identity"
+              terms={<a href="#terms">利用規約</a>}
+              privacy={<a href="#privacy">プライバシー</a>}
+              locale={
+                <Button type="button" variant="ghost" size="sm">
+                  日本語
+                </Button>
+              }
+            />
+            <AuthFooter product="Godx ID" terms="Terms" privacy="Privacy" />
+          </AuthStack>
+        </CardContent>
+      </Card>
+    </PageContainer>
+  );
+}

package/docs/layout/auth-identity.tsx

@@ -0,0 +1,36 @@
+import { Card, CardContent, CardDescription, CardHeader, CardTitle } from "@godxjp/ui/data-display";
+import { AuthAccountSummary, AuthIdentity, AuthStack, PageContainer } from "@godxjp/ui/layout";
+
+/**
+ * AuthIdentity — canonical identity title with optional relying-party request context. The
+ * requester line is consumer data and may be omitted for first-party authentication.
+ */
+export default function Demo() {
+  return (
+    <PageContainer title="AuthIdentity" subtitle="ホストIDと依頼元サービスのコンテキスト">
+      <Card>
+        <CardHeader>
+          <CardTitle level={2}>依頼元あり・なし</CardTitle>
+          <CardDescription>
+            外部サービスからの認証要求だけrequesterを表示し、通常ログインでは省略します。
+          </CardDescription>
+        </CardHeader>
+        <CardContent>
+          <AuthStack>
+            <AuthIdentity title="Godx IDにログイン" requester="勤怠管理が認証を要求しています" />
+            <AuthIdentity title="アカウントを確認" />
+            <AuthIdentity
+              title="Continue to Godx ID"
+              requester="Enterprise Security and Compliance Administration is requesting sign in"
+            />
+            <AuthAccountSummary
+              email="very.long.authoritative.account@example.enterprise.invalid"
+              actionLabel="アカウントを切り替える"
+              onAction={() => {}}
+            />
+          </AuthStack>
+        </CardContent>
+      </Card>
+    </PageContainer>
+  );
+}

package/docs/layout/auth-recovery/examples/mfa-challenge.md

@@ -0,0 +1,41 @@
+---
+title: Sign-in MFA challenge (5 states)
+viewport: 1440x2000
+---
+
+## otp · otp/error · otp/loading · recovery-code · passkey-failure
+
+This is the **sign-in challenge**. `TwoFactorSetup` is the **enrollment** Dialog (QR, manual key,
+recovery-code output) — a challenge has no secret to reveal and no dialog to dismiss, it _is_ the
+page. Reusing the enrollment dialog here is the anti-pattern this example exists to prevent.
+
+## Focus order (WAI-ARIA APG + WCAG 2.4.3)
+
+DOM order **is** the task order, so no `tabindex` is needed anywhere:
+
+1. the code field — one `InputOTP` (or one `Input` for a recovery code)
+2. the primary action — `Button fullWidth`
+3. fallback A
+4. fallback B
+
+The 6-slot row is **one field**, not six. `InputOTP` owns paste, arrow keys, backspace and the
+caret, and exposes a single focus stop; six `Input`s would put six stops in the tab ring and break
+paste of a 6-digit code — the single most common real-world MFA interaction.
+
+The error message is rendered by `FormField error` with `role="alert"` and wired as
+`aria-errormessage` on the field, which also carries `aria-invalid` — so a screen-reader user hears
+"wrong code" without leaving the field, and sighted users get the destructive slot borders. State is
+never signalled by colour alone (WCAG 1.4.1): the text is always there.
+
+## Loading
+
+`<Button loading loadingText="検証中…">` keeps the button's box while it is pending, so the panel
+never jumps mid-submit, and the input is `disabled` for the duration. The fallbacks are disabled
+too — a second verification must not race the first.
+
+## Fallback row
+
+`<Flex justify="between" gap="sm" wrap>` with two ghost buttons. The two fallbacks share one
+horizontal row while the localized labels fit the panel and **wrap to a stack** when they do not —
+a content-driven reflow, so it is correct for JA, EN and VI without a media query. See the
+long-label example.

package/docs/layout/auth-recovery/examples/mfa-challenge.tsx

@@ -0,0 +1,254 @@
+import { useState } from "react";
+
+import { Alert, AlertDescription, AlertTitle } from "@godxjp/ui/feedback";
+import { Card, CardContent, CardDescription, CardHeader, CardTitle } from "@godxjp/ui/data-display";
+import { FormField, Input, InputOTP, InputOTPGroup, InputOTPSlot } from "@godxjp/ui/data-entry";
+import { Button, Logo, Text } from "@godxjp/ui/general";
+import { AuthFooter, AuthShell, AuthStack, Flex } from "@godxjp/ui/layout";
+import { AppSettingPicker } from "@godxjp/ui/navigation";
+
+/**
+ * SIGN-IN MFA CHALLENGE — the three canonical SCR-008 states plus the error / loading paths,
+ * stacked at the real 432px measure.
+ *
+ * This is the SIGN-IN challenge, not enrollment. `TwoFactorSetup` is the enrollment Dialog (QR /
+ * manual key / recovery output) and must never be reused here: a challenge has no secret to reveal
+ * and no dialog to dismiss — it IS the page.
+ *
+ * FOCUS ORDER is DOM order, and DOM order is the task order:
+ *   1. the code field (OTP row / recovery-code Input)  2. the primary action
+ *   3. fallback A                                      4. fallback B
+ * The OTP row is ONE field — `InputOTP` owns paste, arrow keys and the caret; six separate
+ * `Input`s would put six stops in the tab ring and break paste.
+ *
+ * State coverage: otp (idle) · otp ERROR (wrong code) · otp LOADING (verifying) · recovery-code ·
+ * passkey-failure. The first panel owns the standalone frame's single `level={1}` heading; the
+ * remaining state sections use `level={2}`. A real route renders ONE panel at `level={1}`.
+ */
+export default function Demo() {
+  const [code, setCode] = useState("");
+  const [wrongCode, setWrongCode] = useState("140228");
+  const [pendingCode, setPendingCode] = useState("482915");
+  const [recoveryCode, setRecoveryCode] = useState("");
+
+  return (
+    <AuthShell
+      variant="canonical"
+      preset="account-recovery"
+      brand={
+        <Flex align="center" gap="sm">
+          <Logo mark="godx" tone="success" />
+          <Text weight="medium">GoDX ID</Text>
+        </Flex>
+      }
+      footer={
+        <AuthFooter
+          product="GoDX ID"
+          terms="利用規約"
+          privacy="プライバシー"
+          locale={<AppSettingPicker kind="locale" appearance="labeled" compact />}
+        />
+      }
+    >
+      <Flex direction="col" gap="lg">
+        <Text size="xs" tone="muted" mono>
+          1 / 5 · otp · 認証アプリの 6 桁コード（1 行 6 スロット）
+        </Text>
+        <Card>
+          <CardHeader>
+            <CardTitle level={1}>二段階認証</CardTitle>
+            <CardDescription>
+              認証アプリに表示されている 6 桁のコードを入力してください。
+            </CardDescription>
+          </CardHeader>
+          <CardContent>
+            <AuthStack>
+              <FormField id="mfa-otp-idle" label="確認コード" required>
+                <InputOTP maxLength={6} pattern="^[0-9]+$" value={code} onChange={setCode}>
+                  <InputOTPGroup>
+                    <InputOTPSlot index={0} />
+                    <InputOTPSlot index={1} />
+                    <InputOTPSlot index={2} />
+                    <InputOTPSlot index={3} />
+                    <InputOTPSlot index={4} />
+                    <InputOTPSlot index={5} />
+                  </InputOTPGroup>
+                </InputOTP>
+              </FormField>
+              <Button fullWidth>確認する</Button>
+              <Flex justify="between" gap="sm" wrap>
+                <Button variant="ghost" size="sm">
+                  リカバリコードを使う
+                </Button>
+                <Button variant="ghost" size="sm">
+                  パスキーで再試行
+                </Button>
+              </Flex>
+            </AuthStack>
+          </CardContent>
+        </Card>
+
+        <Text size="xs" tone="muted" mono>
+          2 / 5 · otp（error）— コード不一致 · aria-invalid + role=alert
+        </Text>
+        <Card>
+          <CardHeader>
+            <CardTitle level={2}>二段階認証</CardTitle>
+            <CardDescription>
+              認証アプリに表示されている 6 桁のコードを入力してください。
+            </CardDescription>
+          </CardHeader>
+          <CardContent>
+            <AuthStack>
+              <FormField
+                id="mfa-otp-error"
+                label="確認コード"
+                error="コードが正しくありません。残り 4 回入力できます。"
+                required
+              >
+                <InputOTP
+                  maxLength={6}
+                  pattern="^[0-9]+$"
+                  value={wrongCode}
+                  onChange={setWrongCode}
+                >
+                  <InputOTPGroup>
+                    <InputOTPSlot index={0} />
+                    <InputOTPSlot index={1} />
+                    <InputOTPSlot index={2} />
+                    <InputOTPSlot index={3} />
+                    <InputOTPSlot index={4} />
+                    <InputOTPSlot index={5} />
+                  </InputOTPGroup>
+                </InputOTP>
+              </FormField>
+              <Button fullWidth>確認する</Button>
+              <Flex justify="between" gap="sm" wrap>
+                <Button variant="ghost" size="sm">
+                  リカバリコードを使う
+                </Button>
+                <Button variant="ghost" size="sm">
+                  パスキーで再試行
+                </Button>
+              </Flex>
+            </AuthStack>
+          </CardContent>
+        </Card>
+
+        <Text size="xs" tone="muted" mono>
+          3 / 5 · otp（loading）— 検証中 · 入力をロックし、ボタンの箱は動かさない
+        </Text>
+        <Card>
+          <CardHeader>
+            <CardTitle level={2}>二段階認証</CardTitle>
+            <CardDescription>コードを検証しています。しばらくお待ちください。</CardDescription>
+          </CardHeader>
+          <CardContent>
+            <AuthStack>
+              <FormField id="mfa-otp-loading" label="確認コード" required>
+                <InputOTP
+                  disabled
+                  maxLength={6}
+                  pattern="^[0-9]+$"
+                  value={pendingCode}
+                  onChange={setPendingCode}
+                >
+                  <InputOTPGroup>
+                    <InputOTPSlot index={0} />
+                    <InputOTPSlot index={1} />
+                    <InputOTPSlot index={2} />
+                    <InputOTPSlot index={3} />
+                    <InputOTPSlot index={4} />
+                    <InputOTPSlot index={5} />
+                  </InputOTPGroup>
+                </InputOTP>
+              </FormField>
+              <Button fullWidth loading loadingText="検証中…">
+                確認する
+              </Button>
+              <Flex justify="between" gap="sm" wrap>
+                <Button variant="ghost" size="sm" disabled>
+                  リカバリコードを使う
+                </Button>
+                <Button variant="ghost" size="sm" disabled>
+                  パスキーで再試行
+                </Button>
+              </Flex>
+            </AuthStack>
+          </CardContent>
+        </Card>
+
+        <Text size="xs" tone="muted" mono>
+          4 / 5 · recovery-code · 一度きりのリカバリコード（1 つのテキスト入力）
+        </Text>
+        <Card>
+          <CardHeader>
+            <CardTitle level={2}>リカバリコードを入力</CardTitle>
+            <CardDescription>
+              二段階認証の設定時に保存した、一度だけ使えるコードを入力してください。
+            </CardDescription>
+          </CardHeader>
+          <CardContent>
+            <AuthStack>
+              <FormField
+                id="mfa-recovery-code"
+                label="リカバリコード"
+                helper="ハイフンを含めて入力してください（例: 4f7c-92ab-30de）。"
+                required
+              >
+                <Input
+                  autoComplete="one-time-code"
+                  inputMode="text"
+                  spellCheck={false}
+                  placeholder="4f7c-92ab-30de"
+                  value={recoveryCode}
+                  onChange={(event) => setRecoveryCode(event.target.value)}
+                />
+              </FormField>
+              <Button fullWidth>確認する</Button>
+              <Flex justify="between" gap="sm" wrap>
+                <Button variant="ghost" size="sm">
+                  認証アプリに戻る
+                </Button>
+                <Button variant="ghost" size="sm">
+                  パスキーで再試行
+                </Button>
+              </Flex>
+            </AuthStack>
+          </CardContent>
+        </Card>
+
+        <Text size="xs" tone="muted" mono>
+          5 / 5 · passkey-failure · パスキー認証に失敗（destructive 通知 + 代替手段）
+        </Text>
+        <Card>
+          <CardHeader>
+            <CardTitle level={2}>パスキーで確認できませんでした</CardTitle>
+            <CardDescription>
+              このデバイスのパスキーを読み取れませんでした。別の方法で本人確認を続けられます。
+            </CardDescription>
+          </CardHeader>
+          <CardContent>
+            <AuthStack>
+              <Alert tone="destructive">
+                <AlertTitle>パスキーの認証がキャンセルされました</AlertTitle>
+                <AlertDescription>
+                  デバイスのロック解除が完了しなかったか、対応するパスキーが見つかりませんでした。
+                </AlertDescription>
+              </Alert>
+              <Button fullWidth>パスキーで再試行</Button>
+              <Flex justify="between" gap="sm" wrap>
+                <Button variant="ghost" size="sm">
+                  認証アプリのコードを使う
+                </Button>
+                <Button variant="ghost" size="sm">
+                  リカバリコードを使う
+                </Button>
+              </Flex>
+            </AuthStack>
+          </CardContent>
+        </Card>
+      </Flex>
+    </AuthShell>
+  );
+}

package/docs/layout/auth-recovery/examples/mobile-390.md

@@ -0,0 +1,25 @@
+--- title: Viewport 390x844 viewport: 390x844 ---
+
+## The 390 reference image is NOT a valid source
+
+It overflows and crops horizontally: the two 432px panels are still laid out side by side. It shows no mobile route, no mobile gutter and no reflow, and it was **not traced**. Accepting its cropped overflow as "intended mobile behaviour" would ship a broken screen with a canonical signature on it, so the issue's own words apply: _a route-level mobile reference or an explicit responsive contract is required_.
+
+What follows is that **explicit contract**, decided in the library and enforced by tokens + tests.
+
+## The contract at ≤ 30rem
+
+| Aspect            | Contract                                                                                                                                     |
+| ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
+| Page gutter       | `--auth-shell-recovery-main-padding-mobile` = **15px inline** ⇒ panel `x=15, width=360` at a 390 viewport.                                   |
+| Why 15px          | It is the canonical **Login** mobile gutter (`--auth-shell-canonical-main-padding-mobile`). Login → Recovery must not make the surface jump. |
+| Panel measure     | `min(100%, 27rem)`. 432px is a **max**-width, so the panel simply becomes 360px — it is never scaled, cropped or scrolled.                   |
+| Card inset        | Unchanged (24px, `--auth-shell-compact-card-inset`) ⇒ a **310px** content column.                                                            |
+| OTP row           | Stays **one row of 6 slots**: 6 × 36px = **216px** ≤ 310px. Slots are never shrunk and the row never scrolls.                                |
+| Primary action    | `Button fullWidth` — spans the panel at every width.                                                                                         |
+| Fallback row      | Wraps to a **stack** when the two localized labels exceed the content column; otherwise it stays one row. Content-driven, no media query.    |
+| Title/description | Stay inside the bordered surface; long JA/VI strings wrap inside the 310px column and grow the panel's height.                               |
+| Vertical          | The column stays centred; when the panel is taller than the viewport the shell scrolls from the top — the top of the panel is never clipped. |
+
+## Not defined here
+
+Anything the reference could have specified but did not — a mobile-specific type ramp, a sticky bottom action bar, a full-bleed edge-to-edge panel — is **deliberately absent**. Inventing it would be fabricating a canonical. If SCR-008 later ships a real 390 route artboard and it disagrees with the table above, the fix is a token retune (or a new preset), not consumer CSS.

package/docs/layout/auth-recovery/examples/mobile-390.tsx

@@ -0,0 +1,82 @@
+import { useState } from "react";
+
+import { Card, CardContent, CardDescription, CardHeader, CardTitle } from "@godxjp/ui/data-display";
+import { FormField, InputOTP, InputOTPGroup, InputOTPSlot } from "@godxjp/ui/data-entry";
+import { Button, Logo, Reveal, Text } from "@godxjp/ui/general";
+import { AuthFooter, AuthShell, AuthStack, Flex } from "@godxjp/ui/layout";
+import { AppSettingPicker } from "@godxjp/ui/navigation";
+
+/**
+ * Viewport fixture — 390x844 (mobile). THE MOBILE CONTRACT, decided here.
+ *
+ * ⚠️ The 390 canonical reference supplied with gh#233 is a desktop 2x2 COMPOSITE that overflows and
+ * crops horizontally. It is not a route-level mobile artboard and it was NOT traced. The behaviour
+ * below is a decided, documented contract — see the Overview page.
+ *
+ * At <=30rem the `account-recovery` preset switches its page gutter to
+ * `--auth-shell-recovery-main-padding-mobile` (15px inline), so the panel is x=15, width=360 — the
+ * SAME page rhythm as the canonical Login flow, so moving from Login to Recovery on a phone never
+ * makes the surface jump. The panel keeps its full 24px card inset, giving a 310px content column;
+ * the 6-slot OTP row (6 x 36px = 216px) fits that column at every supported width with no scroll,
+ * no shrunken slots and no horizontal overflow.
+ */
+export default function Demo() {
+  const [code, setCode] = useState("");
+
+  return (
+    <AuthShell
+      variant="canonical"
+      preset="account-recovery"
+      brand={
+        <Flex align="center" gap="sm">
+          <Logo mark="godx" tone="success" />
+          <Text weight="medium">GoDX ID</Text>
+        </Flex>
+      }
+      footer={
+        <AuthFooter
+          product="GoDX ID"
+          terms="利用規約"
+          privacy="プライバシー"
+          locale={<AppSettingPicker kind="locale" appearance="labeled" compact />}
+        />
+      }
+    >
+      <Reveal>
+        <Card>
+          <CardHeader>
+            <CardTitle level={1}>二段階認証</CardTitle>
+            <CardDescription>
+              認証アプリに表示されている 6 桁のコードを入力してください。
+            </CardDescription>
+          </CardHeader>
+          <CardContent>
+            <AuthStack>
+              <FormField id="mfa-code-mobile" label="確認コード" required>
+                <InputOTP maxLength={6} pattern="^[0-9]+$" value={code} onChange={setCode}>
+                  <InputOTPGroup>
+                    <InputOTPSlot index={0} />
+                    <InputOTPSlot index={1} />
+                    <InputOTPSlot index={2} />
+                    <InputOTPSlot index={3} />
+                    <InputOTPSlot index={4} />
+                    <InputOTPSlot index={5} />
+                  </InputOTPGroup>
+                </InputOTP>
+              </FormField>
+              <Button fullWidth>確認する</Button>
+              <Flex justify="between" gap="sm" wrap>
+                <Button variant="ghost" size="sm">
+                  リカバリコードを使う
+                </Button>
+                <Button variant="ghost" size="sm">
+                  パスキーで再試行
+                </Button>
+              </Flex>
+            </AuthStack>
+          </CardContent>
+        </Card>
+      </Reveal>
+    </AuthShell>
+  );
+}

package/docs/layout/auth-recovery/examples/password-recovery.md

@@ -0,0 +1,24 @@
+--- title: Password recovery (4 states) viewport: 1440x1700 ---
+
+## request · sent · new-password · expired
+
+One anatomy, four states. Nothing below the `Card` changes shape — only the **notice**, the **fields** and the copy:
+
+| State          | Notice                     | Fields                                             | Primary                               | Fallback row                          |
+| -------------- | -------------------------- | -------------------------------------------------- | ------------------------------------- | ------------------------------------- |
+| `request`      | —                          | email (`autoComplete="username"`)                  | send reset link                       | back to sign-in · contact support     |
+| `sent`         | `Alert tone="success"`     | —                                                  | resend (**disabled** during cooldown) | back to sign-in · use another address |
+| `new-password` | —                          | new + confirm `PasswordInput` + `PasswordStrength` | update password                       | back to sign-in                       |
+| `expired`      | `Alert tone="destructive"` | —                                                  | request a new link                    | back to sign-in · contact support     |
+
+## What is presentation and what is not
+
+The panel renders **only** what the consumer passes it. It does **not** know reset semantics: no route, no token lifetime, no "is this link still valid" decision, no password policy. The `sent` panel prints the masked address the **server** sent (`h*****@example.co.jp`) — the library never reconstructs an identifier from an email.
+
+## Error, loading and disabled
+
+- **Error** — `FormField error` puts `aria-invalid` + `aria-errormessage` on the control and renders the message with `role="alert"`. The confirm field above shows the canonical mismatch case. - **Disabled** — a resend cooldown is `<Button disabled>`. Never a hidden button: the affordance stays visible so the user knows resending is possible, just not yet. - **Loading** — `<Button loading loadingText="…">` (demonstrated in the MFA example).
+
+## Heading level
+
+A real route renders **one** panel and its `CardTitle` is the page `h1`. The four panels are stacked here at `level={2}` under a caption line purely so the states can be compared at an identical measure — do not copy `level={2}` into a route that has no other heading.