@godxjp/ui 19.3.1 → 19.4.0

package/docs/feedback/alert.tsx

@@ -139,7 +139,7 @@ export default function Demo() {
           </CardContent>
         </Card>
 
-        {/* Banner — the SAME component at the page measure (gh#255). variant="banner" swaps only
+        {/* Banner — the SAME component at the page measure. variant="banner" swaps only
             the box: square, edge-to-edge, ruled on the block-end edge, measured by the --banner-*
             tokens. Every tone, the icon, the actions grid and the dismiss ✕ are inherited from the
             inline alert above, so there is nothing new to learn and nothing duplicated.

package/docs/feedback/banner.tsx

@@ -5,7 +5,7 @@ import { Button } from "@godxjp/ui/general";
 import { Flex, PageContainer } from "@godxjp/ui/layout";
 
 /**
- * Banner · full-bleed page/shell attention strip (godxjp-ui#255) — the Alert
+ * Banner · full-bleed page/shell attention strip — the Alert
  * primitive with the structural axis fixed to variant="banner". Persistent,
  * page/shell-scoped, at most one per surface. tone owns colour + icon +
  * live-region politeness; onDismiss renders the built-in dismiss (last in focus

package/docs/foundation/email-tokens.tsx

@@ -25,7 +25,7 @@ import { Flex, PageContainer, ResponsiveGrid } from "@godxjp/ui/layout";
 import { buildEmailSpecimenHtml } from "./_email-specimen";
 
 /**
- * Email tokens · the `@godxjp/ui/email` contract (issue #227).
+ * Email tokens · the `@godxjp/ui/email` contract.
  *
  * A transactional email is rendered by Blade/Twig/MJML, by clients that strip `<style>`, ignore
  * CSS custom properties and block remote images — so neither the React components nor the CSS

package/docs/general/activity.tsx

@@ -12,7 +12,7 @@ import { Flex, PageContainer, Separator } from "@godxjp/ui/layout";
 
 /**
  * Activity · the official AMBIENT-motion primitive: a continuous, unbounded "something is happening
- * right now, elsewhere". The LOOP counterpart to `Reveal`'s one-shot entrance (gh#313).
+ * right now, elsewhere". The LOOP counterpart to `Reveal`'s one-shot entrance.
  *
  * Reads the DS motion tokens (`--activity-interval`, `--activity-stagger-step`,
  * `--activity-mark-offset`, `--activity-color`, `--ease-standard`) so a consumer never hand-rolls a

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

@@ -8,7 +8,7 @@ import { AuthAccountSummary, AuthStack, PageContainer } from "@godxjp/ui/layout"
  * 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
+ *: 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.
  */

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

@@ -9,7 +9,7 @@ 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
+ * ⚠️ The 390 canonical reference supplied with 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.
  *

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

@@ -28,8 +28,6 @@ export default function Demo() {
   const [password, setPassword] = useState("Godx-2026");
   const [confirmation, setConfirmation] = useState("Godx-202");
 
-  // The address is masked by the SERVER before it reaches the panel — the library never
-  // reconstructs an identifier, it only renders the string the consumer sends.
   const maskedEmail = "h*****@example.co.jp";
 
   return (

package/docs/layout/auth-shell-context.tsx

@@ -16,7 +16,7 @@ import { AuthFooter, AuthIdentity, AuthShell, Flex } from "@godxjp/ui/layout";
 import { AppSettingPicker } from "@godxjp/ui/navigation";
 
 /**
- * AuthShell preset="context-selection" (gh#217) — the canonical organisation / context picker.
+ * AuthShell preset="context-selection" — the canonical organisation / context picker.
  *
  * The preset owns the whole page measure: a 25rem card at 1440/1024 and an edge-to-edge card at
  * 390 (0 inline gutter), plus the vertical rhythm between the three direct sections of the auth

package/docs/layout/auth-shell-device.tsx

@@ -18,7 +18,7 @@ import {
 import { AppSettingPicker, Steps } from "@godxjp/ui/navigation";
 
 /**
- * AuthShell preset="device-authorization" (gh#220) — the canonical OAuth device-grant screen.
+ * AuthShell preset="device-authorization" — the canonical OAuth device-grant screen.
  *
  * The whole page measure is owned by the preset: a 380px card at 1440/1024 and a 5px inline page
  * gutter at 390 (card x=5px, width=380px). Nothing here sets a width, an inset or a colour — a
@@ -28,7 +28,7 @@ import { AppSettingPicker, Steps } from "@godxjp/ui/navigation";
  * `variant="canonical"` still owns control density + heading size; the preset only re-measures.
  * Verify at 1440x900 · 1024x900 · 390x844.
  *
- * gh#12 — the preset also owns the CODE FIELD now: `--otp-slot-{inline,block}-size` come from
+ * The preset also owns the CODE FIELD now: `--otp-slot-{inline,block}-size` come from
  * `--auth-shell-device-otp-slot-*`, so each 4-slot grouped box measures the canonical 112x54
  * instead of the 146x38 the square control tier produced. Nothing on this page sets it. The row is
  * centred with `align="center"` (not a wrapper div) and the progress marker is the canonical

package/docs/layout/auth-shell-registration.tsx

@@ -33,7 +33,7 @@ import {
 import { AppSettingPicker } from "@godxjp/ui/navigation";
 
 /**
- * AuthShell preset="registration" (gh#256) — the canonical sign-up measure.
+ * AuthShell preset="registration" — the canonical sign-up measure.
  *
  * The preset owns the whole page geometry: a 360px (22.5rem) form measure at 1440/1024, a 15px
  * inline gutter at 390 (card x=15, width=360 — the same page rhythm as preset="login", so

package/docs/layout/auth-shell.tsx

@@ -14,7 +14,7 @@ import {
  * SCR-001 Login visual contract. `?state=standalone|one-line|wrapped` drives the package visual
  * test; all three keep the same card anchor without consumer CSS or fake requester data.
  *
- * The composition mirrors the documented consumer page exactly (gh#263): NO top brand bar (the
+ * The composition mirrors the documented consumer page exactly: NO top brand bar (the
  * canonical SCR-001 artboard has none — the in-flow AuthIdentity mark IS the brand), a header-less
  * `<CardContent solo>` body, `AuthFooter` as the third direct child (the login preset's third grid
  * row), and a plain 12px text-link row like the artboard's.

package/docs/layout/master-detail.tsx

@@ -102,7 +102,7 @@ const COLLAPSE_STEPS = ["token", "sm", "md", "lg", "xl", "false"] as const;
 const MASTER_VIEWPORTS = ["auto", "compact", "standard"] as const;
 
 /**
- * 実サービスの「長い」コレクション (gh#231)。auto のままだと一覧が数千 px に伸び、
+ * 実サービスの「長い」コレクション。auto のままだと一覧が数千 px に伸び、
  * 積み重なった 390px 画面では詳細がフォールドの遥か下に押し出される。
  */
 const MEMBERS = Array.from({ length: 60 }, (_, i) => ({
@@ -339,7 +339,7 @@ export default function Demo() {
           </Card>
         </MasterDetail>
 
-        {/* ── 3. masterViewport — 長い実コレクションを境界付きビューポートに収める (gh#231)。
+        {/* ── 3. masterViewport — 長い実コレクションを境界付きビューポートに収める。
                auto: 一覧が 60 行ぶん伸び、390px では詳細がフォールドの遥か下に落ちる。
                compact / standard: --master-detail-master-viewport-* が block サイズを
                上限とし、コレクションは region の中でスクロールする。

package/docs/layout/mobile-shell.tsx

@@ -0,0 +1,101 @@
+import * as React from "react";
+import { Inbox, Package, ScanLine, Truck } from "lucide-react";
+
+import { Badge, Card, CardContent } from "@godxjp/ui/data-display";
+import { Button, Heading, Text } from "@godxjp/ui/general";
+import { Flex, MobileShell } from "@godxjp/ui/layout";
+
+/**
+ * MobileShell — the handheld app shell: a status band, an app bar, ONE scroll region, a sticky
+ * action bar and a bottom tab bar. The two things a composed `Card` stack cannot do are exactly
+ * what the shell owns: the root is one screen tall so the DOCUMENT never scrolls (the tab bar can
+ * never slide away under a collapsing URL bar), and every band pads itself out of the device
+ * safe areas. Zero custom CSS — no `min-h-dvh`, no `position: sticky`, no page gutter by hand.
+ */
+const ITEMS = [
+  { rc: "RC-204881", name: "洗顔フォーム", status: "未仕分け", tone: "warning" as const },
+  { rc: "RC-204882", name: "日焼け止め", status: "棚上", tone: "info" as const },
+  { rc: "RC-204879", name: "ビタミン B", status: "棚上", tone: "info" as const },
+  { rc: "RC-204875", name: "歯ブラシ", status: "梱包済み", tone: "muted" as const },
+  { rc: "RC-204871", name: "入浴剤", status: "棚上", tone: "info" as const },
+  { rc: "RC-204864", name: "解熱鎮痛薬", status: "梱包済み", tone: "muted" as const },
+];
+
+const TABS = [
+  { id: "inbound", label: "入庫", icon: Inbox },
+  { id: "packing", label: "梱包", icon: Package },
+  { id: "outbound", label: "出庫", icon: Truck },
+];
+
+export default function Demo() {
+  const [tab, setTab] = React.useState("inbound");
+
+  return (
+    <MobileShell
+      statusBar={
+        <>
+          <Text size="sm" weight="medium" tabular>
+            9:41
+          </Text>
+          <Text size="sm" weight="medium" tone="muted" tabular>
+            Acme Handy
+          </Text>
+        </>
+      }
+      header={
+        <Flex align="center" justify="between" gap="xs" className="w-full">
+          <Heading level={3} as="h1">
+            入庫
+          </Heading>
+          <Button variant="ghost" size="sm">
+            選択
+          </Button>
+        </Flex>
+      }
+      actions={
+        <>
+          <Button className="flex-[2]">
+            <ScanLine aria-hidden="true" />
+            スキャン
+          </Button>
+          <Button variant="outline" className="flex-1">
+            手入力
+          </Button>
+        </>
+      }
+      tabBar={TABS.map((t) => {
+        const Icon = t.icon;
+        return (
+          <Button
+            key={t.id}
+            variant="ghost"
+            onClick={() => setTab(t.id)}
+            aria-current={t.id === tab ? "page" : undefined}
+            className="h-full flex-col rounded-none"
+          >
+            <Icon aria-hidden="true" />
+            <Text size="2xs">{t.label}</Text>
+          </Button>
+        );
+      })}
+    >
+      <Flex direction="col" gap="sm">
+        {ITEMS.map((item) => (
+          <Card key={item.rc} density="tight">
+            <CardContent solo>
+              <Flex align="center" justify="between" gap="sm">
+                <Flex direction="col" gap="none">
+                  <Text weight="medium">{item.name}</Text>
+                  <Text size="xs" mono tone="muted" tabular>
+                    {item.rc}
+                  </Text>
+                </Flex>
+                <Badge tone={item.tone}>{item.status}</Badge>
+              </Flex>
+            </CardContent>
+          </Card>
+        ))}
+      </Flex>
+    </MobileShell>
+  );
+}

package/docs/layout/page-container.tsx

@@ -47,7 +47,7 @@ const TOOLBAR_CHROME_TOKENS = {
 } as CSSProperties;
 
 /**
- * `--page-header-min-block-size-chrome` · クロム帯の「高さ」（gh#331）。文書のヘッダーは中身なりの
+ * `--page-header-min-block-size-chrome` · クロム帯の「高さ」。文書のヘッダーは中身なりの
  * 高さで正しい · 見出しは見出しの高さだからです。クロムは逆で、家具には「ものが中央に収まる帯」が
  * 要ります。既定は `auto`（＝rule #44 の最も静かな状態）なので、このトークンを置くまで DOM も
  * 見え方も従来どおり · 文書ページはそもそもこの規則に一致しません。
@@ -109,7 +109,7 @@ const journalColumns: ColumnDef<JournalEntry>[] = [
  * PageContainer · mandatory page shell.
  * Covers: title/subtitle/status/extra/footer/breadcrumb/linkComponent + variant
  * default/narrow/flush/ghost + density compact/default/comfortable + PageContainer.Inset.
- * The embedded header is the CANONICAL DXS PageHeader (gh#255) — status/meta band included.
+ * The embedded header is the CANONICAL DXS PageHeader — status/meta band included.
  * Each example is standalone (no AppShell) so the variant behaviour is visible in
  * isolation. Composed only from real @godxjp/ui components.
  */
@@ -165,7 +165,7 @@ export default function Demo() {
         </ResponsiveGrid>
       </PageContainer>
 
-      {/* ── 1b. Canonical page-header contract (gh#255) · status/meta band ── */}
+      {/* ── 1b. Canonical page-header contract · status/meta band ── */}
       {/* PageContainer's embedded header IS the DXS PageHeader: breadcrumbs + title +
           subtitle + status/meta + actions + responsive overflow on ONE renderer. The
           `status` band shares the title line at --page-header-status-gap and wraps
@@ -405,7 +405,7 @@ export default function Demo() {
         </Card>
       </PageContainer>
 
-      {/* ── 6. fill · body height behaviour on a tall shell (gh#103) ──
+      {/* ── 6. fill · body height behaviour on a tall shell ──
           Each PageContainer sits in a fixed-height framed box that stands in for the
           viewport-tall app shell, so the two behaviours are visible side by side. */}
       <ResponsiveGrid columns={{ sm: 1, md: 2 }}>
@@ -452,7 +452,7 @@ export default function Demo() {
         </div>
       </ResponsiveGrid>
 
-      {/* ── 7. headerLayout · 390px でヘッダー extra をタイトル行に残す (gh#231) ──
+      {/* ── 7. headerLayout · 390px でヘッダー extra をタイトル行に残す ──
           stack (既定) は 640px 未満で extra を subtitle の下の全幅行に落とす。
           responsive-inline は --page-header-extra-measure (11rem) の測度で
           title 帯の横に残す。640px 以上では両者は同一。
@@ -505,7 +505,7 @@ export default function Demo() {
         </PageContainer>
       </ResponsiveGrid>
 
-      {/* ── 8. measure · ヘッダーとボディを 1 つの測度で束ねる (gh#245 / gh#247) ──
+      {/* ── 8. measure · ヘッダーとボディを 1 つの測度で束ねる ──
           measure は variant（クローム）と直交する第 3 の軸。variant="narrow" は
           .ui-page-body しか絞らないため、ヘッダーのアクションはページ端に取り残される。
           measure はヘッダーとボディの両方を同じトークン測度で絞るので、extra の終端が

package/docs/layout/responsive-grid.tsx

@@ -13,7 +13,7 @@ import { Flex, PageContainer, ResponsiveGrid, SplitPane } from "@godxjp/ui/layou
  * ResponsiveGrid · equal-width multi-column tile grid with automatic responsive
  * collapse (CSS container queries, not viewport). It OWNS its query container
  * (container-type: inline-size), so it responds to the width available to the grid
- * with no external container-type declaration (gh#165). Direct children are typically
+ * with no external container-type declaration. Direct children are typically
  * StatCard (self-contained bordered card · never wrap in Card/CardContent) or
  * Card+CardContent for richer tile bodies. columns accepts a number OR breakpoint
  * object { sm?, md?, lg? } — or use the named `preset` prop (e.g. "pricing-plans") for a
@@ -45,7 +45,7 @@ export default function Demo() {
               aside={
                 <Flex direction="col" gap="sm">
                   <Text tone="muted">狭いコンテナ（約 20rem）→ sm=1 列</Text>
-                  {/* No wrapping `@container` needed — ResponsiveGrid OWNS its query container (gh#165). */}
+                  {/* No wrapping `@container` needed — ResponsiveGrid OWNS its query container. */}
                   <ResponsiveGrid columns={4}>
                     <StatCard label="今日の入金" value="¥420,000" />
                     <StatCard label="未処理" value="6 件" />

package/docs/layout/separator.tsx

@@ -19,7 +19,7 @@ import { Flex, PageContainer, Separator } from "@godxjp/ui/layout";
  * defaults to true · set false only when the divider carries semantic meaning for
  * a11y.
  *
- * gh#308 — `label` INTERRUPTS the rule: a message stream's day divider, a "new messages"
+ * `label` INTERRUPTS the rule: a message stream's day divider, a "new messages"
  * watermark, an auth conjunction. A labelled rule flips `decorative` to false, so it is a real
  * role="separator" NAMED by the label (the visible node is aria-hidden, so the string is announced
  * exactly once). `labelAlign` is a controlled vocabulary value — start | center | end, logical, so
@@ -172,7 +172,7 @@ export default function Demo() {
           </CardContent>
         </Card>
 
-        {/* ── gh#308 — the real screen the labelled rule exists for ─────────────────────────── */}
+        {/* ── — the real screen the labelled rule exists for ─────────────────────────── */}
         <Card>
           <CardHeader>
             <CardTitle level={2}>実画面 · チャンネルの投稿ストリーム</CardTitle>

package/docs/layout/service-role-panel.tsx

@@ -1,5 +1,5 @@
 /**
- * ServiceRolePanel — ロール一覧 ⇄ 詳細 (canonical master-detail roles surface, gh#257).
+ * ServiceRolePanel — ロール一覧 ⇄ 詳細 (canonical master-detail roles surface).
  *
  * MasterDetail (rail=master) underneath owns all geometry: two tracks at 1440/1024, stacked
  * list-then-detail at 390. The panel adds selection (aria-current rows), locked system roles,

package/docs/layout/sidebar.tsx

@@ -127,7 +127,7 @@ const MENTION_SECTIONS: SidebarSectionProp[] = [
 ];
 
 /**
- * gh#228 · nav row and nav icon read SEPARATE colour tokens. A service normally sets these once in
+ * nav row and nav icon read SEPARATE colour tokens. A service normally sets these once in
  * its theme.css (`:root` or a scoped `[data-tenant] .app-sidebar`); here they are scoped to one
  * demo frame so the default rail can sit next to the themed one. Icons only — geometry (16px icon,
  * 32px row, 10px gap) is untouched.
@@ -138,7 +138,7 @@ const CANONICAL_NAV_TOKENS = {
 } as CSSProperties;
 
 /**
- * gh#213 · THE router-link contract. `createSidebarLink` adapts any router `Link` — React Router /
+ * THE router-link contract. `createSidebarLink` adapts any router `Link` — React Router /
  * TanStack use `to`, Inertia and Next.js use `href` (the default, and
  * `inertiaSidebarLink(Link)` from `@godxjp/ui/inertia` is the same thing pre-bound). The consumer
  * writes NO row markup: the Sidebar composes the icon slot, the label, the badge, the active state
@@ -171,7 +171,7 @@ const ROUTED_SECTIONS: SidebarSectionProp[] = [
 ];
 
 /**
- * renderItem · DEPRECATED (gh#213) — kept working for existing consumers. It leaves the row CONTENT
+ * renderItem · DEPRECATED — kept working for existing consumers. It leaves the row CONTENT
  * to the caller, which is how a `<Link>{item.label}</Link>` silently dropped every icon in
  * production. `rowProps` now carries the library-composed `children`, so spreading it (or rendering
  * `rowProps.children`) restores the canonical row; the star is a decorative, non-interactive affix.
@@ -346,7 +346,7 @@ export default function Demo() {
             </CardContent>
           </Card>
 
-          {/* linkComponent prop · THE router-link contract (gh#213) — library composes the row. */}
+          {/* linkComponent prop · THE router-link contract — library composes the row. */}
           <Card>
             <CardHeader>
               <CardTitle level={2}>linkComponent プロップ（ルーターリンク）</CardTitle>
@@ -395,7 +395,7 @@ export default function Demo() {
             </CardContent>
           </Card>
 
-          {/* renderItem prop · DEPRECATED escape hatch (gh#213) — kept for back-compat. */}
+          {/* renderItem prop · DEPRECATED escape hatch — kept for back-compat. */}
           <Card>
             <CardHeader>
               <CardTitle level={2}>renderItem プロップ（非推奨）</CardTitle>
@@ -526,7 +526,7 @@ export default function Demo() {
             </CardContent>
           </Card>
 
-          {/* Nav colour tokens · icon and label are themed SEPARATELY (gh#228). */}
+          {/* Nav colour tokens · icon and label are themed SEPARATELY. */}
           <Card>
             <CardHeader>
               <CardTitle level={2}>ナビの配色トークン（アイコンとラベルを別々に）</CardTitle>

package/docs/layout/split-pane.tsx

@@ -17,7 +17,7 @@ import { FileText, Building2, Calendar, CreditCard, ArrowRight } from "lucide-re
  * Shows: main list + detail panel, asideWidth sm/md, nested inside PageContainer.
  * It OWNS its query container (container-type: inline-size), so the two-column split
  * is chosen from the PANE's own width (≥48rem), not the viewport — a narrow embedded
- * pane on a large screen correctly stays single-column (gh#165).
+ * pane on a large screen correctly stays single-column.
  * Composed only from real @godxjp/ui components.
  *
  * NOTE: <Flex> defaults to direction="row"; vertical stacks set direction="col"

package/docs/layout/topbar.tsx

@@ -37,10 +37,7 @@ import {
 
 /**
  * Topbar · a PURE SLOT bar. The shell only positions `start` / `center` / `end`; the CONSUMER
- * composes every control. This demo builds the chrome the OLD baked Topbar used to force ·
- * sidebar toggle, brand mark (Avatar), an entity switcher, a search trigger, a notifications button, a
- * user menu · entirely from real primitives, so you can see there is no hidden template (and no
- * dead dropdown: a control exists ONLY because it's placed here).
+ * composes every control.
  */
 const SECTIONS: SidebarSectionProp[] = [
   {
@@ -153,10 +150,7 @@ export default function Demo() {
   // end · notifications + user menu, both consumer-composed.
   const end = (
     <>
-      {/* The end slot is `flex: 0 0 auto` — whatever sits here is taken out of the start slot's
-          budget before it gets a say. At 320 this environment chip alone claimed 93 of the bar's
-          198px, squeezing start to 25px and clipping the entity switcher inside it. An ambient
-          status label is the first thing a compact bar drops, so it appears from sm up. */}
+      {}
       <Badge tone="warning" className="text-xs">
         ステージング
       </Badge>

package/docs/navigation/filter-bar.tsx

@@ -39,7 +39,7 @@ export default function Demo() {
   const [period, setPeriod] = useState("all");
   const hasActiveFilters = query !== "" || status !== "all";
 
-  // Typed model (gh#258) — ALL state is consumer data; the bar only renders it.
+  // Typed model — ALL state is consumer data; the bar only renders it.
   const [modelQuery, setModelQuery] = useState("田中");
   const [modelStatus, setModelStatus] = useState("active");
   const [modelRole, setModelRole] = useState("");
@@ -80,7 +80,7 @@ export default function Demo() {
       subtitle="Search, labelled filters, active state, consumer-owned reset, and both responsive overflow strategies"
     >
       <Flex direction="col" gap="lg">
-        {/* Typed model (gh#258) — search/filters/chips/reset/result-count/actions as DATA.
+        {/* Typed model — search/filters/chips/reset/result-count/actions as DATA.
             The bar owns layout, token widths, chip lifecycle and keyboard order; the page owns
             every piece of state. Remove a chip, reset, or pick a filter and watch the chips row
             and the localized result count follow. */}

package/docs/navigation/pagination.tsx

@@ -97,7 +97,7 @@ export default function Demo() {
           onValueChange={handleChange}
         />
 
-        {/* Regression: total=0, exactly one page, multiple pages, + the single-page opt-in (gh#153). */}
+        {/* Regression: total=0, exactly one page, multiple pages, + the single-page opt-in. */}
         <Card>
           <CardHeader>
             <CardTitle level={2}>境界状態 · 0 件 / 1 ページ / 複数ページ</CardTitle>
@@ -136,7 +136,7 @@ export default function Demo() {
           </CardContent>
         </Card>
 
-        {/* Long localized total label — the row stays ONE line and never wraps on desktop (gh#153). */}
+        {/* Long localized total label — the row stays ONE line and never wraps on desktop. */}
         <Card>
           <CardHeader>
             <CardTitle level={2}>長いローカライズ済みラベル · 折り返さない</CardTitle>

package/docs/navigation/steps.tsx

@@ -229,7 +229,7 @@ export default function Demo() {
           </CardContent>
         </Card>
 
-        {/* Inline row — the hosted-identity / device progression (gh#12) */}
+        {/* Inline row — the hosted-identity / device progression */}
         <Card>
           <CardHeader>
             <CardTitle level={2}>

package/docs/navigation/tabs.tsx

@@ -67,7 +67,7 @@ export default function Demo() {
           </CardContent>
         </Card>
 
-        {/* Disabled first item — fallback selection must skip it (gh#175) */}
+        {/* Disabled first item — fallback selection must skip it */}
         <Card>
           <CardHeader>
             <CardTitle level={2}>先頭タブが disabled · フォールバック選択</CardTitle>

package/docs/showcase/acme-portal.tsx

@@ -50,6 +50,7 @@ import {
   CardContent,
   CardHeader,
   CardTitle,
+  ListRow,
   Progress,
   StatCard,
   Table,
@@ -353,27 +354,25 @@ export default function AcmePortalShowcase() {
                 <CardContent flush>
                   <ul className="divide-border divide-y">
                     {QUEUE.map((q) => (
-                      <li key={q.title} className="px-4 py-3">
-                        <Flex align="center" gap="md">
+                      <ListRow
+                        as="li"
+                        key={q.title}
+                        leading={
                           <Badge
                             tone={q.tone}
                             variant="outline"
                             icon={q.icon}
                             aria-label={q.title}
                           />
-                          <div className="min-w-0 flex-1">
-                            <Text as="div" size="sm" weight="medium" truncate>
-                              {q.title}
-                            </Text>
-                            <Text as="div" size="xs" tone="muted" truncate>
-                              {q.meta}
-                            </Text>
-                          </div>
+                        }
+                        title={q.title}
+                        description={q.meta}
+                        trailing={
                           <Button variant="outline" size="sm">
                             {q.action}
                           </Button>
-                        </Flex>
-                      </li>
+                        }
+                      />
                     ))}
                   </ul>
                 </CardContent>

package/docs/showcase/acme-website.tsx

@@ -237,7 +237,7 @@ function SectionHead({
   center?: boolean;
 }) {
   return (
-    <div className={center ? "mx-auto mb-10 text-center" : "mb-8"}>
+    <div className={center ? "mx-auto text-center" : undefined}>
       <div className="tx-eyebrow">{eyebrow}</div>
       <h2 className="tx-h2">{title}</h2>
       {sub ? <p className="tx-lead mx-auto">{sub}</p> : null}
@@ -272,7 +272,7 @@ function Services() {
   ];
   return (
     <section className="bg-card tx-section">
-      <div className={SHELL}>
+      <Flex direction="col" gap="xl" className={SHELL}>
         <SectionHead
           center
           eyebrow="Dịch vụ"
@@ -296,7 +296,7 @@ function Services() {
             </Card>
           ))}
         </ResponsiveGrid>
-      </div>
+      </Flex>
     </section>
   );
 }
@@ -310,7 +310,7 @@ function Steps() {
   ];
   return (
     <section className="bg-background tx-section">
-      <div className={SHELL}>
+      <Flex direction="col" gap="xl" className={SHELL}>
         <SectionHead eyebrow="Quy trình" title="Mua hàng quốc tế trong 4 bước" />
         <ResponsiveGrid columns={{ sm: 1, md: 2, lg: 4 }}>
           {steps.map(([Icon, t, d], i) => (
@@ -332,7 +332,7 @@ function Steps() {
             </Flex>
           ))}
         </ResponsiveGrid>
-      </div>
+      </Flex>
     </section>
   );
 }
@@ -346,7 +346,7 @@ function Routes() {
   ];
   return (
     <section className="bg-card tx-section">
-      <div className={SHELL}>
+      <Flex direction="col" gap="xl" className={SHELL}>
         <SectionHead eyebrow="Tuyến vận chuyển" title="Giá cước rõ ràng theo từng tuyến" />
         <ResponsiveGrid columns={{ sm: 1, md: 2, lg: 4 }}>
           {routes.map(([c, code, mode, price]) => (
@@ -370,7 +370,7 @@ function Routes() {
             </Card>
           ))}
         </ResponsiveGrid>
-      </div>
+      </Flex>
     </section>
   );
 }

package/docs/showcase/case1-warehouse-dashboard.tsx

@@ -43,6 +43,7 @@ import {
   CardContent,
   CardHeader,
   CardTitle,
+  ListRow,
   Progress,
   StatCard,
   Table,
@@ -241,27 +242,25 @@ export default function WarehouseDashboardShowcase() {
                 <ul className="divide-border divide-y">
                   {QUEUE.map((q) => {
                     return (
-                      <li key={q.title} className="px-4 py-3">
-                        <Flex align="center" gap="md">
+                      <ListRow
+                        as="li"
+                        key={q.title}
+                        leading={
                           <Badge
                             tone={q.tone}
                             variant="outline"
                             icon={q.icon}
                             aria-label={q.title}
                           />
-                          <div className="min-w-0 flex-1">
-                            <Text as="div" size="sm" weight="medium" truncate>
-                              {q.title}
-                            </Text>
-                            <Text as="div" size="2xs" tone="muted" truncate>
-                              {q.meta}
-                            </Text>
-                          </div>
+                        }
+                        title={q.title}
+                        description={q.meta}
+                        trailing={
                           <Button variant="outline" size="sm">
                             {q.action}
                           </Button>
-                        </Flex>
-                      </li>
+                        }
+                      />
                     );
                   })}
                 </ul>