@godxjp/ui 20.2.1 → 22.0.0

package/docs/data-entry/segmented.tsx

@@ -2,7 +2,7 @@ import { useState } from "react";
 
 import { Card, CardContent, CardDescription, CardHeader, CardTitle } from "@godxjp/ui/data-display";
 import { FormField, Segmented } from "@godxjp/ui/data-entry";
-import { Text } from "@godxjp/ui/general";
+import { Text, VisuallyHidden } from "@godxjp/ui/general";
 import { Flex, PageContainer } from "@godxjp/ui/layout";
 import { CalendarDays, Columns3, LayoutList, Monitor, Moon, Sun } from "lucide-react";
 
@@ -84,6 +84,108 @@ export default function Demo() {
           </CardContent>
         </Card>
 
+        <Card>
+          <CardHeader>
+            <CardTitle level={2}>size · vertical · block</CardTitle>
+            <CardDescription>
+              size は 3 段（sm / md / lg）。トラックの高さは --control-height そのもので、
+              MobileShell のようにその変数をスコープする領域では自動的にタッチ段（44px）になります。
+              vertical では 1 行ぶんが 1 コントロールの高さになります — 横 1 行のときだけトラック
+              内側の余白を引くので、積んだときは引きません。block は幅いっぱいに広げます。
+            </CardDescription>
+          </CardHeader>
+          <CardContent>
+            <Flex direction="col" gap="md" align="start">
+              <Segmented
+                aria-label="サイズ sm"
+                size="sm"
+                defaultValue="a"
+                options={[
+                  { value: "a", label: "小" },
+                  { value: "b", label: "中" },
+                  { value: "c", label: "大" },
+                ]}
+              />
+              <Segmented
+                aria-label="サイズ md"
+                defaultValue="b"
+                options={[
+                  { value: "a", label: "小" },
+                  { value: "b", label: "中" },
+                  { value: "c", label: "大" },
+                ]}
+              />
+              <Segmented
+                aria-label="サイズ lg"
+                size="lg"
+                defaultValue="c"
+                options={[
+                  { value: "a", label: "小" },
+                  { value: "b", label: "中" },
+                  { value: "c", label: "大" },
+                ]}
+              />
+              <Segmented
+                aria-label="縦積み"
+                vertical
+                block
+                defaultValue="ok"
+                options={[
+                  { value: "ok", label: "実施" },
+                  { value: "warn", label: "要改善" },
+                  { value: "none", label: "未実施" },
+                ]}
+              />
+            </Flex>
+          </CardContent>
+        </Card>
+
+        <Card>
+          <CardHeader>
+            <CardTitle level={2}>短い記号を出して、長い名前を読ませる</CardTitle>
+            <CardDescription>
+              `label` は ReactNode なので、見える記号を aria-hidden にして VisuallyHidden に
+              読み上げ名を置けます。専用の prop は要りません。○ と読み上げられても意味が伝わらない
+              ため、色や記号だけに意味を持たせないという WCAG 1.4.1 の要求そのものです。
+            </CardDescription>
+          </CardHeader>
+          <CardContent>
+            <Segmented
+              aria-label="監査結果"
+              defaultValue="ok"
+              options={[
+                {
+                  value: "ok",
+                  label: (
+                    <>
+                      <span aria-hidden="true">○</span>
+                      <VisuallyHidden>実施</VisuallyHidden>
+                    </>
+                  ),
+                },
+                {
+                  value: "warn",
+                  label: (
+                    <>
+                      <span aria-hidden="true">△</span>
+                      <VisuallyHidden>要改善</VisuallyHidden>
+                    </>
+                  ),
+                },
+                {
+                  value: "none",
+                  label: (
+                    <>
+                      <span aria-hidden="true">×</span>
+                      <VisuallyHidden>未実施</VisuallyHidden>
+                    </>
+                  ),
+                },
+              ]}
+            />
+          </CardContent>
+        </Card>
+
         <Card>
           <CardHeader>
             <CardTitle level={2}>フォームの中で</CardTitle>

package/docs/layout/mobile-shell.tsx

@@ -32,6 +32,11 @@ export default function Demo() {
 
   return (
     <MobileShell
+      // `width="phone"` because this frame is READ ON A DESKTOP. The shell's own docstring already
+      // named this case on the block axis (`height="fill"` for "a phone view embedded in a wider
+      // page"); the inline axis had no answer until now, so this page drew a 1232px-wide handheld
+      // app with its four tab-bar destinations spread across the screen.
+      width="phone"
       statusBar={
         <>
           <Text size="sm" weight="medium" tabular>

package/docs/navigation/tabs.tsx

@@ -1,5 +1,7 @@
 import { useState } from "react";
 
+import { Trash2 } from "lucide-react";
+
 import { Card, CardContent, CardDescription, CardHeader, CardTitle } from "@godxjp/ui/data-display";
 import { Button, Text } from "@godxjp/ui/general";
 import { Flex, PageContainer } from "@godxjp/ui/layout";
@@ -44,8 +46,45 @@ const journalItems = [
   },
 ];
 
+/**
+ * 20 saved views with real Japanese labels — a strip that is wider than 1920px, so it overflows at
+ * EVERY width the browser gates sweep. `scripts/check-tabs-overflow-menu.mjs` measures this frame;
+ * it fails if the strip ever stops overflowing, because a gate over a bar that fits proves nothing.
+ */
+const savedViewItems = [
+  { value: "all", label: "すべての仕訳", content: <Text as="p">全 1,284 件</Text> },
+  { value: "pending", label: "未承認の仕訳", content: <Text as="p">未承認 2 件</Text> },
+  { value: "posted", label: "承認済の仕訳", content: <Text as="p">承認済 48 件</Text> },
+  { value: "voided", label: "取消済の仕訳", content: <Text as="p">取消済 3 件</Text> },
+  { value: "returned", label: "差戻しの仕訳", content: <Text as="p">差戻し 5 件</Text> },
+  { value: "draft", label: "下書きの仕訳", content: <Text as="p">下書き 12 件</Text> },
+  { value: "recurring", label: "定期仕訳のひな形", content: <Text as="p">ひな形 7 件</Text> },
+  { value: "accrual", label: "未払費用の計上", content: <Text as="p">未払費用 9 件</Text> },
+  { value: "prepaid", label: "前払費用の振替", content: <Text as="p">前払費用 4 件</Text> },
+  { value: "payroll", label: "給与支払の仕訳", content: <Text as="p">給与 3 件</Text> },
+  { value: "tax", label: "消費税の集計", content: <Text as="p">消費税 6 件</Text> },
+  { value: "closing", label: "決算整理の仕訳", content: <Text as="p">決算整理 11 件</Text> },
+  { value: "audit", label: "監査対象の仕訳", content: <Text as="p">監査対象 8 件</Text> },
+  {
+    value: "archived",
+    label: "アーカイブ済の仕訳",
+    content: <Text as="p">アーカイブ 214 件</Text>,
+  },
+  { value: "fx", label: "外貨建の換算差額", content: <Text as="p">換算差額 2 件</Text> },
+  { value: "intercompany", label: "関係会社間の取引", content: <Text as="p">関係会社 15 件</Text> },
+  {
+    value: "fixed-asset",
+    label: "固定資産の減価償却",
+    content: <Text as="p">減価償却 22 件</Text>,
+  },
+  { value: "inventory", label: "棚卸資産の評価替", content: <Text as="p">評価替 6 件</Text> },
+  { value: "bank", label: "銀行勘定の照合", content: <Text as="p">未照合 4 件</Text> },
+  { value: "reversal", label: "翌期首の振戻し", content: <Text as="p">振戻し 9 件</Text> },
+];
+
 export default function Demo() {
   const [activeTab, setActiveTab] = useState("pending");
+  const [reopened, setReopened] = useState(0);
   const [editableTabs, setEditableTabs] = useState([
     { value: "je-0042", label: "JE-0042", content: <Text as="p">売上計上 ¥480,000</Text> },
     { value: "je-0043", label: "JE-0043", content: <Text as="p">仕入計上 ¥120,000</Text> },
@@ -367,6 +406,116 @@ export default function Demo() {
           </CardContent>
         </Card>
 
+        {/* antd `more` — overflow="menu" beside the default overflow="scroll" */}
+        <Card>
+          <CardHeader>
+            <CardTitle level={2}>overflow · scroll(既定) / menu</CardTitle>
+            <CardDescription>
+              antd の more をこのライブラリの overflow 語彙に写したもの。既定の scroll
+              は今までどおり、帯が自分の水平オーバーフローをスクロールする。menu
+              はそれに加えて、帯の外に「他のタブ」ボタンを出し、いま見えていないタブだけを並べる ·
+              antd と違いタブは帯から取り除かれない(tablist はタブ以外を持てず、display:none
+              のタブはロービングフォーカスを受け取れないため · WAI-ARIA APG)。
+            </CardDescription>
+          </CardHeader>
+          <CardContent>
+            <Flex direction="col" gap="lg">
+              <Flex direction="col" gap="sm">
+                <Text as="p" size="sm" tone="muted">
+                  overflow=&quot;scroll&quot;(既定)
+                </Text>
+                <Tabs
+                  id="antd-overflow-scroll"
+                  defaultValue="all"
+                  variant="line"
+                  items={savedViewItems}
+                />
+              </Flex>
+              <Flex direction="col" gap="sm">
+                <Text as="p" size="sm" tone="muted">
+                  overflow=&quot;menu&quot;
+                </Text>
+                <Tabs
+                  id="antd-overflow-menu"
+                  defaultValue="all"
+                  variant="line"
+                  overflow="menu"
+                  items={savedViewItems}
+                />
+              </Flex>
+            </Flex>
+          </CardContent>
+        </Card>
+
+        {/* antd onTabClick / removeIcon / Tab.forceRender */}
+        <Card>
+          <CardHeader>
+            <CardTitle level={2}>onTabClick · closeIcon · forceRender</CardTitle>
+            <CardDescription>
+              onTabClick は antd の onTabClick で、ポインタで押されたときだけ発火し DOM の
+              MouseEvent を渡す(キーボードは activationMode=&quot;manual&quot;
+              でフォーカス移動と選択が分かれるため発火しない · 選択は onValueChange
+              が担当)。closeIcon は antd の removeIcon で、タブ全体の既定グリフを差し替える(item
+              側の closeIcon が優先)。item の forceRender は antd の Tab.forceRender
+              で、そのパネルだけを先にマウントし、他のタブに 切り替えても保持する。
+            </CardDescription>
+          </CardHeader>
+          <CardContent>
+            <Flex direction="col" gap="md">
+              <Text as="p" size="sm" tone="muted">
+                同じタブを押し直した回数: {reopened}
+              </Text>
+              <Tabs
+                id="antd-tab-click"
+                defaultValue="pending"
+                variant="line"
+                onTabClick={(value) => {
+                  if (value === activeTab) setReopened((count) => count + 1);
+                  setActiveTab(value);
+                }}
+                items={[
+                  {
+                    value: "pending",
+                    label: "未承認",
+                    content: <Text as="p">未承認の仕訳が 2 件あります。</Text>,
+                  },
+                  {
+                    value: "chart",
+                    label: "推移グラフ",
+                    // The one panel that must survive a tab switch — antd Tab.forceRender.
+                    forceRender: true,
+                    content: <Text as="p">月次推移: 4 月 ¥3,120,000 · 5 月 ¥4,820,000</Text>,
+                  },
+                  {
+                    value: "posted",
+                    label: "承認済",
+                    content: <Text as="p">当期承認済: 48 件</Text>,
+                  },
+                ]}
+              />
+              <Tabs
+                id="antd-remove-icon"
+                variant="editable-card"
+                defaultValue="je-0042"
+                closeIcon={<Trash2 aria-hidden="true" />}
+                onEdit={() => undefined}
+                items={[
+                  {
+                    value: "je-0042",
+                    label: "JE-0042",
+                    content: <Text as="p">売上計上 ¥480,000</Text>,
+                  },
+                  {
+                    value: "je-0043",
+                    label: "JE-0043",
+                    content: <Text as="p">仕入計上 ¥120,000</Text>,
+                  },
+                ]}
+              />
+            </Flex>
+          </CardContent>
+        </Card>
+
         <Card>
           <CardHeader>
             <CardTitle level={2}>tabPlacement · size · centered</CardTitle>

package/docs/roadmap/ai-chat-components.md

@@ -0,0 +1,207 @@
+# AI / chatbot components — normalized spec
+
+> **Reference:** Ant Design X (<https://x.ant.design/components/overview>) for *capabilities*.
+> **Naming:** when a component's identity is unclear, look it up at
+> <https://namethatui.com/?platform=web> before inventing a name.
+> **Contract:** `.claude/skills/godxjp-ui-component/SKILL.md` is the hard gate — MCP-first, real
+> primitives only, `t()` + `Intl`, WAI-ARIA APG + WCAG 2.2 AA + vitest-axe, logical CSS, controlled
+> vocabulary, semantic tokens, MCP catalog entry, real-screen docs page.
+
+The library has **zero** chat/AI components today (verified against `mcp/src/data/components.ts` —
+127 entries, none of them conversational). This document decides which of Ant Design X's surface
+becomes a framework component and which is a composition, so no agent has to re-litigate it.
+
+## 1. Scope decision — GATE 0 applied to every Ant Design X component
+
+`docs/COMPOSITION-VS-COMPONENT.md` C1–C7. **Any FAIL ⇒ composition, never `src/components/`.**
+
+| Ant Design X | godx name | Group | C1 | C2 | C3 | C4 | C5 | C6 | C7 | Verdict |
+| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
+| `Bubble` | **`ChatBubble`** | `data-display` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | **Framework component** |
+| `Bubble.List` | **`ChatBubbleList`** | `data-display` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | **Framework component** |
+| `Sender` | **`ChatComposer`** | `data-entry` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | **Framework component** |
+| `Suggestion` | **`ChatSuggestion`** | `data-entry` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | **Framework component** |
+| `Conversations` | **`ConversationList`** | `navigation` | ✅ | ✅ | ⚠️ | ✅ | ✅ | ✅ | ✅ | **Verify C3 first** — see §6 |
+| `ThoughtChain` / `Think` | **`ThoughtChain`** | `data-display` | ✅ | ⚠️ | ⚠️ | ✅ | ✅ | ✅ | ⚠️ | **Verify C2/C3 first** — see §6 |
+| `Prompts` | — | — | ✅ | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ | **Composition** — `ResponsiveGrid` + `Card` + `Button` |
+| `Welcome` | — | — | ❌ | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ | **Composition** — static block, `EmptyState`-shaped |
+| `Actions` | — | — | ✅ | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ | **Composition** — `Button` + `DropdownMenu` |
+| `Attachments` / `FileCard` | — | — | ✅ | ✅ | ❌ | — | — | — | — | **Extend `Upload`** — duplicating it is an instant reject |
+| `CodeHighlighter` | — | — | — | — | ❌ | — | — | — | — | **Use `CodeBlock`** |
+| `Sources` | — | — | ✅ | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ | **Composition** — `ListRow` + `Badge` |
+| `XProvider` | — | — | — | — | ❌ | — | — | — | — | **Use `AppProvider`** |
+| `Mermaid` | — | — | ❌ | — | — | — | — | — | ❌ | **Out of scope** |
+| `Folder/File Tree` | — | — | — | — | ❌ | — | — | — | — | **Covered by `Tree`** — see `docs/roadmap/tree-components.md` |
+
+**v1 build set: `ChatBubble`, `ChatBubbleList`, `ChatComposer`, `ChatSuggestion`** (4 components,
+all 7/7 PASS). `ConversationList` and `ThoughtChain` are conditional — §6.
+Everything else ships as a `docs/` showcase composition, not library code.
+
+---
+
+## 2. `ChatBubble` — one message in a conversation
+
+**Group:** `data-display` · **File:** `src/components/data-display/chat-bubble.tsx`
+
+| Ant Design X | **godx `ChatBubble`** |
+| --- | --- |
+| `content` | `children` (a `ReactNode`; do not take an HTML string) |
+| `placement: 'start' \| 'end'` | `placement: 'start' \| 'end'` (logical — flips under RTL) |
+| `variant: 'filled' \| 'borderless' \| 'outlined' \| 'shadow'` | `variant: 'filled' \| 'borderless' \| 'outlined'` (drop `shadow`; the design system is 1px-border, no drop shadows) |
+| `avatar` | `avatar` (a real `Avatar` node, never a styled div) |
+| `header` / `footer` | `header` / `footer` |
+| `loading` | `loading` (renders `Skeleton`, `aria-busy="true"`) |
+| `typing` | `typing: boolean \| { step?: number; interval?: number }` |
+| `messageRender` | *dropped* — the caller passes rendered `children` |
+| `shape` | *dropped* — corner radius is a token |
+| — | `size: 'xs' \| 'sm' \| 'lg'` (`md` default) |
+| — | `tone` for status-tinted bubbles (error/warning), never colour-only |
+
+**Semantics.** The bubble is an `<article>` inside the list's feed. Give it an accessible name from
+its `header` (the author). The typing animation MUST respect `prefers-reduced-motion: reduce` —
+render the full text immediately, no animation. Streaming text goes in an `aria-live="polite"`
+region owned by `ChatBubbleList`, **not** per-bubble (a live region per bubble floods a screen
+reader). Decorative avatars `aria-hidden`.
+
+**Tokens** (`src/tokens/components/chat-bubble.css`): `--chat-bubble-background`,
+`--chat-bubble-foreground`, `--chat-bubble-border-color`, `--chat-bubble-radius`,
+`--chat-bubble-gap`, `--chat-bubble-max-inline-size`, `--chat-bubble-avatar-size`.
+Role-mirror knobs default to `initial` (`docs/TOKENS.md`).
+
+**i18n:** `chat.bubble.typing`, `chat.bubble.loading`, `chat.bubble.you`, `chat.bubble.assistant`.
+Timestamps via `Intl.DateTimeFormat`; "2 minutes ago" via `Intl.RelativeTimeFormat`; counted nouns
+via `Intl.PluralRules` — never a template string.
+
+---
+
+## 3. `ChatBubbleList` — the message feed
+
+**Group:** `data-display` · **File:** same module as `ChatBubble`
+
+| Ant Design X `Bubble.List` | **godx `ChatBubbleList`** |
+| --- | --- |
+| `items` | `items: ChatMessageProp[]` |
+| `roles` | `roles: Record<string, Partial<ChatBubbleProp>>` — per-role defaults (`user`, `assistant`, `system`) |
+| `autoScroll` | `autoScroll` (default `true`) |
+
+**The behavior that earns C2/C3** — none of it is composable from `ScrollArea` + `map`:
+
+1. **Stick-to-bottom.** Auto-scroll while the user is at the bottom; the moment they scroll up,
+   **stop** and surface a "jump to latest" affordance. Silently yanking a reader back to the bottom
+   mid-read is the classic chat-UI defect.
+2. **Streaming without layout thrash** — appended text must not re-scroll the whole feed.
+3. **One `aria-live="polite"` region** for the whole feed, announcing only the newest message.
+4. `role="log"` on the scroll container, `aria-label` via `t()`.
+5. Keyboard: the feed is focusable and scrollable with `PageUp`/`PageDown`/`Home`/`End`; bubbles
+   are not a roving-tabindex widget (interactive controls inside them keep normal tab order).
+
+---
+
+## 4. `ChatComposer` — the message input (Ant's `Sender`)
+
+**Group:** `data-entry` · **File:** `src/components/data-entry/chat-composer.tsx`
+
+Named for what the industry calls it (Slack/Discord "composer"); `Sender` describes the person,
+not the control.
+
+| Ant Design X `Sender` | **godx `ChatComposer`** |
+| --- | --- |
+| `value` / `onChange` | `value` / `defaultValue` / `onValueChange` (**controlled triad — mandatory**) |
+| `onSubmit` | `onSubmit(value: string)` |
+| `loading` + `onCancel` | `loading` + `onCancel` |
+| `submitType: 'enter' \| 'shiftEnter'` | `submitType: 'enter' \| 'shiftEnter'` |
+| `placeholder` | `placeholder` (through `t()` at the call site) |
+| `disabled` / `readOnly` | `disabled` / `readOnly` |
+| `header` (`Sender.Header`) | `header` slot |
+| `prefix` / `footer` / `actions` | `prefix` / `footer` / `actions` slots |
+| `allowSpeech` | **out of scope v1** — Web Speech API is not cross-browser; file a follow-up |
+| `autoSize` | always auto-sizing; not a prop |
+| — | `size: 'xs' \| 'sm' \| 'lg'` · `maxLength` · `status` |
+
+**Rules.**
+- Built on the real `Textarea` primitive and real `Button`s — **no raw `<textarea>`/`<button>`**.
+- Auto-grow between a min and max height expressed in `--control-height` tiers, then scroll
+  inside. **No literal `height` and no `calc(var(--control-height) ± …)`** (`check:control-sizing`).
+- `submitType="enter"`: `Enter` submits, `Shift+Enter` newline. `submitType="shiftEnter"`: the
+  inverse. IME composition must never submit — guard on `compositionstart`/`compositionend`
+  (this is the bug that breaks Japanese and Vietnamese input; it is not optional).
+- Empty or whitespace-only input does not submit; the submit button is `disabled` with an
+  accessible name, not merely greyed out.
+- While `loading`, the submit button becomes a cancel button — **one trailing action at a time**,
+  the same discipline as the picker trailing-action rule.
+- The textarea is the semantic focus target; forward the `FormField` label/helper/error contract
+  onto it via `pickFieldA11y` / `useFieldIdentity` — do not reinvent it (`src/lib/field-a11y.ts`).
+
+---
+
+## 5. `ChatSuggestion` — trigger-character autocomplete over the composer
+
+**Group:** `data-entry` · **File:** `src/components/data-entry/chat-suggestion.tsx`
+
+| Ant Design X `Suggestion` | **godx `ChatSuggestion`** |
+| --- | --- |
+| `items` | `items: SuggestionItemProp[]` (supports one level of `children`) |
+| `onSelect` | `onValueChange(value: string)` |
+| `block` | *dropped* — width follows the anchor |
+| render-prop `children({ onTrigger, onKeyDown })` | same shape — it wraps `ChatComposer` |
+| — | `triggerCharacter` (default `'/'`) · `open` / `defaultOpen` / `onOpenChange` |
+
+**Rules.** Compose the existing `Command` (cmdk) inside a `Popover` anchored to the composer — do
+**not** hand-roll a listbox; `Command` already ships correct ARIA. What this component owns is the
+part `Command` does not: detecting the trigger character in a textarea, tracking the query as the
+caret moves, and closing on `Escape`/blur/word-break. `Escape` returns focus to the textarea and
+leaves the typed text intact.
+
+---
+
+## 6. Conditional components — prove C3 before writing code
+
+Do **not** start these until the ledger is recorded in the PR description.
+
+**`ConversationList`** (Ant's `Conversations`). `NavList` already renders selectable rows with
+`aria-current="page"`, an icon column and a badge; `ListRow` covers short entity lists. Before
+building, answer in writing: what does a conversation list own that `NavList` does not?
+The honest candidates are date **grouping** (Today / Yesterday / Last 7 days — via
+`Intl.RelativeTimeFormat` + `Intl.DateTimeFormat`, never hand-rolled buckets), a **per-item
+overflow menu**, and **inline rename**. If those land as `NavList` props instead, that is the
+better outcome — extend `NavList` and close this out.
+
+**`ThoughtChain`** (Ant's `ThoughtChain` / `Think`). `Timeline` already has a 3-state per-item
+`status` (`done`/`current`/`pending`), an icon rail and ordinal/status variants; `Collapsible`
+owns disclosure. `ThoughtChain` = `Timeline` + per-item collapsible body + a streaming/pending
+state. Strongly prefer adding a `collapsible` affordance to `Timeline` over a new component.
+Whichever way it goes, the reasoning body must be collapsible, and the running step must be
+announced once via `aria-live="polite"` — not on every token.
+
+---
+
+## 7. Per-component definition of done
+
+Every component in the build set ships **all** of:
+
+1. `src/components/<group>/<name>.tsx` — real primitives only, logical CSS, `t()` for every string
+   and `aria-label`, `ref` forwarded, `...props` spread, `className` + `id` accepted.
+2. `XProp` + `XProp as XProps` in `src/props/components/<group>.prop.ts`, **registered in
+   `src/props/registry.ts`**.
+3. `src/tokens/components/<name>.css` + an `@import` in `src/tokens/base.css`; names pass
+   `check:token-tiers`; control boxes come from the `--control-height` tier.
+4. Keys in `src/i18n/messages/en.json`, `vi.json`, `ja.json` — all three, no exceptions.
+5. Tests in `src/components/<group>/__tests__/`: a behavior test using `@testing-library/user-event`
+   **and** a `<name>.a11y.test.tsx` with `expectNoA11yViolations` at **0 violations**.
+6. An `mcp/src/data/components.ts` entry (props / usage / useCases / related / example / rules) —
+   `check:mcp-sync` and `check:mcp-orphans` must pass.
+7. A real-screen docs page under `docs/<group>/` (AppShell + PageContainer + real primitives), not
+   a bare `Card` snippet.
+8. Export from the group's `index.ts`.
+
+Gates, then **only** the touched group's tests:
+
+```
+pnpm typecheck && pnpm lint && pnpm run audit \
+  && pnpm check:prop-vocabulary && pnpm check:mcp-sync && pnpm check:mcp-orphans \
+  && pnpm check:token-tiers && pnpm check:control-sizing && pnpm check:example-imports
+pnpm vitest run src/components/<group>/__tests__ --maxWorkers=2
+```
+
+`pnpm test` and a bare `pnpm vitest run` are **forbidden** — 506 files / 3700+ tests, and several
+agents on one machine takes the load past 90. The full suite is CI's job on the PR.