@godxjp/ui 19.0.0 → 19.2.0

package/docs/layout/error-surface/index.md

@@ -0,0 +1,153 @@
+--- title: Overview ---
+
+# Error surface — 403 / 404 / 500 / 503
+
+`ErrorSurface` is a **package-owned, importable component** (`@godxjp/ui/layout`). It owns the four HTTP exception pages every application ships, including their responsive geometry, so no app re-implements them from a generic `Card` in the wrong shell.
+
+```tsx
+import { ErrorSurface } from "@godxjp/ui/layout";
+```
+
+## History — why this is a component (gh#221 → gh#251)
+
+#221 first shipped this surface as a **documentation-only composition pattern**: the
+Framework-Component Test was run, it was judged a composition, and the package shipped two shells,
+some tokens and a docs page instead of an export. That was wrong in outcome, and #251 is the proof:
+**a consumer cannot `import` a docs page.** A clean install of 18.5.0 exposed no `ErrorSurface`, so
+DXS Platform was still forced to compose `AuthShell` + a generic `Card` behind a consumer-local
+`.canonical-auth-card` — exactly what the API-first rule forbids. The consumer requirement settles
+the question: the surface ships as a real export.
+
+Two things that analysis got right are preserved verbatim in the component's design:
+
+- **A component cannot manufacture the application shell.** Nav sections, product identity and the user menu are consumer-owned data. So `mode="application"` does not build chrome — it defines _where the surface goes_ (see below), and the surface renders only its own block. - **Exactly one recovery action** stays structural — one slot, extras dropped.
+
+## `mode` is the shell contract, not a skin
+
+| `mode`          | Status    | What the component renders                                          | What you provide                                                     |
+| --------------- | --------- | ------------------------------------------------------------------- | -------------------------------------------------------------------- |
+| `"application"` | 403 · 404 | **Only the surface block.** No shell, no landmark, no page geometry | The `AppShell` (usually + `PageContainer`) the route already renders |
+| `"system"`      | 500 · 503 | **The whole page** — `CenteredShell align="center"` + the surface   | Nothing. No `min-h-dvh`, no flex-centring class, no media query      |
+
+> **`mode="application"` means "this is what you put in AppShell's children".** The session is
+> valid, so the sidebar, topbar and breadcrumb stay mounted and the user can navigate away. The
+> surface never reconstructs them.
+>
+> **`mode="system"` means "the app itself failed".** Session and nav data may be gone, so the
+> surface owns the page. `AuthShell` is never an option: it is the UNAUTHENTICATED root and imposes
+> auth-card geometry.
+
+## API
+
+```tsx
+<ErrorSurface
+  mode="application" | "system"     // required — the shell contract above
+  status={403 | 404 | 500 | 503}    // required — drives the default icon + tone
+  title={t("errors.403.title")}     // required — consumer-owned copy
+  description={t("errors.403.body")}
+  action={<Button>{t("errors.backHome")}</Button>}  // required — EXACTLY ONE
+
+  // optional semantic metadata slots (each renders as a <dt>/<dd> pair)
+  requestId="01J9Z0M7Q2K5S7WQ3T5N8V2H4B"
+  permission="reports.view"
+  organization="Acme KK"
+  maintenance={{ start, end, timeZone, progress }}  // ISO-8601 + IANA + 0–100
+
+  // optional overrides / system-mode slots
+  icon={LifeBuoy} tone="warning" titleLevel={2}
+  brand={<Logo glyph="G" />} footer={<Text size="xs">2026 GodX</Text>} width="sm"
+  id className ref
+/>
+```
+
+- **`status` is the input, not a lookup you write.** It selects the icon (`ShieldAlert` 403 ·
+  `SearchX` 404 · `ServerCrash` 500 · `Wrench` 503) and the tone (`warning` 403/503 · `muted` 404 ·
+  `destructive` 500). Override either only for a truer product glyph, never to recolour a severity.
+- **`action` is exactly one.** A single slot is the enforcement; pass a fragment with two buttons
+  and only the first renders, with a development-time error. Support contact belongs in
+  `description`, not in a second CTA.
+- **`titleLevel` defaults per mode** — `2` in `application` (a `PageContainer` `h1` sits above),
+  `1` in `system` (the surface IS the page). Override only to fit a deeper outline.
+- **Product copy stays consumer-owned.** `title` / `description` / `action` come from the app's own
+  `t()`. The surface localizes only its OWN metadata labels ("Request ID", "Required permission",
+  "Organization", "Scheduled maintenance", "Maintenance progress").
+
+## Metadata slots — semantic, not sentences
+
+Each slot renders a real `<dt>`/`<dd>` pair inside a `<dl>`, so the label↔value relationship
+survives for a screen reader instead of collapsing into a colon in a paragraph. Omit them all and
+the list is not rendered at all.
+
+| Slot                    | Why it exists                                                                                                                                                                    |
+| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `requestId`             | Support correlation id. Mono + tabular so it can be read out or copied accurately.                                                                                               |
+| `permission`            | The missing role (403). Distinguishes "you need a role" from a generic refusal.                                                                                                  |
+| `organization`          | The tenant the request was scoped to. Distinguishes a wrong-workspace 403 from a missing-role one.                                                                               |
+| `maintenance.start/end` | ISO-8601 instants + an IANA `timeZone`, formatted by `Intl.DateTimeFormat(...).formatRange()`. The visible text is CLDR; `<time dateTime>` keeps the machine-readable ISO value. |
+| `maintenance.progress`  | 0–100, rendered as a labelled `Progress` meter with an `Intl.NumberFormat` percent name — never colour-only.                                                                     |
+
+**Never hand-build a window** (`"18:00 - 20:00 JST"`): it cannot localize. **Never derive
+`progress` from the client clock**: SSR and hydration would disagree, and an exception page must be
+readable before hydration.
+
+## Accessibility
+
+- **Status code is announced as a phrase.** The visible digits are `aria-hidden`; an `sr-only`
+  sibling carries "HTTP status 403", because a bare "403" is read as the cardinal number
+  "four hundred three".
+- **Heading order stays valid** by default in both modes (see `titleLevel` above).
+- The single action is a real `Button`: standard visible focus ring, reachable by `Tab`, no
+  positive tabindex.
+- Verified at **0 axe violations** for all four statuses, in both shells, with metadata, and under
+  `dir="rtl"` (`src/components/layout/__tests__/error-surface.a11y.test.tsx`).
+
+## Package-owned geometry (1440 / 1024 / 390)
+
+No consumer `className`, media query or `min-h-dvh` is needed at any viewport.
+
+| Token                                   | Default                   | Owns                                                                                                                                                                   |
+| --------------------------------------- | ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `--error-surface-max-width`             | `32rem`                   | Measure of the whole surface block, in BOTH modes — so a long ja/vi headline wraps readably even inside a wide `PageContainer`.                                        |
+| `--error-surface-gap`                   | `--space-3`               | Rhythm between status code, body, metadata list and progress meter.                                                                                                    |
+| `--error-surface-padding-block`         | `--space-10`              | Block padding at the desktop steps (1440 / 1024).                                                                                                                      |
+| `--error-surface-padding-block-compact` | `--space-6`               | Block padding below the narrow step (the 390 case).                                                                                                                    |
+| `--error-surface-meta-gap` / `-row-gap` | `--space-1` / `--space-2` | Metadata row rhythm and the label↔value gap inside one row.                                                                                                            |
+| `--error-surface-meta-border`           | `none`                    | Divider above the metadata block. **Quiet by default (rule #44)** — a service opts in with `1px solid hsl(var(--border))`.                                             |
+| `--error-surface-progress-max-width`    | `18rem`                   | Progress meter measure, so it reads as metadata rather than as the page's primary content.                                                                             |
+| `--centered-shell-column-offset-block`  | `0` (`auto` when centred) | `system` mode only. `align="center"` centres the column in the `100dvh` shell; auto offsets collapse when content overflows, so tall copy scrolls instead of clipping. |
+| `--empty-state-description-max-width`   | `28rem`                   | Description measure — retune per service/locale instead of forking `.ui-empty-state-description`.                                                                      |
+
+The narrow step is a **container query on the surface's own width**, not a viewport query (the
+SplitPane precedent, gh#165): the surface compacts correctly whether the squeeze came from a 390px
+phone or from an application shell with an expanded sidebar. Below the step, metadata rows stack
+label-over-value instead of wrapping into a ragged two-column shape.
+
+## SSR / Inertia exception pages
+
+The surface has **no state, no effects and no portals**, so it renders fully server-side. Inertia
+delivers every exception through one `Error` page component that receives the HTTP `status`
+(Laravel `Handler::render()` → `Inertia::render('Error', ['status' => …])`), which maps onto
+`ErrorSurface` with a single expression:
+
+````tsx
+// resources/js/Pages/Error.tsx
+import { Button, Logo } from "@godxjp/ui/general";
+import { ErrorSurface } from "@godxjp/ui/layout";
+import { Link, router } from "@inertiajs/react";
+
+export default function Error({ status, requestId, }: { status: 403 | 404 | 500 | 503; requestId?: string; }) { const { t } = useTranslation(); // the APP's i18n — @godxjp/ui never owns product copy const isSystem = status >= 500;
+
+return ( <ErrorSurface mode={isSystem ? "system" : "application"} status={status} title={t(`errors.${status}.title`)} description={t(`errors.${status}.description`)} requestId={requestId} {...(isSystem ? { brand: <Logo glyph="G" /> } : {})} action={ isSystem ? ( <Button onClick={() => router.reload()}>{t("errors.reload")}</Button> ) : ( <Button asChild> <Link href="/">{t("errors.backHome")}</Link> </Button> ) } /> ); }
+
+// Persistent layout ⇒ 403/404 keep the authenticated shell (the sidebar is not re-mounted, scroll // and drawer state survive); 500/503 render standalone, because the surface owns the page. Error.layout = (page: React.ReactNode) => page.props.status < 500 ? <AuthenticatedLayout>{page}</AuthenticatedLayout> : page; ```
+
+SSR notes:
+
+- Send the maintenance window as **ISO-8601 from the server** with an explicit `timeZone`. Relying on the server's local zone makes SSR and client output diverge and React logs a hydration mismatch. - A 500 page must not import the app's data providers/query client — the failure may be inside them. `ErrorSurface` needs no provider beyond the `AppProvider` that supplies the locale.
+
+## Anti-patterns
+
+## The composition underneath
+
+`ErrorSurface` composes real primitives (`EmptyState` · `Text` · `Progress` · `CenteredShell`) and adds no bespoke markup you could not inspect. For a status outside the supported four, compose the same body by hand — that composition is pinned by `src/components/layout/__tests__/error-surface-pattern.test.tsx`, so it cannot break from underneath.
+````

package/docs/layout/error-surface/index.tsx

@@ -0,0 +1,239 @@
+import { Card, CardContent, CardHeader, CardTitle } from "@godxjp/ui/data-display";
+import { Button, Logo } from "@godxjp/ui/general";
+import { ErrorSurface, Flex, PageContainer, ResponsiveGrid } from "@godxjp/ui/layout";
+import { LifeBuoy, RotateCcw } from "lucide-react";
+
+/**
+ * ERROR SURFACE (403 · 404 · 500 · 503) — a real, importable component: `ErrorSurface`.
+ *
+ * `mode` is the SHELL CONTRACT, not a skin:
+ *   application (403/404) → the BODY you place inside the AppShell the route already renders
+ *   system      (500/503) → owns the page: CenteredShell align="center", package-owned geometry
+ *
+ * Every card below renders the surface in `application` mode, because a `system` surface is a full
+ * `100dvh` page and would swallow this catalogue page — see the Examples for the two real screens.
+ *
+ * Structure of the surface: status code (compact, mono/tabular, announced as "HTTP status 403")
+ * → icon · tone · title · description · EXACTLY ONE action → optional semantic metadata rows
+ * (request id · required permission · organization · maintenance window + progress).
+ */
+export default function Demo() {
+  return (
+    <PageContainer
+      title="Error surface"
+      subtitle="ErrorSurface · 403 / 404 / 500 / 503 · mode=application (AppShell body) vs mode=system (owns the page)"
+    >
+      <Flex direction="col" gap="lg">
+        <Card>
+          <CardHeader>
+            <CardTitle level={2}>status=403 · 権限なし（permission + organization）</CardTitle>
+          </CardHeader>
+          <CardContent>
+            <ErrorSurface
+              mode="application"
+              status={403}
+              titleLevel={3}
+              title="このページへのアクセス権限がありません"
+              description="管理者にレポート閲覧ロールの付与を依頼してください。"
+              permission="reports.view"
+              organization="株式会社ゴッドエックス"
+              action={<Button>ダッシュボードへ戻る</Button>}
+            />
+          </CardContent>
+        </Card>
+
+        <Card>
+          <CardHeader>
+            <CardTitle level={2}>status=404 · 未検出（メタデータなし）</CardTitle>
+          </CardHeader>
+          <CardContent>
+            {/* Every metadata slot omitted ⇒ the whole description list disappears. Metadata is
+                optional; the surface never renders an empty row or a dangling label. */}
+            <ErrorSurface
+              mode="application"
+              status={404}
+              titleLevel={3}
+              title="ページが見つかりません"
+              description="お探しのページは移動または削除された可能性があります。"
+              action={<Button>ダッシュボードへ戻る</Button>}
+            />
+          </CardContent>
+        </Card>
+
+        <Card>
+          <CardHeader>
+            <CardTitle level={2}>status=500 · リクエスト ID 付き</CardTitle>
+          </CardHeader>
+          <CardContent>
+            {/* Shown here in application mode so the card can contain it. In a real 500 page this
+                is mode="system" and the surface owns the whole viewport. */}
+            <ErrorSurface
+              mode="application"
+              status={500}
+              titleLevel={3}
+              title="問題が発生しました"
+              description="予期しないエラーが発生しました。担当チームに通知済みです。"
+              requestId="01J9Z0M7Q2K5S7WQ3T5N8V2H4B"
+              action={
+                <Button>
+                  <RotateCcw />
+                  再読み込み
+                </Button>
+              }
+            />
+          </CardContent>
+        </Card>
+
+        <Card>
+          <CardHeader>
+            <CardTitle level={2}>status=503 · メンテナンス時間帯 + 進捗</CardTitle>
+          </CardHeader>
+          <CardContent>
+            {/* ISO-8601 instants + an IANA zone in, Intl.DateTimeFormat.formatRange out. The
+                progress meter is server-sent (a client clock would break SSR hydration). */}
+            <ErrorSurface
+              mode="application"
+              status={503}
+              titleLevel={3}
+              title="サービスを一時的にご利用いただけません"
+              description="計画メンテナンスを実施しています。しばらくしてから再度お試しください。"
+              maintenance={{
+                start: "2026-08-02T18:00:00Z",
+                end: "2026-08-02T20:00:00Z",
+                timeZone: "Asia/Tokyo",
+                progress: 40,
+              }}
+              action={
+                <Button>
+                  <RotateCcw />
+                  再読み込み
+                </Button>
+              }
+            />
+          </CardContent>
+        </Card>
+
+        <Card>
+          <CardHeader>
+            <CardTitle level={2}>icon / tone / brand の上書き</CardTitle>
+          </CardHeader>
+          <CardContent>
+            {/* icon and tone DEFAULT from the status (500 ⇒ ServerCrash + destructive). Override
+                them only when the product has a truer glyph for the failure — never to recolour a
+                status into a different severity. `brand` is system-mode only and is ignored here. */}
+            <ErrorSurface
+              mode="application"
+              status={500}
+              titleLevel={3}
+              icon={LifeBuoy}
+              tone="warning"
+              brand={<Logo glyph="G" />}
+              title="復旧作業中です"
+              description="サポートチームが対応しています。復旧までしばらくお待ちください。"
+              action={<Button variant="outline">ステータスページを見る</Button>}
+            />
+          </CardContent>
+        </Card>
+
+        <Card>
+          <CardHeader>
+            <CardTitle level={2}>tone · セマンティックな重大度の 5 段階</CardTitle>
+          </CardHeader>
+          <CardContent>
+            {/* `tone` DEFAULTS from `status` (403/503 warning · 404 muted · 500 destructive). An
+                explicit tone is for the case where the product knows a TRUER severity than the
+                status code carries -- a planned window is informational, a resolved incident is a
+                success -- never to recolour one severity into another for decoration. All five
+                branches are rendered here so the whole axis is readable at rest. */}
+            <ResponsiveGrid columns={{ sm: 1, md: 3 }}>
+              <ErrorSurface
+                mode="application"
+                status={404}
+                tone="muted"
+                titleLevel={3}
+                title="ページが見つかりません"
+                description="リンクが古い可能性があります。中立な不在であり、障害ではありません。"
+                action={<Button variant="outline">ホームへ戻る</Button>}
+              />
+              <ErrorSurface
+                mode="application"
+                status={503}
+                tone="info"
+                titleLevel={3}
+                title="計画メンテナンスを実施しています"
+                description="事前告知済みの停止です。障害ではないため、警告ではなく情報として提示します。"
+                action={<Button variant="outline">ステータスページを見る</Button>}
+              />
+              <ErrorSurface
+                mode="application"
+                status={403}
+                tone="warning"
+                titleLevel={3}
+                title="この操作には承認が必要です"
+                description="権限を追加すれば同じ画面に戻れます。回復可能な状態です。"
+                action={<Button variant="outline">権限を申請する</Button>}
+              />
+              <ErrorSurface
+                mode="application"
+                status={500}
+                tone="destructive"
+                titleLevel={3}
+                title="問題が発生しました"
+                description="想定外の失敗です。利用者側の操作では回復できません。"
+                action={<Button variant="outline">再読み込み</Button>}
+              />
+              <ErrorSurface
+                mode="application"
+                status={503}
+                tone="success"
+                titleLevel={3}
+                title="復旧が完了しました"
+                description="最終確認を行っています。まもなく通常どおりご利用いただけます。"
+                action={<Button variant="outline">再読み込み</Button>}
+              />
+            </ResponsiveGrid>
+          </CardContent>
+        </Card>
+
+        {/* The same surface in ja / en / vi. The library-owned metadata LABELS ("Request ID") follow
+            the active app locale; the product copy is whatever the app's own t() returns. The
+            description measure is owned by --empty-state-description-max-width (28rem), and the
+            surface measure by --error-surface-max-width (32rem), so the longest locale wraps
+            instead of breaking the layout. */}
+        <Card>
+          <CardHeader>
+            <CardTitle level={2}>多言語オーバーフロー：ja / en / vi</CardTitle>
+          </CardHeader>
+          <CardContent>
+            <ResponsiveGrid columns={{ sm: 1, md: 3 }}>
+              <ErrorSurface
+                mode="application"
+                status={503}
+                titleLevel={3}
+                title="サービスを一時的にご利用いただけません"
+                description="計画メンテナンスを実施しています。しばらくしてから再度お試しください。"
+                action={<Button variant="outline">再読み込み</Button>}
+              />
+              <ErrorSurface
+                mode="application"
+                status={503}
+                titleLevel={3}
+                title="Service temporarily unavailable"
+                description="We are performing scheduled maintenance right now. Please try again in a few minutes."
+                action={<Button variant="outline">Reload</Button>}
+              />
+              <ErrorSurface
+                mode="application"
+                status={503}
+                titleLevel={3}
+                title="Dịch vụ tạm thời không khả dụng"
+                description="Chúng tôi đang bảo trì theo lịch. Vui lòng thử lại sau ít phút nữa."
+                action={<Button variant="outline">Tải lại</Button>}
+              />
+            </ResponsiveGrid>
+          </CardContent>
+        </Card>
+      </Flex>
+    </PageContainer>
+  );
+}

package/docs/layout/flex.tsx

@@ -0,0 +1,262 @@
+import {
+  Badge,
+  Card,
+  CardContent,
+  CardDescription,
+  CardHeader,
+  CardTitle,
+} from "@godxjp/ui/data-display";
+import { Button, Text } from "@godxjp/ui/general";
+import { Flex, PageContainer } from "@godxjp/ui/layout";
+
+/**
+ * Flex · canonical flex primitive (replaced Stack/Inline as named shortcuts).
+ * The default direction is "row" — matching the CSS `display:flex` initial value.
+ * Use direction="col" for vertical stacks (formerly Stack); direction="row" is the
+ * default for horizontal groups (formerly Inline). Keep spacing in gap prop · same
+ * token scale as Stack/Inline. align + justify expose cross-axis and main-axis control.
+ * wrap allows chip clusters and action rows to reflow. Composed only from real
+ * @godxjp/ui components.
+ */
+export default function Demo() {
+  return (
+    <PageContainer
+      title="Flex"
+      subtitle="方向・整列・間隔・折り返し · Stack/Inline を置き換えた汎用フレックスプリミティブ"
+    >
+      <Flex direction="col" gap="lg">
+        <Card>
+          <CardHeader>
+            <CardTitle level={2}>既定 direction=&quot;row&quot; · CSS 標準</CardTitle>
+            <CardDescription>
+              direction を省略すると row（CSS の display:flex の初期値）。横並びが既定で、
+              縦積みには direction=&quot;col&quot; を明示する。
+            </CardDescription>
+          </CardHeader>
+          <CardContent>
+            <Flex gap="sm" align="center">
+              <Badge variant="outline">借方</Badge>
+              <Badge variant="outline">貸方</Badge>
+              <Badge variant="outline">残高</Badge>
+            </Flex>
+          </CardContent>
+        </Card>
+
+        <Card>
+          <CardHeader>
+            <CardTitle level={2}>direction=&quot;col&quot; · 縦スタック</CardTitle>
+            <CardDescription>
+              縦積みは direction=&quot;col&quot; を明示する。gap
+              トークンで間隔を均一に制御。className で raw gap-* を使わない。
+            </CardDescription>
+          </CardHeader>
+          <CardContent>
+            <Flex direction="col" gap="sm">
+              <Card>
+                <CardContent>
+                  <Text tone="muted">行 1 · 仕訳入力</Text>
+                </CardContent>
+              </Card>
+              <Card>
+                <CardContent>
+                  <Text tone="muted">行 2 · 補助元帳</Text>
+                </CardContent>
+              </Card>
+              <Card>
+                <CardContent>
+                  <Text tone="muted">行 3 · 試算表</Text>
+                </CardContent>
+              </Card>
+            </Flex>
+          </CardContent>
+        </Card>
+
+        <Card>
+          <CardHeader>
+            <CardTitle level={2}>
+              direction=&quot;row&quot; + justify=&quot;between&quot; · ツールバー
+            </CardTitle>
+            <CardDescription>
+              カードヘッダー内でタイトルとアクションを左右に配置する典型パターン。
+            </CardDescription>
+          </CardHeader>
+          <CardContent>
+            <Flex direction="row" gap="sm" align="center" justify="between">
+              <Text weight="medium">請求書一覧</Text>
+              <Flex direction="row" gap="xs" align="center">
+                <Button variant="outline" size="sm">
+                  エクスポート
+                </Button>
+                <Button size="sm">新規作成</Button>
+              </Flex>
+            </Flex>
+          </CardContent>
+        </Card>
+
+        <Card>
+          <CardHeader>
+            <CardTitle level={2}>
+              align=&quot;center&quot; + justify=&quot;center&quot; · センタリング
+            </CardTitle>
+            <CardDescription>
+              空状態やローディングブロックを両軸で中央揃えにする用途。
+            </CardDescription>
+          </CardHeader>
+          <CardContent>
+            <Flex direction="col" align="center" justify="center" gap="sm" className="min-h-32">
+              <Text tone="muted">データがありません</Text>
+              <Button variant="outline" size="sm">
+                インポート
+              </Button>
+            </Flex>
+          </CardContent>
+        </Card>
+
+        <Card>
+          <CardHeader>
+            <CardTitle level={2}>align · 交差軸の整列（全 5 値）</CardTitle>
+            <CardDescription>
+              direction=&quot;row&quot; の交差軸（縦方向）の揃え方。高さの異なる子要素で
+              start・center・end・baseline・stretch の違いを比較。baseline はテキストの
+              ベースライン、stretch は子要素を行の高さまで引き伸ばす。
+            </CardDescription>
+          </CardHeader>
+          <CardContent>
+            <Flex direction="col" gap="md">
+              {(["start", "center", "end", "stretch", "baseline"] as const).map((a) => (
+                <Flex
+                  key={a}
+                  direction="row"
+                  gap="sm"
+                  align={a}
+                  className="bg-muted min-h-20 rounded-md p-2"
+                >
+                  <Text size="xs" tone="muted" className="w-16">
+                    {a}
+                  </Text>
+                  <Badge variant="outline">短</Badge>
+                  <Text>標準テキスト</Text>
+                  <Text size="2xl" weight="bold">
+                    大
+                  </Text>
+                </Flex>
+              ))}
+            </Flex>
+          </CardContent>
+        </Card>
+
+        <Card>
+          <CardHeader>
+            <CardTitle level={2}>justify · 主軸の配置（全 6 値）</CardTitle>
+            <CardDescription>
+              direction=&quot;row&quot; の主軸（横方向）の配置。固定幅トラックで余白の
+              分配を比較。between は端寄せ、around は各要素の周囲、evenly は要素間と端を
+              すべて均等にする。
+            </CardDescription>
+          </CardHeader>
+          <CardContent>
+            <Flex direction="col" gap="md">
+              {(["start", "center", "end", "between", "around", "evenly"] as const).map((j) => (
+                <Flex key={j} direction="row" gap="sm" align="center">
+                  <Text size="xs" tone="muted" className="w-16">
+                    {j}
+                  </Text>
+                  <Flex
+                    direction="row"
+                    gap="xs"
+                    align="center"
+                    justify={j}
+                    className="bg-muted flex-1 rounded-md p-2"
+                  >
+                    <Badge variant="outline">借方</Badge>
+                    <Badge variant="outline">貸方</Badge>
+                    <Badge variant="outline">残高</Badge>
+                  </Flex>
+                </Flex>
+              ))}
+            </Flex>
+          </CardContent>
+        </Card>
+
+        <Card>
+          <CardHeader>
+            <CardTitle level={2}>wrap · 折り返しの有無を比較</CardTitle>
+            <CardDescription>
+              wrap=&#123;true&#125;（既定の false に対して）。狭いトラックで折り返しの有無を
+              並べて比較。false では子要素が一行に圧縮され、true では次行へ流れる。
+            </CardDescription>
+          </CardHeader>
+          <CardContent>
+            <Flex direction="row" gap="md" align="start" wrap>
+              <Flex direction="col" gap="xs" className="w-44">
+                <Text size="xs" tone="muted">
+                  wrap=&#123;false&#125;（既定）
+                </Text>
+                <Flex direction="row" gap="xs" wrap={false} className="bg-muted rounded-md p-2">
+                  <Badge variant="outline">勘定科目</Badge>
+                  <Badge variant="outline">補助科目</Badge>
+                  <Badge variant="outline">部門</Badge>
+                </Flex>
+              </Flex>
+              <Flex direction="col" gap="xs" className="w-44">
+                <Text size="xs" tone="muted">
+                  wrap=&#123;true&#125;
+                </Text>
+                <Flex direction="row" gap="xs" wrap className="bg-muted rounded-md p-2">
+                  <Badge variant="outline">勘定科目</Badge>
+                  <Badge variant="outline">補助科目</Badge>
+                  <Badge variant="outline">部門</Badge>
+                </Flex>
+              </Flex>
+            </Flex>
+          </CardContent>
+        </Card>
+
+        <Card>
+          <CardHeader>
+            <CardTitle level={2}>wrap · バッジ・チップクラスター</CardTitle>
+            <CardDescription>
+              direction=&quot;row&quot; + wrap=&#123;true&#125; でタグ・ステータスバッジが折り返す。
+              gap トークンで均一スペーシング。
+            </CardDescription>
+          </CardHeader>
+          <CardContent>
+            <Flex direction="row" wrap gap="xs" align="center">
+              <Badge tone="success">承認済</Badge>
+              <Badge tone="warning">保留中</Badge>
+              <Badge tone="info">確認待ち</Badge>
+              <Badge tone="destructive">却下</Badge>
+              <Badge variant="secondary">下書き</Badge>
+              <Badge variant="outline">アーカイブ</Badge>
+              <Badge>既定</Badge>
+              <Badge tone="neutral">中立</Badge>
+            </Flex>
+          </CardContent>
+        </Card>
+
+        <Card>
+          <CardHeader>
+            <CardTitle level={2}>gap トークンスケール</CardTitle>
+            <CardDescription>
+              xs · sm · md（既定）· lg · xl。raw gap-* / space-* ユーティリティは使わない。
+            </CardDescription>
+          </CardHeader>
+          <CardContent>
+            <Flex direction="col" gap="md">
+              {(["xs", "sm", "md", "lg", "xl"] as const).map((g) => (
+                <Flex key={g} direction="row" gap={g} align="center">
+                  <Text size="xs" tone="muted" className="w-6">
+                    {g}
+                  </Text>
+                  <Badge variant="outline">勘定科目</Badge>
+                  <Badge variant="outline">補助科目</Badge>
+                  <Badge variant="outline">部門</Badge>
+                </Flex>
+              ))}
+            </Flex>
+          </CardContent>
+        </Card>
+      </Flex>
+    </PageContainer>
+  );
+}