@godxjp/ui 28.7.0 → 28.9.0

package/docs/DESIGN-AUTHORITY.md

@@ -12,17 +12,17 @@ It changes no code by itself. It is the tie-breaker a reviewer points at.
 
 ## The layers, and who owns each
 
-| Layer                                                              | Authority                                       | Status in this repo                                                                                                                                  |
-| ------------------------------------------------------------------ | ----------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Interaction semantics, keyboard, ARIA                              | **WAI-ARIA APG**                                | already followed — 33 references in `src/`                                                                                                           |
-| Behaviour primitives                                               | **Radix**                                       | already the implementation — 193 references                                                                                                          |
-| Component composition shape                                        | **shadcn**                                      | already the structural convention — 23 references                                                                                                    |
-| Component taxonomy / grouping                                      | **Ant Design** groups                           | already the catalog shape: `data-entry`, `data-display`, `layout`, `feedback`, `navigation`, `general` — a naming precedent, nothing is installed    |
+| Layer                                                              | Authority                                       | Status in this repo                                                                                                                                                                                        |
+| ------------------------------------------------------------------ | ----------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Interaction semantics, keyboard, ARIA                              | **WAI-ARIA APG**                                | already followed — 33 references in `src/`                                                                                                                                                                 |
+| Behaviour primitives                                               | **Radix**                                       | already the implementation — 193 references                                                                                                                                                                |
+| Component composition shape                                        | **shadcn**                                      | already the structural convention — 23 references                                                                                                                                                          |
+| Component taxonomy / grouping                                      | **Ant Design** groups                           | already the catalog shape: `data-entry`, `data-display`, `layout`, `feedback`, `navigation`, `general` — a naming precedent, nothing is installed                                                          |
 | Colour foundation                                                  | **SmartHR**, brand roles aside                  | the NEUTRAL spine is SmartHR's — `--foreground` = TEXT_BLACK, `--border` = BORDER. `--primary` was SmartHR MAIN `#0071bd` until identity v2.3 took the brand roles back: it is GoDX violet `#7A00FF` today |
-| **Derived colour — the interaction states hanging off each seed**  | **Measured contrast (WCAG 2.2 / JIS X 8341-3)** | Authored in `src/tokens/derived.css`; no algorithm derives them. Four contrast suites read that file and hold every value to a threshold, and a fifth holds it to the seed's HUE (gh#648) — see below |
-| **Japanese UI convention — density, JP typography, form patterns** | **SmartHR**                                     | **NEW — this decision.** Extends SmartHR from "where the colours came from" to the authority for how a JP business screen behaves                    |
-| **Japanese accessibility / public-sector convention**              | **デジタル庁 Design System** (Digital Agency)   | **NEW — this decision.** The reference when a JP customer asks which standard a screen meets (JIS X 8341-3)                                          |
-| **Spacing, density, type scale, information architecture**         | **IBM Carbon**                                  | **NEW — this decision**                                                                                                                              |
+| **Derived colour — the interaction states hanging off each seed**  | **Measured contrast (WCAG 2.2 / JIS X 8341-3)** | Authored in `src/tokens/derived.css`; no algorithm derives them. Four contrast suites read that file and hold every value to a threshold, and a fifth holds it to the seed's HUE (gh#648) — see below      |
+| **Japanese UI convention — density, JP typography, form patterns** | **SmartHR**                                     | **NEW — this decision.** Extends SmartHR from "where the colours came from" to the authority for how a JP business screen behaves                                                                          |
+| **Japanese accessibility / public-sector convention**              | **デジタル庁 Design System** (Digital Agency)   | **NEW — this decision.** The reference when a JP customer asks which standard a screen meets (JIS X 8341-3)                                                                                                |
+| **Spacing, density, type scale, information architecture**         | **IBM Carbon**                                  | **NEW — this decision**                                                                                                                                                                                    |
 
 The first five were already true and merely unwritten. The last three are the choices being made
 here. Carbon fills the one layer that had no outside answer at all: page rhythm, table density, form layout,
@@ -282,6 +282,87 @@ bottomEnd | none` (`TablePaginationPositionProp`, default `['bottomEnd']`), the
   rows, so an expanded detail row shifts every stripe after it, and `ui-audit` blocks the
   utilities it would need.
 
+- **`Masonry.gap` is antd `gutter`, and its breakpoint steps are this library's (gh-masonry
+  port).** Three divergences on one component, each for a reason already written down elsewhere in
+  this file:
+
+  1. **`gutter` → `gap`.** antd's `gutter` takes a raw pixel number (or a per-breakpoint map of
+     them). This library already owns that axis under the name `gap` on `Flex`, `ResponsiveGrid`
+     and `AuthStack`, `check:prop-vocabulary` maps a field called `gap` to `GapProp`, and a token
+     step is what makes spacing follow `--scaling` (density) and a tenant theme. "This library's
+     controlled vocabulary wins on values" is the rule; here it wins on the name too, because the
+     name and the value type move together. antd's tuple `[Gap, Gap]` survives as
+     `[GapProp, GapProp]` = `[inline, block]`. **`gutter` is not silently absent**: it is declared
+     on the prop type as `never`, so a consumer arriving from antd's docs gets a compile error and
+     a `@deprecated` hint naming `gap`, plus a development-time `console.warn`.
+  2. **`columns` steps are `base sm md lg xl`, not antd's `xs sm md lg xl xxl`.** antd's `xs` IS
+     this library's `base` (the mobile-first floor), and a second spelling of one axis is what
+     `check:prop-vocabulary` exists to prevent; `xxl` has no step here at all. `Flex direction`
+     is the precedent shape and the media queries are literally the `--flex-direction-*` cascade's
+     (sm 40rem · md 48rem · lg 64rem · xl 80rem). Both antd spellings FAIL LOUDLY — TypeScript
+     rejects them as excess properties and the component names them in a development warning —
+     because a silently-ignored `xs` is the worst outcome of the three.
+  3. **`MasonryItem.height` is HONOURED, where antd declares it and never reads it.** Verified in
+     antd `master`: `Masonry.tsx` builds every `ItemHeightData` from `getBoundingClientRect()`
+     alone, and all six demos carry their heights in `data`. Porting the field as inert would ship
+     a documented prop that does nothing. Here a finite `height` sizes the tile and replaces its
+     measurement, which is also what lets a first paint and an SSR render land in the right place.
+
+  Not ported, each under a rule that already exists: `classNames` / `styles` (a knob only a fork
+  could reach — `src/tokens/components/masonry.css` is the answer), `prefixCls` / `rootClassName`
+  (no `prefixCls` layer here), and rc-motion's tile-REMOVAL animation (the arrival fade and the
+  re-flow slide are ported in CSS and both snap under `prefers-reduced-motion`). `fresh` keeps
+  antd's name and antd's `false` default even though `docs/roadmap/list-masonry.md` (2026-09-10)
+  proposed renaming it `observeItems` and defaulting it on — that proposal predates the
+  2026-09-12 restatement above, and "the antd name says nothing" is exactly the reasoning the
+  restatement rejects. The same roadmap's invented `sequential` prop is not ported for the same
+  reason: antd has no such knob, and improvements come after parity, not instead of it.
+
+- **`Affix` and `Anchor` take the LOGICAL axis where antd takes the physical one (gh#827/gh#828).**
+  Ported from `ant-design@master`, read out of `components/affix/{index.tsx,utils.ts}` and
+  `components/anchor/{Anchor,AnchorLink}.tsx` on 2026-09-21, not out of the docs tables. Every
+  antd prop is present. Four renames, and nothing else:
+
+  1. **`offsetTop` → `offsetBlockStart`, `offsetBottom` → `offsetBlockEnd`** (both components;
+     `Anchor.targetOffset` → `targetOffsetBlockStart` with it). `check:rtl` exists to keep
+     `inset-block-start` out of `top`'s hands in every stylesheet here, and a prop that names a
+     physical edge re-opens that door at the API. It is also load-bearing rather than cosmetic:
+     the offset is a CSS custom property (`--affix-inset-block-start`), read once by the sentinel
+     that detects the crossing and once by the pinned bar that paints it, so the name has to be
+     the one CSS uses. All three antd spellings are declared `never` — a compile error carrying an
+     `@deprecated` hint that names the replacement — plus a development `console.warn`, plus the
+     MCP catalog entry. The `Masonry gutter → gap` precedent, applied to a second component.
+  2. **`Anchor.onChange` → `onValueChange`,** beside new `value` / `defaultValue`. The active
+     `href` is a controlled value and this library has one spelling for that. antd has no
+     controlled form of it at all (`getCurrentAnchor` is a transform of the computed answer, not a
+     value), so this is an ADDITION with a rename attached rather than a substitution, and
+     `getCurrentAnchor` is ported unchanged beside it — a controlled `value` simply outranks it.
+     antd's own note is ported too: `onValueChange` reports the link the SCROLL POSITION resolved,
+     not the one `getCurrentAnchor` substituted.
+
+  **`Affix.onChange` is NOT renamed**, and the distinction is the point: there is no pinned VALUE
+  to control, only an observation of a derived boolean, so no triad applies. `Attachments.onChange`
+  and `ActionsFeedback.onChange` already carry antd's name with a non-DOM payload for the same
+  reason.
+
+  **Not ported, each under a rule that already exists:** `classNames` / `styles` on `Anchor` (a
+  knob only a fork could reach — `src/tokens/components/anchor.css` is the answer),
+  `prefixCls` / `rootClassName`, and antd's deprecated `Anchor children` / `Anchor.Link` JSX form
+  (antd itself warns on it and says to use `items`).
+
+  **One deliberate behavioural difference, in `Anchor`.** antd resolves from scroll position on
+  mount unconditionally, which overwrites a landing hash on any page whose hashed section happens
+  to be above the fold. Here the hash is read in the state INITIALISER and the mount resolution is
+  skipped when it matched, so `/page#section` is correct on the first render with no scroll event
+  ever firing — which is gh#828's acceptance criterion, and the one place antd's behaviour is
+  worse rather than merely differently named.
+
+  **Two things antd does not have at all**, both required by the contract rather than invented:
+  `Anchor.label` (antd ships an unnamed `<div>`; a `<nav>` landmark on a page that already has a
+  breadcrumb and a rail must be named, so `label` defaults through `t()`), and `Affix`'s
+  `scroll-padding-block-start` on the scroll box while pinned (WCAG 2.4.11 — without it the pinned
+  bar covers whatever the browser scrolls a focused element to).
+
 - **`Command.split` is antd `List.split`, with this library's default.** Same name, same meaning:
   a divider between rows and none after the last (gh#699). antd's `List` defaults it to `true`;
   `Command` defaults it to `false`, because its resting home is a command palette, where inset
@@ -501,11 +582,11 @@ snapped to the seed's hue (1.008:1 / 1.010:1 from the kit value, i.e. the same c
 the kit's `action.primary.hover` and then reflects the pressed step, because the dark seed sits at
 86.9% L and the conventional step runs out of LIGHTNESS rather than out of contrast:
 
-| token                    | conventional step        | shipped                            |
-| ------------------------ | ------------------------ | ---------------------------------- |
-| light `--primary-hover`  | kit #6400D4              | #6500d4 · 8.23:1                   |
-| light `--primary-active` | kit #5200B0              | #5400b0 · 10.31:1                  |
-| dark `--primary-hover`   | kit #E8DAFF              | #ecdaff · 13.51:1                  |
+| token                    | conventional step            | shipped                         |
+| ------------------------ | ---------------------------- | ------------------------------- |
+| light `--primary-hover`  | kit #6400D4                  | #6500d4 · 8.23:1                |
+| light `--primary-active` | kit #5200B0                  | #5400b0 · 10.31:1               |
+| dark `--primary-hover`   | kit #E8DAFF                  | #ecdaff · 13.51:1               |
 | dark `--primary-active`  | #fbf7ff · 1.056:1 from white | #cd9fff · 8.41:1 (sign flipped) |
 
 **The ratio is blind to hue, and that cost a release (gh#648).** Identity v2.3 moved the seed 63
@@ -604,10 +685,10 @@ the **field** indicator on every control — one hairline (1px) in the focus hue
 `--control-outline` halo — rather than the heavy 3px outline form. Measured, in Chromium, on
 `ql.test` after the transition settles:
 
-| control                    | switch off                                           | switch on                                                      |
-| -------------------------- | ---------------------------------------------------- | -------------------------------------------------------------- |
+| control                    | switch off                                           | switch on                                                       |
+| -------------------------- | ---------------------------------------------------- | --------------------------------------------------------------- |
 | Input / Select trigger     | border `1px rgb(144,135,127)`, resting shadow intact | border `1px` of `--ring` + `--control-outline` halo `0 0 0 2px` |
-| Button (primary)           | outline `0px`, resting shadow intact                 | `outline: 1px solid` `--ring` @ `0px` + same halo              |
+| Button (primary)           | outline `0px`, resting shadow intact                 | `outline: 1px solid` `--ring` @ `0px` + same halo               |
 | Sidebar nav row / list row | outline `0px`                                        | `outline: 1px solid` `--ring` @ **`-1px`** (inset into the row) |
 
 The GEOMETRY above is the Chromium measurement; the COLOUR is named by token rather than pinned as

package/docs/FRAME-COVERAGE-REPORT.md

@@ -3,8 +3,8 @@
 > Generated by `scripts/frame-coverage.mjs` (issue #163). Do not edit by hand — run `pnpm check:frame-coverage`.
 > Standard: [FRAME-COVERAGE-STANDARD.md](./FRAME-COVERAGE-STANDARD.md). A missing dimension is **UNTESTED**, never a pass.
 
-- Public components: **165**
-- With ≥1 frame: **144** · zero-frame: **21**
+- Public components: **170**
+- With ≥1 frame: **149** · zero-frame: **21**
 - Fully covered (every contract axis declared): **0**
 
 ## UNTESTED — no `/frame/**` route
@@ -198,8 +198,13 @@ Legend: ✓ covered · N/A reasoned skip · · UNTESTED (blank cell = UNTESTED).
 | ChatComposer | ✓ | · | · | · | · | · | · | · | · | · |
 | ChatSuggestion | ✓ | N/A | N/A | · | · | · | · | · | · | · |
 | Conversations | ✓ | N/A | N/A | N/A | · | · | · | · | · | · |
+| MegaMenu | ✓ | · | N/A | · | · | · | · | · | · | · |
 | Welcome | ✓ | · | N/A | N/A | · | · | · | · | · | · |
 | Actions | ✓ | · | N/A | N/A | · | · | · | · | · | · |
 | ThoughtChain | ✓ | N/A | N/A | N/A | · | · | · | · | · | · |
 | Attachments | ✓ | N/A | · | N/A | · | · | · | · | · | · |
+| Marquee | ✓ | N/A | N/A | N/A | · | · | · | · | · | · |
+| Masonry | ✓ | N/A | N/A | N/A | · | · | · | · | · | · |
+| Affix | ✓ | N/A | N/A | N/A | · | · | · | · | · | · |
+| Anchor | ✓ | N/A | N/A | · | · | · | · | · | · | · |
 

package/docs/TOKENS.md

@@ -297,7 +297,22 @@ Instead, declare the knob `initial` (a real, catalogued, guaranteed-invalid decl
 }
 ```
 
-The same rule applies to `@theme inline` (utilities re-resolve scoped roles) and to any `:root`-declared **composite** that wraps a role (e.g. a focus-ring box-shadow): read the role **directly** at the call site, never through a frozen `:root` intermediate. Pure non-colour knobs (spacing, radius, font-size) don't need this — they aren't scope-retinted — but any colour/fill/ border/shadow knob whose default is a role token does.
+The same rule applies to `@theme inline` (utilities re-resolve scoped roles) and to any `:root`-declared **composite** that wraps a role (e.g. a focus-ring box-shadow): read the role **directly** at the call site, never through a frozen `:root` intermediate. Pure non-colour knobs (spacing, radius, font-size) don't need this **as long as nothing re-scopes what they read** — see the two paragraphs below, which is where that qualifier cost a release.
+
+**A DERIVED TIER FREEZES ON ITS OWN SEED — the `--font-size-*` ramp (gh#834).** The type scale is one base and one ratio, and every step used to be written `--font-size-5xl: var(--font-size-display)` / `--font-size-lg: calc(var(--font-size-base) * …)` on `:root`. Those substitute on `<html>`, so a `[data-tenant]` that re-seeds the base — the route level 3 of `docs/CUSTOMER-THEMING.md` documents, and which level 1 calls a seed — moved `text-base` and **nothing else**. Measured with `--font-size-base: 24px; --font-size-display: 80px` on a scope: 2xs/xs/sm/lg/xl/2xl/3xl/4xl/5xl all sat exactly where `:root` had left them, and a showcase whose comment read "80px hero via text-5xl" painted 54.
+
+So every **derived** step is now an `initial` knob and the formula lives at the call site, spelled in terms of the un-derived knobs only (`--font-size-base`, `--font-size-ratio`, `--font-size-display`, `--font-size-display-ratio`) — an `initial` knob cannot be chained through, so `xl` reads `base × ratio³` rather than `lg × ratio`:
+
+```css
+:root {
+  --font-size-5xl: initial;
+} /* documented default = var(--font-size-display) */
+[data-slot="text"][data-size="5xl"] {
+  font-size: var(--font-size-5xl, var(--font-size-display));
+}
+```
+
+**Every reader must carry the fallback**: a bare `var(--font-size-xs)` on an `initial` knob resolves to nothing, and the failure is silent and total. `check:frame-token-scope` is the gate that measures both halves — it fails on a step that stops following a scoped seed, and on a bare read of an empty knob.
 
 **The same freeze bites any knob whose default is a RE-SCOPED tier, colour or not.** `--control-height` is re-scoped by `.ui-auth-shell` (44px comfortable) and by `.ui-auth-shell[data-variant="canonical"]` (36px), so a knob that mirrors it must follow the same `initial` + call-site-fallback shape:
 

package/docs/data-display/marquee.tsx

@@ -0,0 +1,254 @@
+import { useState } from "react";
+
+import {
+  Badge,
+  Card,
+  CardContent,
+  CardDescription,
+  CardHeader,
+  CardTitle,
+  Marquee,
+} from "@godxjp/ui/data-display";
+import { Switch } from "@godxjp/ui/data-entry";
+import { Heading, Link, Text } from "@godxjp/ui/general";
+import { Flex, PageContainer, Separator } from "@godxjp/ui/layout";
+
+/**
+ * Marquee · a track of content that travels continuously, and the WCAG 2.2.2 pause control that
+ * makes that legal.
+ *
+ * Every card on this page is an EDGE, because the tidy demo is the one that hides the defects this
+ * component actually has:
+ * · ONE item in a full-width track, which is the case that needs the most clones;
+ * · FORTY items, which is the case that proves the pace is measured and not per-cycle;
+ * · a 71-character unbreakable string, wider than a phone;
+ * · a track NARROWER than one item, where there is nothing to clone into;
+ * · CJK beside Latin beside Vietnamese, at three different optical widths;
+ * · the paused state, which is where the content has to stay readable;
+ * · a controlled "stop all motion" switch driving two tracks at once.
+ *
+ * Composed only from real @godxjp/ui components. All copy is consumer-owned and localized.
+ */
+
+const PARTNERS = [
+  "フジワラ運輸",
+  "Meridian Foods",
+  "Công ty Đại Việt",
+  "北陸電機",
+  "Halden Systems",
+  "三和商会",
+  "Vinh Phat Logistics",
+  "東海システム",
+];
+
+/** Forty items · the case a per-cycle duration would send across the screen forty times too fast. */
+const FORTY = Array.from({ length: 40 }, (_, index) => `SKU-${String(index + 1).padStart(4, "0")}`);
+
+/** 71 characters, no break opportunity anywhere in it. */
+const UNBREAKABLE = "SUPPLYCHAINRECONCILIATIONBATCHIDENTIFIER2026Q3NOBREAKOPPORTUNITY0000001";
+
+export default function MarqueeDoc() {
+  const [motion, setMotion] = useState(true);
+
+  return (
+    <PageContainer title="Marquee" subtitle="連続して流れるトラックと、それを止める操作">
+      <Flex direction="col" gap="lg">
+        <Card>
+          <CardHeader>
+            <CardTitle level={2}>ロゴウォール · 既定のかたち</CardTitle>
+            <CardDescription>
+              `fade` で両端をマスクし、`pauseOnHover` を足した 8 件。コピー数は測って決まる（内容幅
+              ÷ 表示幅 + 1）ので、ウィンドウを横に伸ばせばクローンが増える。停止ボタンは常にあり、
+              Tab で到達できる。各社名はリンクなので、トラック内にフォーカスが入ると自動で止まる
+              （動いているリンクは押せないため）。クローン側のリンクは Tab の順路に出てこない。
+            </CardDescription>
+          </CardHeader>
+          <CardContent>
+            <Marquee fade pauseOnHover label="取引先ロゴ">
+              {PARTNERS.map((name) => (
+                <Link key={name} href={`#partner-${encodeURIComponent(name)}`}>
+                  {name}
+                </Link>
+              ))}
+            </Marquee>
+          </CardContent>
+        </Card>
+
+        <Card>
+          <CardHeader>
+            <CardTitle level={2}>1 件 と 40 件 · 速度は件数で変わらない</CardTitle>
+            <CardDescription>
+              1 周の所要時間ではなく「1 画面ぶんを流れる時間」が `--marquee-interval` なので、1
+              件でも 40 件でも見た目の速さは同じ。1 件のトラックはクローンが最も多く、 40
+              件のトラックはクローンが 1 枚で足りる。
+            </CardDescription>
+          </CardHeader>
+          <CardContent>
+            <Flex direction="col" gap="md">
+              <Heading level={3}>1 件</Heading>
+              <Marquee label="在庫同期の状態">
+                <Badge tone="info">在庫同期 · 実行中</Badge>
+              </Marquee>
+              <Separator />
+              <Heading level={3}>40 件</Heading>
+              <Marquee label="処理中の SKU">
+                {FORTY.map((sku) => (
+                  <Text key={sku} size="xs" tone="muted">
+                    {sku}
+                  </Text>
+                ))}
+              </Marquee>
+            </Flex>
+          </CardContent>
+        </Card>
+
+        <Card>
+          <CardHeader>
+            <CardTitle level={2}>折り返せない 71 文字と、1 件より狭いトラック</CardTitle>
+            <CardDescription>
+              分割点のない 71 文字は電話の画面より広い。狭い枠に入れると「表示幅 ÷ 内容幅」は 1
+              を下回るので、クローンは最小の 1 枚になり、それでも継ぎ目なく回る。
+            </CardDescription>
+          </CardHeader>
+          <CardContent>
+            <Flex direction="col" gap="md">
+              <Heading level={3}>全幅</Heading>
+              <Marquee label="照合バッチ識別子">
+                <Text size="sm">{UNBREAKABLE}</Text>
+              </Marquee>
+              <Separator />
+              <Heading level={3}>幅 14rem · 1 件より狭い枠</Heading>
+              <div style={{ inlineSize: "14rem", maxInlineSize: "100%" }}>
+                <Marquee label="照合バッチ識別子・狭い枠">
+                  <Text size="sm">{UNBREAKABLE}</Text>
+                </Marquee>
+              </div>
+            </Flex>
+          </CardContent>
+        </Card>
+
+        <Card>
+          <CardHeader>
+            <CardTitle level={2}>日本語 · Latin · Tiếng Việt が同じ行に並ぶ</CardTitle>
+            <CardDescription>
+              全角の仮名漢字、欧文、そしてダイアクリティカルの付いたベトナム語は 1 文字あたりの幅も
+              行の高さも違う。同じトラックに置いたときの継ぎ目とベースラインはここで見る。
+              `direction="end"` は読み方向の逆に流れる版で、`dir="rtl"` では両方が反転する。
+            </CardDescription>
+          </CardHeader>
+          <CardContent>
+            <Flex direction="col" gap="md">
+              <Marquee gap={6} speed="slow" label="多言語の見出し">
+                <Text size="sm">品質保証部 · 月次レビュー</Text>
+                <Text size="sm">Quality Assurance · Monthly review</Text>
+                <Text size="sm">Đảm bảo chất lượng · Đánh giá hàng tháng</Text>
+              </Marquee>
+              <Separator />
+              <Marquee gap={6} speed="fast" direction="end" label="多言語の見出し・逆方向">
+                <Text size="sm">品質保証部 · 月次レビュー</Text>
+                <Text size="sm">Quality Assurance · Monthly review</Text>
+                <Text size="sm">Đảm bảo chất lượng · Đánh giá hàng tháng</Text>
+              </Marquee>
+            </Flex>
+          </CardContent>
+        </Card>
+
+        <Card>
+          <CardHeader>
+            <CardTitle level={2}>止まった状態 · WebAIM の推奨する既定</CardTitle>
+            <CardDescription>
+              `defaultPlay={false}` で始めると、内容は止まったまま読める。停止中もリンクは Tab
+              で辿れて、押せる。動いている最中にトラック内へフォーカスが入った場合も自動で止まる
+              （動いているリンクは押せないため）。ボタンの名前は「次に起きること」を言う。
+            </CardDescription>
+          </CardHeader>
+          <CardContent>
+            <Marquee defaultPlay={false} fade label="社内のお知らせ">
+              <Text size="sm">2026-10-01 · 社内システム定期メンテナンス</Text>
+              <Link href="#maintenance">詳細</Link>
+              <Text size="sm">2026-10-14 · 新しい経費申請フォームに切替</Text>
+              <Link href="#expense">申請の手順</Link>
+            </Marquee>
+          </CardContent>
+        </Card>
+
+        <Card>
+          <CardHeader>
+            <CardTitle level={2}>`play` で外から止める</CardTitle>
+            <CardDescription>
+              制御された `play` / `onPlayChange` は、画面全体の「動きを止める」1
+              つのスイッチから複数のトラックを同時に止めるためにある。各トラックの停止ボタンは
+              そのまま残る（2.2.2 の要件は個々の操作で満たす）。
+            </CardDescription>
+          </CardHeader>
+          <CardContent>
+            <Flex direction="col" gap="md">
+              <Flex align="center" gap="sm">
+                <Switch
+                  id="stop-all-motion"
+                  checked={motion}
+                  onCheckedChange={setMotion}
+                  aria-label="このページの動きを有効にする"
+                />
+                <Text size="sm">
+                  {motion ? "このページの動きは有効" : "このページの動きは停止中"}
+                </Text>
+              </Flex>
+              <Marquee play={motion} onPlayChange={setMotion} label="取引先ロゴ・上段">
+                {PARTNERS.slice(0, 4).map((name) => (
+                  <Text key={name} size="sm" tone="muted">
+                    {name}
+                  </Text>
+                ))}
+              </Marquee>
+              <Marquee
+                play={motion}
+                onPlayChange={setMotion}
+                direction="end"
+                label="取引先ロゴ・下段"
+              >
+                {PARTNERS.slice(4).map((name) => (
+                  <Text key={name} size="sm" tone="muted">
+                    {name}
+                  </Text>
+                ))}
+              </Marquee>
+            </Flex>
+          </CardContent>
+        </Card>
+
+        <Card>
+          <CardHeader>
+            <CardTitle level={2}>使う前に読むこと</CardTitle>
+          </CardHeader>
+          <CardContent>
+            <Flex direction="col" gap="sm">
+              <Heading level={3}>止められる動きでも、止まっている方が良いことは多い</Heading>
+              <Text tone="muted">
+                自動で流れる内容は Nielsen Norman Group も WebAIM も勧めていない。NN/g
+                は「ユーザーが操作していないのに画面が動くのは不快で、読み終える前に消える」と書き、
+                WebAIM は「アニメーションは既定で止めておくことを勧める」と書いている。この
+                コンポーネントはその判断を奪わない。止める操作は必ず付いてくるし、`defaultPlay=
+                {"{false}"}` は 1 つのプロパティで済む。動かす理由が言えないなら、静止した `Flex
+                wrap` や `ResponsiveGrid` のロゴウォールの方が良い。
+              </Text>
+              <Heading level={3}>OS のモーション低減設定では一切動かない</Heading>
+              <Text tone="muted">
+                `prefers-reduced-motion: reduce` のとき、クローンも停止ボタンも作らず、1
+                件ぶんの内容を横スクロールできる領域として出す。横方向の平行移動は前庭系の
+                トリガーそのもので、控えめにする版というものが無いため（WCAG 2.2 SC 2.2.2 / SC
+                2.3.3）。
+              </Text>
+              <Heading level={3}>テーマ側のつまみ</Heading>
+              <Text tone="muted">
+                --marquee-interval · --marquee-interval-slow · --marquee-interval-fast ·
+                --marquee-gap-inline · --marquee-mask-width。時間はモーション層
+                （foundation.css）に、幾何はコンポーネント層（tokens/components/marquee.css）にある。
+              </Text>
+            </Flex>
+          </CardContent>
+        </Card>
+      </Flex>
+    </PageContainer>
+  );
+}