@godxjp/ui 28.5.0 → 28.7.0

package/dist/tokens/components/form.css

@@ -10,6 +10,8 @@
 
   --form-block-gap: var(--space-4);
 
+  --form-feedback-icon-size: var(--icon-size-sm);
+
   --form-field-row-gap: var(--space-3);
 
   --form-grid-row-gap: var(--form-field-row-gap);

package/dist/tokens/components/navigation.css

@@ -187,6 +187,8 @@
   --app-setting-picker-density-width: 10rem;
   --app-setting-picker-font-size-width: 9rem;
 
+  --app-setting-picker-trigger-width: auto;
+
   --app-setting-picker-width-breakpoint: 40rem;
   --app-setting-picker-bar-border-width: 0;
   --app-setting-picker-bar-shadow: none;

package/docs/COMPOSITION-VS-COMPONENT.md

@@ -77,6 +77,7 @@ new UI need
 | `Select` (incl. search/async)                           | ✅  | ✅  | ✅  | ✅  | ✅  | ✅  | ✅  | **Framework component**                                                  |
 | `DataTable`, `Dialog`, `Calendar`, `Switch`, `Combobox` | ✅  | ✅  | ✅  | ✅  | ✅  | ✅  | ✅  | **Framework component**                                                  |
 | `StatCard` (+ `icon`)                                   | ✅  | ➖  | ✅  | ✅  | ✅  | ✅  | ✅  | **Framework component** (a reusable KPI tile with a stable API + tokens) |
+| `ServiceLauncherCard`                                   | ➖  | ❌  | ❌  | ✅  | ✅  | ➖  | ➖  | **Composition by the test — RETAINED as a recorded exception** (gh#814) |
 | Marketing **Hero**                                      | ❌  | ❌  | ❌  | ❌  | ❌  | ❌  | ❌  | **Composition** — section, static, composable, brand-specific            |
 | **Navbar** / **Footer**                                 | ❌  | ❌  | ❌  | ❌  | ❌  | ❌  | ❌  | **Composition** — layout of `Text`/`Button`/`Flex`                       |
 | **PricingTable** / feature grid                         | ❌  | ❌  | ❌  | ❌  | ❌  | ❌  | ❌  | **Composition** — `ResponsiveGrid` + `Card`                              |
@@ -85,6 +86,8 @@ new UI need
 
 `✅ pass · ❌ fail · ➖ borderline`. **StatCard** is the instructive borderline: C2 is weak (it owns little behavior), but it is a universal KPI tile with a controlled API, fully tokenized, broadly reused — so it earns its place. A **Hero** fails six of seven; it is unambiguously a composition.
 
+**ServiceLauncherCard is the ONE recorded exception, and it is recorded so that it stays one.** It shipped before the test was run against it, and when the test was run it came back with two hard FAILs: **C2** — no state, no keyboard handling, no focus management, its only ARIA three static attributes — and **C3** — its own imports are `Card` + `CardContent` + `Badge` + a Lucide glyph, so "could I build this right now from primitives?" is yes. By §2 that makes it a composition pattern. It is kept anyway because `src/components/layout/app-launcher.tsx` consumes it: it is an internal building block of a component that **does** pass, so the question was never "should it exist" but "should it be PUBLIC", and removing a public export is breaking. Keeping it public was the cheaper call and the ledger lives on gh#814 and at the top of `src/components/data-display/service-launcher-card.tsx`. **Consumers should compose `Card` + `Badge` for a service tile** — reach for `ServiceLauncherCard` only to match `AppLauncher`'s own tiles — and this row is not precedent for adding another static tile to `src/components/`.
+
 ---
 
 ## 4. How to build a composition pattern correctly

package/docs/DESIGN-AUTHORITY.md

@@ -648,11 +648,31 @@ because removing it would break the contents anchor.
 
 **Every other focusable non-interactive element in this library is a genuinely scrollable region**
 — `.app-main`, `.ui-mobile-shell-main`, `.ui-timeline-grid`, `.ui-code-block` when it overflows,
-MasterDetail's bounded master, the DataTable and Table scroll containers, ScrollArea, and the
-BranchScopePicker list. Each carries `tabIndex={0}` for axe `scrollable-region-focusable` and must
-stay reachable, so each keeps BOTH halves rather than becoming focusable-but-unpainted. The region
-ring (`--region-focus-ring-width`, off by default) now also multiplies by `--focus-outline`, so a
-service that opts it in still cannot paint while the library-wide switch is off.
+MasterDetail's bounded master, the DataTable and Table scroll containers when they overflow,
+ScrollArea, and the BranchScopePicker list. Each carries `tabIndex={0}` for axe
+`scrollable-region-focusable` and must stay reachable, so each keeps BOTH halves rather than
+becoming focusable-but-unpainted. The region ring (`--region-focus-ring-width`, off by default) now
+also multiplies by `--focus-outline`, so a service that opts it in still cannot paint while the
+library-wide switch is off.
+
+### A focusable scroll region is ROLED and NAMED, and only exists while it scrolls (gh#817)
+
+Reaching the overflow is half the contract; knowing what you reached is the other half. A stop with
+no role and no accessible name announces nothing at all, which is why `godx-jp/id` found `Table`'s
+wrapper sitting at tab stop 27 as a bare `<div tabindex="0">`. So the Table and DataTable scroll
+containers carry `role="group"` plus a name that defaults to the localized `dataTable.scrollRegion`
+— a consumer is never forced to invent one per table, and `label` overrides it per instance.
+
+`group`, not `region`: a NAMED `region` is a landmark, so a page with three tables would ship three
+identically-named landmarks and fail axe `landmark-unique`. That collision is the reason the role
+was left off in the first place; `group` is announced, takes a name, and is not a landmark.
+
+And all three attributes are withheld until the box provably overflows (`useScrollsHorizontally`,
+`src/lib/hooks.ts`) — a focus stop that scrolls nothing is noise. The measurement may only ever
+REMOVE the stop: an unlaid-out box reports `clientWidth === 0` (SSR, jsdom, a `display:none`
+ancestor), and reading that as "nothing overflows" would strand the overflow from every keyboard
+user, a worse failure than the extra stop. Gated by
+`src/components/data-display/__tests__/table-scroll-region-a11y-817.test.tsx`.
 
 ## How a decision gets made from here
 

package/docs/FRAME-COVERAGE-REPORT.md

@@ -173,7 +173,7 @@ Legend: ✓ covered · N/A reasoned skip · · UNTESTED (blank cell = UNTESTED).
 | Carousel | ✓ | N/A | N/A | · | · | · | · | · | · | · |
 | AppSettingPicker | ✓ | N/A | · | · | · | · | · | · | · | · |
 | AppSettingToggle | ✓ | N/A | · | · | · | · | · | · | · | · |
-| Field | ✓ | N/A | N/A | N/A | · | · | · | · | · | · |
+| Field | ✓ | N/A | · | N/A | · | · | · | · | · | · |
 | LineChart | ✓ | ✓ | N/A | N/A | · | · | · | · | · | · |
 | BarChart | ✓ | ✓ | N/A | N/A | · | · | · | · | · | · |
 | CompactBarTrend | ✓ | ✓ | N/A | N/A | · | · | · | · | · | · |

package/docs/data-display/collapsible.tsx

@@ -10,7 +10,7 @@ import {
 } from "@godxjp/ui/data-display";
 import { Button, Text } from "@godxjp/ui/general";
 import { Flex, PageContainer } from "@godxjp/ui/layout";
-import { ChevronsUpDown } from "lucide-react";
+import { ChevronDown } from "lucide-react";
 import { useState } from "react";
 
 /**
@@ -43,7 +43,7 @@ export default function Demo() {
                       aria-label="開閉"
                       className="transition-transform data-[state=open]:rotate-180"
                     >
-                      <ChevronsUpDown />
+                      <ChevronDown className="ui-disclosure-chevron" />
                     </Button>
                   </CollapsibleTrigger>
                 </Flex>
@@ -74,7 +74,7 @@ export default function Demo() {
                       aria-label="開閉"
                       className="transition-transform data-[state=open]:rotate-180"
                     >
-                      <ChevronsUpDown />
+                      <ChevronDown className="ui-disclosure-chevron" />
                     </Button>
                   </CollapsibleTrigger>
                 </Flex>
@@ -112,7 +112,7 @@ export default function Demo() {
                       aria-label="開閉"
                       className="transition-transform data-[state=open]:rotate-180"
                     >
-                      <ChevronsUpDown />
+                      <ChevronDown className="ui-disclosure-chevron" />
                     </Button>
                   </CollapsibleTrigger>
                 </Flex>
@@ -144,7 +144,7 @@ export default function Demo() {
                     aria-label="開閉"
                     className="transition-transform data-[state=open]:rotate-180"
                   >
-                    <ChevronsUpDown />
+                    <ChevronDown className="ui-disclosure-chevron" />
                   </Button>
                 </CollapsibleTrigger>
               </Flex>

package/docs/data-display/descriptions.tsx

@@ -6,176 +6,255 @@ import {
   CardHeader,
   CardTitle,
   Descriptions,
+  Progress,
+  Thumbnail,
 } from "@godxjp/ui/data-display";
-import type { CSSProperties } from "react";
-import { Text } from "@godxjp/ui/general";
+import { Button, Text } from "@godxjp/ui/general";
 import { Flex, PageContainer } from "@godxjp/ui/layout";
+import { Download, ExternalLink, FileText } from "lucide-react";
 
 /**
- * Descriptions — responsive label/value grid for detail-page metadata. COMPOUND:
- * the value goes in Descriptions.Item children. Never hand-roll a dl/dt/dd grid.
- * Composed only from real @godxjp/ui components.
+ * Descriptions — the label/value grid every detail page is made of.
+ *
+ * WHY THIS PAGE IS LONG. It was five tidy cards of short strings, and the owner's verdict was that
+ * it shows nothing about whether the component holds up. That is right: a label/value grid is
+ * trivial when every label is four characters and every value is one line.
+ *
+ * A real detail screen is not that. It has a label that runs to three lines beside one that is two
+ * characters; a value that is an image, a file to download, a link, a status, a progress bar, a
+ * 40-character machine ID, or nothing at all; and it has to survive all of them in the same grid,
+ * at every breakpoint, bordered and not.
+ *
+ * So every section below is a case a real detail page hits. Where a section looks bad, the
+ * component owes an answer — the sample data is not there to flatter it.
  */
+const ID = "01JBQ9X7M4K2R8VT3NZ6YHF0PA";
+
 export default function Demo() {
   return (
-    <PageContainer title="Descriptions" subtitle="Label / value metadata grid for detail pages">
+    <PageContainer
+      title="Descriptions"
+      subtitle="label/value grid — every shape a detail page asks for"
+    >
       <Flex direction="col" gap="lg">
-        {/* Default columns=2 — the canonical 2-column metadata grid.
-            mono for the ID; span=2 + a long URL value shows full-row + break-all overflow. */}
         <Card>
           <CardHeader>
-            <CardTitle level={2}>請求書の詳細</CardTitle>
+            <CardTitle level={2}>1 · columns × bordered × layout — the three axes</CardTitle>
             <CardDescription>
-              既定は
-              columns=2。値は任意のノード（テキスト・Badge・金額）。狭い画面では1列に折り返します。
+              Every combination changes where the label sits and how the grid divides. These are the
+              four a project actually picks between.
             </CardDescription>
           </CardHeader>
           <CardContent>
-            <Descriptions>
-              <Descriptions.Item label="請求書番号" mono>
-                INV-2024-0312
-              </Descriptions.Item>
-              <Descriptions.Item label="取引先">株式会社ベトヤ</Descriptions.Item>
-              <Descriptions.Item label="状態">
-                <Badge status="active" />
-              </Descriptions.Item>
-              <Descriptions.Item label="発行日">2024-04-12</Descriptions.Item>
-              <Descriptions.Item label="小計">
-                <Text tabular>¥438,182</Text>
-              </Descriptions.Item>
-              <Descriptions.Item label="消費税 (10%)">
-                <Text tabular>¥43,818</Text>
-              </Descriptions.Item>
-              <Descriptions.Item label="合計">
-                <Text weight="medium" tabular>
-                  ¥482,000
+            <Flex direction="col" gap="lg">
+              <Flex direction="col" gap="xs">
+                <Text size="sm" tone="muted">
+                  columns=3 · bordered · horizontal — the dense admin default
                 </Text>
+                <Descriptions columns={3} bordered layout="horizontal">
+                  <Descriptions.Item label="取引先">株式会社山田製作所</Descriptions.Item>
+                  <Descriptions.Item label="担当">佐藤 玲</Descriptions.Item>
+                  <Descriptions.Item label="状態">
+                    <Badge tone="success">有効</Badge>
+                  </Descriptions.Item>
+                  <Descriptions.Item label="登録日">2024-04-01</Descriptions.Item>
+                  <Descriptions.Item label="与信枠">¥12,000,000</Descriptions.Item>
+                  <Descriptions.Item label="支払条件">月末締め翌月末払い</Descriptions.Item>
+                </Descriptions>
+              </Flex>
+
+              <Flex direction="col" gap="xs">
+                <Text size="sm" tone="muted">
+                  columns=2 · no border · vertical — the reading layout, label above value
+                </Text>
+                <Descriptions columns={2} layout="vertical">
+                  <Descriptions.Item label="取引先">株式会社山田製作所</Descriptions.Item>
+                  <Descriptions.Item label="担当">佐藤 玲</Descriptions.Item>
+                  <Descriptions.Item label="与信枠">¥12,000,000</Descriptions.Item>
+                  <Descriptions.Item label="支払条件">月末締め翌月末払い</Descriptions.Item>
+                </Descriptions>
+              </Flex>
+
+              <Flex direction="col" gap="xs">
+                <Text size="sm" tone="muted">
+                  columns=1 · bordered — a narrow column or a phone
+                </Text>
+                <Descriptions columns={1} bordered>
+                  <Descriptions.Item label="取引先">株式会社山田製作所</Descriptions.Item>
+                  <Descriptions.Item label="状態">
+                    <Badge tone="success">有効</Badge>
+                  </Descriptions.Item>
+                </Descriptions>
+              </Flex>
+
+              <Flex direction="col" gap="xs">
+                <Text size="sm" tone="muted">
+                  labelAlign=end — right-aligned labels, so the values start on one line
+                </Text>
+                <Descriptions columns={2} bordered labelAlign="end">
+                  <Descriptions.Item label="ID">{ID}</Descriptions.Item>
+                  <Descriptions.Item label="状態">
+                    <Badge tone="success">有効</Badge>
+                  </Descriptions.Item>
+                </Descriptions>
+              </Flex>
+            </Flex>
+          </CardContent>
+        </Card>
+
+        <Card>
+          <CardHeader>
+            <CardTitle level={2}>2 · responsive columns</CardTitle>
+            <CardDescription>
+              `columns` takes a breakpoint object. Narrow this frame with the Dimensions control: 1
+              column on a phone, 2 on a tablet, 3 on a desktop — the same markup throughout.
+            </CardDescription>
+          </CardHeader>
+          <CardContent>
+            <Descriptions columns={{ sm: 1, md: 2, lg: 3 }} bordered>
+              <Descriptions.Item label="会社名">株式会社山田製作所</Descriptions.Item>
+              <Descriptions.Item label="法人番号" mono>
+                7010001071491
               </Descriptions.Item>
-              <Descriptions.Item label="PDF リンク" mono span={2}>
-                https://invoices.vetoya.example.co.jp/2024/04/INV-2024-0312-rev2.pdf
-              </Descriptions.Item>
+              <Descriptions.Item label="業種">精密機器製造</Descriptions.Item>
+              <Descriptions.Item label="代表">山田 太郎</Descriptions.Item>
+              <Descriptions.Item label="従業員数">248 名</Descriptions.Item>
+              <Descriptions.Item label="設立">1974-06-12</Descriptions.Item>
             </Descriptions>
           </CardContent>
         </Card>
 
-        {/* layout="horizontal" — label BESIDE value (token-aligned label column), like <Form layout>.
-            Default layout is "vertical" (label over value, the cards above). */}
         <Card>
           <CardHeader>
-            <CardTitle level={2}>横並び (layout=&quot;horizontal&quot;)</CardTitle>
+            <CardTitle level={2}>3 · the value is not a string</CardTitle>
             <CardDescription>
-              ラベルを値の左に揃える。`--descriptions-label-width` でラベル列幅を調整。既定は
-              layout=&quot;vertical&quot;（ラベルを上に積む、上のカード）。
+              The value slot takes any node. These are the ones a detail page actually puts there —
+              an image, a file, a link, a status, a proportion, a secret, money, a long memo.
             </CardDescription>
           </CardHeader>
           <CardContent>
-            <Descriptions columns={1} layout="horizontal">
-              <Descriptions.Item label="請求書番号" mono>
-                INV-2024-0312
+            <Descriptions columns={{ sm: 1, md: 2 }} bordered>
+              <Descriptions.Item label="製品画像">
+                <Thumbnail src="/godxjp-ui/favicon.svg" alt="製品サムネイル" size="md" />
               </Descriptions.Item>
-              <Descriptions.Item label="取引先">株式会社ベトヤ</Descriptions.Item>
               <Descriptions.Item label="状態">
-                <Badge status="active" />
+                <Flex direction="row" gap="xs" wrap>
+                  <Badge tone="success">出荷可</Badge>
+                  <Badge tone="warning" variant="outline">
+                    在庫僅少
+                  </Badge>
+                </Flex>
               </Descriptions.Item>
-              <Descriptions.Item label="合計">
-                <Text weight="medium" tabular>
-                  ¥482,000
-                </Text>
+              <Descriptions.Item label="仕様書">
+                <Button variant="outline" size="sm">
+                  <FileText className="size-4" />
+                  仕様書_v4.2.pdf
+                </Button>
+              </Descriptions.Item>
+              <Descriptions.Item label="検査成績書">
+                <Button variant="ghost" size="sm">
+                  <Download className="size-4" />
+                  ダウンロード（2.4 MB）
+                </Button>
+              </Descriptions.Item>
+              <Descriptions.Item label="外部リンク">
+                <Button variant="link" size="sm">
+                  <ExternalLink className="size-4" />
+                  サプライヤーポータル
+                </Button>
+              </Descriptions.Item>
+              <Descriptions.Item label="検収進捗">
+                <Progress value={72} tone="success" label="検収進捗 72%" />
+              </Descriptions.Item>
+              <Descriptions.Item label="単価">¥128,400</Descriptions.Item>
+              <Descriptions.Item label="ロットID" mono>
+                {ID}
               </Descriptions.Item>
             </Descriptions>
           </CardContent>
         </Card>
 
-        {/* columns=1 — stacked detail panel: every item on its own row. */}
         <Card>
           <CardHeader>
-            <CardTitle level={2}>取引先の詳細</CardTitle>
-            <CardDescription>columns=1。各項目を縦積みにする詳細パネル向けの構成。</CardDescription>
+            <CardTitle level={2}>4 · span — a value that needs the whole row</CardTitle>
+            <CardDescription>
+              An address, a memo or a JSON blob does not belong in a one-third cell. `span` widens
+              the item; `span=&quot;filled&quot;` takes whatever is left on the row, so the grid
+              stays aligned instead of leaving a hole.
+            </CardDescription>
           </CardHeader>
           <CardContent>
-            <Descriptions columns={1}>
-              <Descriptions.Item label="会社名">株式会社ベトヤ</Descriptions.Item>
-              <Descriptions.Item label="法人番号" mono>
-                1180001052731
+            <Descriptions columns={3} bordered>
+              <Descriptions.Item label="取引先">株式会社山田製作所</Descriptions.Item>
+              <Descriptions.Item label="担当">佐藤 玲</Descriptions.Item>
+              <Descriptions.Item label="電話">03-5555-0198</Descriptions.Item>
+              <Descriptions.Item label="本社所在地" span={3}>
+                〒105-0011 東京都港区芝公園四丁目2番8号 東京タワー内 グローバルビジネスセンター 23F
+                株式会社山田製作所 東日本統括本部
               </Descriptions.Item>
-              <Descriptions.Item label="住所">
-                東京都渋谷区神宮前5-52-2 青山オーバルビル7F
+              <Descriptions.Item label="備考" span="filled">
+                検収は毎月第2・第4火曜のみ。祝日と重なる場合は翌営業日に振替。先方の受入窓口は
+                資材部・資材管理課（内線
+                4821）。2026年4月以降は電子取引のみとなるため、紙の納品書は不可。
               </Descriptions.Item>
-              <Descriptions.Item label="担当者">山田 太郎（経理部）</Descriptions.Item>
+              <Descriptions.Item label="与信枠">¥12,000,000</Descriptions.Item>
+              <Descriptions.Item label="使用中">¥8,214,930</Descriptions.Item>
             </Descriptions>
           </CardContent>
         </Card>
 
-        {/* columns=3 — dense metadata grid; span=3 makes the JSON value occupy the full width. */}
         <Card>
           <CardHeader>
-            <CardTitle level={2}>システムメタデータ</CardTitle>
+            <CardTitle level={2}>5 · the cases that break a label/value grid</CardTitle>
             <CardDescription>
-              columns=3。識別子の多い密なメタデータ向け。mono と span でIDやJSONを整列。
+              This is the only section on the page that can tell you whether Descriptions is any
+              good. If a row here looks wrong, the component owes an answer — not the data.
             </CardDescription>
           </CardHeader>
           <CardContent>
-            <Descriptions columns={3}>
-              <Descriptions.Item label="リソースID" mono>
-                inv_8f3a21c0
+            <Descriptions columns={{ sm: 1, md: 2, lg: 3 }} bordered>
+              <Descriptions.Item label="グローバル人事情報基盤・従業員セルフサービスポータル（アジア太平洋地域）連携ステータス">
+                <Badge tone="success">連携済</Badge>
               </Descriptions.Item>
-              <Descriptions.Item label="リビジョン" mono>
-                v3
+              <Descriptions.Item label="率">96.8%</Descriptions.Item>
+              <Descriptions.Item label="ID" mono>
+                urn:godx:entitlement:ap-northeast-1:7010001071491:workforce/identity/administration/v4
               </Descriptions.Item>
-              <Descriptions.Item label="状態">
-                <Badge status="active" />
-              </Descriptions.Item>
-              <Descriptions.Item label="作成日時" mono>
-                2024-04-12T09:31:00+09:00
-              </Descriptions.Item>
-              <Descriptions.Item label="更新日時" mono>
-                2024-04-12T14:07:55+09:00
+              <Descriptions.Item label="未設定">
+                <Text tone="muted">—</Text>
               </Descriptions.Item>
-              <Descriptions.Item label="作成者">山田 太郎</Descriptions.Item>
-              <Descriptions.Item label="メタデータ" mono span={3}>
-                {'{ "channel": "web", "tax_rate": 0.1, "currency": "JPY" }'}
+              <Descriptions.Item label="空文字">{""}</Descriptions.Item>
+              <Descriptions.Item label="ゼロ">0</Descriptions.Item>
+              <Descriptions.Item label="累計取扱高">¥128,400,932,517</Descriptions.Item>
+              <Descriptions.Item label="差引">−¥412,880</Descriptions.Item>
+              <Descriptions.Item label="長い英数字" mono>
+                AKIAIOSFODNN7EXAMPLEWJALRXUTNFEMIK7MDENGBPXRFICYEXAMPLEKEY
               </Descriptions.Item>
             </Descriptions>
           </CardContent>
         </Card>
 
-        {/* ── The RULED property panel (gh#414) ─────────────────────────────
-            Two token knobs, both OFF by default, turn a horizontal Descriptions into the ruled
-            panel a detail page usually wants. They exist so a service stops hand-rolling a
-            `<Flex className="min-h-10 border-b">` row: the label column, the gaps and the value
-            type step were already Descriptions'; only the rule and the band height were missing.
-            The row gap goes to 0 in the same declaration — the gap is the space BETWEEN rules, so
-            leaving it would draw detached hairlines instead of a ruled list. */}
         <Card>
           <CardHeader>
-            <CardTitle level={2}>案件の詳細 · ruled rows</CardTitle>
-            <CardDescription>
-              一行ごとに罫線を引いた属性パネル。--descriptions-row-border と
-              --descriptions-row-min-height をテーマで一度設定するだけで、コンポーネントは同じです。
-            </CardDescription>
+            <CardTitle level={2}>使い方の要点</CardTitle>
+            <CardDescription>この3点で、上のほとんどが決まります。</CardDescription>
           </CardHeader>
-          {/* The knobs are declared on the CARD BODY, not on the grid: custom properties inherit,
-              so one scope re-tunes every Descriptions inside it — which is how a service theme
-              would set them (once, globally), not per call site. */}
-          <CardContent
-            style={
-              {
-                "--descriptions-row-border": "1px solid hsl(var(--border))",
-                "--descriptions-row-min-height": "var(--band-height-lg)",
-                "--descriptions-row-gap": "0px",
-              } as CSSProperties
-            }
-          >
-            <Descriptions columns={1} layout="horizontal">
-              <Descriptions.Item label="案件名">2026年度 基幹システム更改</Descriptions.Item>
-              <Descriptions.Item label="担当">山田 太郎</Descriptions.Item>
-              <Descriptions.Item label="状態">
-                <Badge status="active" />
-              </Descriptions.Item>
-              <Descriptions.Item label="契約ID" mono>
-                CT-2026-0088
-              </Descriptions.Item>
-            </Descriptions>
+          <CardContent>
+            <Flex direction="col" gap="sm">
+              <Text as="div" size="sm">
+                直下の子は <code>Descriptions.Item</code> だけです。生の <code>&lt;div&gt;</code> や
+                <code>&lt;dt&gt;/&lt;dd&gt;</code> を混ぜるとグリッドが崩れます。
+              </Text>
+              <Text as="div" size="sm">
+                機械可読な値（ID・パス・鍵・通貨コード）には <code>mono</code> を付けてください。
+                等幅になるだけでなく <code>break-all</code> が効き、上の 57
+                文字の鍵がセルを突き破らずに折り返します。
+              </Text>
+              <Text as="div" size="sm">
+                住所・備考・JSON のような長い値には <code>span</code> を。 1/3
+                セルに押し込むと、その行だけ高さが跳ねて表全体が読みにくくなります。
+              </Text>
+            </Flex>
           </CardContent>
         </Card>
       </Flex>

package/docs/data-display/legend.tsx

@@ -61,7 +61,20 @@ export default function Demo() {
                       aria-label={row.name}
                     />
                   </Flex>
-                  <Flex width={150} justify="end" align="center" gapRaw={12}>
+                  {/* A COLUMN OF NUMBERS NEEDS COLUMNS, not a row of shrink-to-fit boxes.
+                      `tabular` makes DIGITS equal-width inside one Text; it cannot align two Texts
+                      with different digit COUNTS. Laid out as a flex row and right-aligned as a
+                      group, a row ending in "9" sat 8px right of one ending in "21" — measured on
+                      the published site, and the reason this readout looked crooked. Fixed tracks
+                      give each value its own cell, so every row lines up whatever the digits. */}
+                  <div
+                    className="grid items-center"
+                    style={{
+                      gridTemplateColumns: "2.5rem 2.5rem 2.5rem 4.5rem",
+                      justifyItems: "end",
+                      columnGap: "var(--space-2)",
+                    }}
+                  >
                     <Text tone="destructive" weight="semibold" tabular>
                       {row.over}
                     </Text>
@@ -74,7 +87,7 @@ export default function Demo() {
                     <Text tone="muted" tabular>
                       計 {row.over + row.near + row.done}
                     </Text>
-                  </Flex>
+                  </div>
                 </Flex>
               ))}
             </Flex>
@@ -108,8 +121,8 @@ export default function Demo() {
           <CardHeader>
             <CardTitle level={2}>Named legend</CardTitle>
             <CardDescription>
-              aria-label を渡すと、その凡例が「何のキーか」を読み上げます。項目は list /
-              listitem として並びます。
+              aria-label を渡すと、その凡例が「何のキーか」を読み上げます。項目は list / listitem
+              として並びます。
             </CardDescription>
           </CardHeader>
           <CardContent>