@godxjp/ui 20.2.1 → 22.0.0

package/docs/roadmap/antd-parity.md

@@ -0,0 +1,155 @@
+# Ant Design parity — the audit programme
+
+> The complaint is systemic: _"hầu hết các component thiếu tính năng so với Ant Design."_
+> This document is the **method**, so that 127 catalog entries can be audited by different agents
+> and still produce comparable, reviewable results. Per-component specs live in sibling files.
+
+## 0. Ground rules (a parity gap is not a licence to copy Ant Design)
+
+1. **Capabilities are the target; prop names are not.** Map every antd prop onto
+   `docs/PROPS-VOCABULARY.md` — controlled triad `value`/`defaultValue`/`onValueChange`,
+   overlays `open`/`defaultOpen`/`onOpenChange`, `size ∈ xs|sm|md|lg` (never `"default"`),
+   `tone` for status, positive booleans. Where the library already has a spelling
+   (`getRowId`, `gap`, `columns: {base,sm,md,lg}`, `count`/`overflowCount`/`showZero`), **reuse it**.
+   A third dialect of the same idea is the defect this repo keeps paying to fix.
+2. **GATE 0 still applies.** A missing antd component is not automatically a framework component.
+   Run the C1–C7 test in `docs/COMPOSITION-VS-COMPONENT.md` and publish the ledger. Ant ships
+   things that are compositions here (`Badge.Ribbon`, `Welcome`, `Prompts`).
+3. **Do not duplicate what exists.** Ant's `CheckableTag` is this library's `Toggle`. Ant's
+   searchable select is `Select showSearch`. Check the MCP catalog before proposing anything.
+4. **Do not port antd's mistakes.** Skip `styles={{…}}` inline-style twins (this system themes with
+   tokens), pixel `offset` pairs, and physical `left/right` spellings.
+5. **A gap is only real once measured.** Cite the file and line, or the absence of a grep hit.
+   "Looks less capable than antd" is not a finding.
+
+## 1. Spacing, geometry and token names — the rules already exist, so use them
+
+This library is instrumented with ~60 checkers. Anything you write — **a spec document included** —
+is machine-checkable, so check it before you hand it to anyone.
+
+**Spacing is not free-form.** `docs/SPACING.md` is binding:
+
+- Macro layout uses a **φ modular scale (≈1.618)**, _not_ the 8pt grid. `xs`/`sm` = 4px grid,
+  `md` = φ⁰, `lg` = φ¹, `xl` = φ². Applying Material's 8pt grid here is wrong, not "standard".
+- Tailwind `p-*` / `m-*` / `gap-*` are rejected by `no-utility-spacing`; hand-rolled `flex`/`grid`
+  by `no-utility-layout`. Rows are `<Flex>`, stacks `<Flex direction="col" gap>`, grids
+  `<ResponsiveGrid>`, page sections spaced by `<PageContainer>` itself.
+- **Card padding has a single owner**: `src/styles/card-layout.css`. Anything else that must sit on
+  the same rhythm uses `ui-card-inset-x` / `ui-card-inset-y` / `ui-card-inset` — and those three do
+  **not** share one value. Never invent a per-component inline-padding token where the Card already
+  owns the inset.
+
+**Component token names must match this exact shape** — `check:token-tiers` enforces it:
+
+```
+--{component}-{part}-{property}
+```
+
+where `{property}` is one of: `space color background foreground border radius height width padding
+gap size font line letter shadow glow tint gradient alpha align inset offset translate max overflow
+display`.
+
+`surface`, `bg`, `fg`, `spacing` are **not** accepted words. Control boxes come from the
+`--control-height` tier — never a literal height, never `calc(var(--control-height) ± …)`
+(`check:control-sizing`), never a Tailwind scale literal (`check:no-hardcoded-geometry` —
+even `min-w-0` fails).
+
+**Before handing over any doc or spec, run at minimum:**
+
+```
+pnpm check:doc-prop-existence   # a prop named in an example must exist on that component —
+                                # including a prop you only meant as an Ant Design illustration
+pnpm check:token-tiers && pnpm check:no-hardcoded-geometry && pnpm run audit
+```
+
+This section exists because it was violated: a comparison table in
+`badge-tag-chip-count.md` wrote an antd `Badge` + `count` example to illustrate _Ant's_ API and
+`check:doc-prop-existence` correctly read it as a claim about _ours_; and three specs named tokens
+`--…-surface` / `--…-bg`, which the shape above forbids. Both were caught by gates that already
+existed and simply had not been run.
+
+## 2. The ledger format — every audit produces exactly this table
+
+One row per antd capability. No prose findings.
+
+| Ant Design prop / behaviour | Status                                                                | Evidence                                     | Verdict                                                    |
+| --------------------------- | --------------------------------------------------------------------- | -------------------------------------------- | ---------------------------------------------------------- |
+| `<prop>` — one-line meaning | `PRESENT` / `RENAMED` / `COVERED-ELSEWHERE` / `MISSING` / `WONT-PORT` | `src/…:line`, or the grep that found nothing | for `MISSING`: the godx prop name to add, or "composition" |
+
+- `RENAMED` — present under the house spelling. Record both names; no work.
+- `COVERED-ELSEWHERE` — another primitive owns it. Name it. No work, but add a `related` cross-link
+  in the catalog **on both sides** (a one-sided claim is the mistake commit `8365bf05` fixed).
+- `WONT-PORT` — a deliberate refusal. State the reason in the catalog entry so nobody re-adds it.
+
+Close every audit with a **priority call**: `P0` (breaks a real screen), `P1` (a workaround exists
+but it is hand-rolled and a11y-risky), `P2` (nice to have).
+
+## 3. Findings so far
+
+### 3.1 Already specced — see the sibling documents
+
+| Area                               | Verdict                                                                                                      | Spec                      |
+| ---------------------------------- | ------------------------------------------------------------------------------------------------------------ | ------------------------- |
+| `Tree` / `TreeList` / `TreeSelect` | `TreeSelect` fine; `TreeList` is not a tree; **`Tree` missing entirely**                                     | `tree-components.md`      |
+| Badge / Tag / Chip / Pill / Count  | Count marker missing entirely; removable chip trapped inside `TagInput`; selectable chip already is `Toggle` | `badge-tag-chip-count.md` |
+| `List` (Ant `Listy`) / `Masonry`   | Both missing entirely — no virtualization and no column packing anywhere in `src/`                           | `list-masonry.md`         |
+| AI / chat surface                  | Nothing exists; 4 components + 6 compositions decided                                                        | `ai-chat-components.md`   |
+
+### 3.2 `Tabs`, `Steps`, `Segmented` — audited 2026-09-10
+
+These three are **already deliberately Ant-aligned** — the prop types cite antd by name. The
+remaining gaps are narrow, and none of them is P0.
+
+**`Tabs`** (`src/props/components/navigation.prop.ts:301`, `src/components/navigation/tabs.tsx`).
+Present: `items` (incl. `closable`/`closeIcon`/`icon`), `value`/`defaultValue`/`onValueChange`,
+`variant` (`line`/`card`/`editable-card`), `tabPlacement`, `centered`, `extra`
+(= antd `tabBarExtraContent`), `destroyOnHidden`, `onEdit`, `addIcon`, `hideAdd`. Overflow already
+scrolls and keeps the active tab visible (`src/components/navigation/tabs-scroll.ts`).
+
+| Gap                                                                                          | Priority | Verdict                                                                                       |
+| -------------------------------------------------------------------------------------------- | -------- | --------------------------------------------------------------------------------------------- |
+| `moreIcon` + an overflow **"more" dropdown** when the strip cannot scroll (narrow viewports) | **P1**   | Add. Scrolling alone hides tabs from a touch user with no affordance.                         |
+| `indicator: { size, align }`                                                                 | P2       | Add as tokens (`--tabs-indicator-*`), not props — it is a design knob (cardinal rule #44).    |
+| `tabBarGutter`                                                                               | P2       | Token, not a prop.                                                                            |
+| `animated`                                                                                   | P2       | `WONT-PORT` as a prop — motion is a system decision and must follow `prefers-reduced-motion`. |
+| `renderTabBar`                                                                               | P2       | `WONT-PORT` — an escape hatch that lets a consumer bypass the a11y contract.                  |
+| `size` lacks `xs`                                                                            | P2       | Add `xs` for the full `xs\|sm\|md\|lg` tier.                                                  |
+
+**`Steps`** (`src/props/components/navigation.prop.ts:201-240`).
+Present: `items` (`title`/`subtitle`/`description`/`icon`/`status`/`disabled`),
+`value`/`defaultValue`/`onValueChange`, `orientation`, `status`, `type`
+(`default`/`dot`/`inline`/`navigation` — `dot` **is** antd's deprecated `progressDot`), `percent`,
+`titlePlacement`, `separator`.
+
+| Gap                                                          | Priority | Verdict                                                                |
+| ------------------------------------------------------------ | -------- | ---------------------------------------------------------------------- |
+| `initial` — start the visible numbering at N                 | P2       | Add. Trivial, and real for resumed wizards.                            |
+| `responsive` — auto-switch to vertical on a narrow container | **P1**   | Add. Today a horizontal 5-step bar on a phone is the caller's problem. |
+| `size` is `md\|sm` only                                      | P2       | Extend to `xs\|sm\|md\|lg`.                                            |
+
+**`Segmented`** (`src/components/ui/segmented.tsx`). Built on react-aria-components' `RadioGroup`
+(Radix's, when this was audited) — the correct APG choice either way, and the comment explaining why
+it is not a `ToggleGroup` should be preserved verbatim.
+Present: `options` (`value`/`label`/`icon`/`disabled`), `value`/`defaultValue`/`onValueChange`,
+`block`, `vertical`, `size`, `disabled`, `name`.
+
+| Gap                                         | Priority | Verdict                                                                                                       |
+| ------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------- |
+| `shape: 'default' \| 'round'`               | P2       | Add as `shape` — the existing `ShapeProp` vocabulary already has `pill`; reuse it rather than antd's `round`. |
+| Option as a bare `string \| number`         | P2       | Add. Ant accepts it; it removes ceremony for the common case.                                                 |
+| Per-option `title` (a tooltip / hover hint) | P2       | `COVERED-ELSEWHERE` — wrap the option in `Tooltip`. Do not add a second tooltip API.                          |
+| `size` lacks `xs`                           | P2       | Add.                                                                                                          |
+
+**None of these three is the source of the "doesn't look like Ant Design" impression** — that is
+`TreeList`, the missing count badge, and the missing `List`/`Masonry`/`Tree`.
+
+## 4. How to run an audit (per component group)
+
+1. Read the group's catalog entries in `mcp/src/data/components.ts` and the prop types in
+   `src/props/components/<group>.prop.ts`.
+2. Fetch the matching Ant Design docs page for each. Where a component's _identity_ is unclear,
+   settle it at <https://namethatui.com/?platform=web> before writing anything.
+3. Produce the §2 ledger per component. Cite file:line.
+4. Publish a GATE-0 C1–C7 ledger for anything proposed as a **new** component.
+5. Do **not** write source in an audit pass. An audit is read-only; fixes are a separate wave with
+   their own spec, so the diff stays reviewable and two agents never edit one file at once.

package/docs/roadmap/badge-tag-chip-count.md

@@ -0,0 +1,172 @@
+# Badge / Tag / Chip / Pill / Count — audit + normalized spec
+
+> **Canonical taxonomy:** <https://namethatui.com/web/badge-chip-pill?part=badge-count>
+> **Capability reference:** Ant Design `Badge` + `Tag` (never their prop spellings where they
+> conflict with `docs/PROPS-VOCABULARY.md`).
+> **Contract:** `.claude/skills/godxjp-ui-component/SKILL.md` is the hard gate.
+
+## 1. The canonical taxonomy — five different things, routinely confused
+
+| Term | Canonical definition | Interactive? |
+| --- | --- | --- |
+| **Badge** | A tiny count or status marker **attached to another object**. Parts: the *badge anchor* (the icon/avatar it attaches to) and the *badge count* (the number in the bubble). | No |
+| **Tag** | Non-interactive **category metadata** on a card or row. | No |
+| **Pill** | A **shape**, not a component — a capsule-shaped status label. | No |
+| **Chip** | A compact **interactive token** that can be selected, edited or removed. Parts: a *remove button* (a real `<button>` with an `aria-label`) and a *selected state* (`aria-pressed`). | Yes |
+| **Label** | The text naming a form field (`<label for>`). | No |
+
+## 2. What the library actually has, mapped onto that taxonomy
+
+| Repo component | What it really is | Verdict |
+| --- | --- | --- |
+| `Badge` (`src/components/data-display/badge.tsx`) | A **Tag / Pill** — a standalone non-interactive chip with `variant` (structure), `tone` (meaning), `color` (data), `shape`, `status`→tone+icon+i18n. Nothing is attached to an anchor and there is no count. | **Misnamed, but keep the name** — see §5. Capability-wise it is *richer* than Ant's `Tag` (the `color` wash carries a real WCAG argument: 8.52:1 worst case across the sRGB cube). |
+| `Toggle` / `ToggleGroupItem` | The **selectable Chip** — `pressed`/`onPressedChange` (= `aria-pressed`) plus the `count`/`overflowCount`/`showZero`/`countLabel` counter-pill vocabulary. Its own catalog entry already says a faceted filter chip ("Open 42") and a reaction chip are this, and explicitly forbids nesting a `Badge` inside it. | **Already correct.** Do **not** build a second selectable chip. |
+| `TagInput` | The **chip field** — Ant-aligned (`tagRender`, `status`, `readOnly`, overflow, Backspace-removes-last). Its removable chips are **private markup** (`.ui-tag-input-chip` + a `<button aria-label>`). | Chip rendering is trapped inside it — see §4.2. |
+| `Label` | A real `<label>` on `react-aria-components`. | **Correct.** Not part of this family. |
+| `Button` | Also carries `count`/`overflowCount`/`showZero`/`countLabel`. | Source of the count vocabulary to reuse. |
+
+## 3. The gap — what Ant Design has and this library does not
+
+Verified: `count` / `overflowCount` appear **only** in `Button`, `Toggle`, `ToggleGroup` and their
+props. `Badge` has no `count` at all, and nothing anywhere renders a bubble attached to a child.
+
+| Ant Design | Missing here | Consequence today |
+| --- | --- | --- |
+| antd `Badge` with `count` wrapping an `Avatar` — the count bubble on an anchor | **Entirely** | No way to put an unread count on an avatar, a nav icon, a Topbar bell or a tab. `Sidebar`/`NavList` take a `badge` prop, but that renders the Tag-style pill *inline*, not an attached marker. |
+| antd `Badge` with `dot` — the bare dot marker | **Entirely** | No "there is something new" affordance. |
+| `overflowCount` → `99+` on a marker | **Entirely** | (The cap exists on `Button`/`Toggle`; it never reaches a marker.) |
+| `<Tag closable onClose>` — the removable chip | **Not public** | Only exists privately inside `TagInput`; a filter-summary row or a recipient list has to hand-roll a ✕ button, which is how `aria-label`-less removers get shipped. |
+| `<Badge.Ribbon>` | Entirely | Composition — see §4.4. |
+| `<CheckableTag>` | — | **Already covered by `Toggle`.** No action. |
+
+## 4. The fix — one new component, one extension, two documentation fixes
+
+This deliberately adds the **minimum**. Three of the five gaps close by extending what exists;
+building a `Chip` component would duplicate `Toggle` and is an instant reject.
+
+### 4.1 NEW — `CountBadge` (group: `data-display`)
+
+The attached count/status marker. Ant's `Badge`; NameThatUI's *badge* proper.
+
+**GATE 0 ledger**
+
+| # | Criterion | Verdict | Why |
+| --- | --- | --- | --- |
+| C1 | Universal | **PASS** | Unread counts on avatars, nav icons, bells, tabs, inbox rows — every app. |
+| C2 | Reusable behavior | **PASS** | Overflow capping, zero suppression, dot mode, anchor-relative placement that survives RTL, and folding the count into the anchor's accessible name / announcing changes politely. |
+| C3 | Not composable | **PASS** | Requires an absolutely-positioned marker measured against an arbitrary child plus a live-region contract. A `Badge` in a `<div className="relative">` is exactly the hand-rolled version this replaces. |
+| C4 | Single responsibility + vocabulary | **PASS** | One job; reuses the count vocabulary already defined by `Button`. |
+| C5 | Token-themeable | **PASS** | Size, offset, surface, ring are `--count-badge-*` tokens. |
+| C6 | Earns the i18n/a11y contract | **PASS** | `Intl.NumberFormat` for the number *and* the cap (vi renders `1.000+`), and the count must be announced, not merely drawn. |
+| C7 | Earns bundle cost | **PASS** | Used by nav chrome in every consumer. |
+
+**ALL PASS → framework component.**
+
+**API — reuse the EXISTING count vocabulary verbatim.** `Button` and `Toggle` already define
+`count` / `overflowCount` / `showZero` / `countLabel`. Do not invent a second spelling; a third
+dialect of the same idea is the defect this repo keeps fixing.
+
+| Ant Design | **godx `CountBadge`** |
+| --- | --- |
+| `count` | `count: number` |
+| `overflowCount` | `overflowCount: number` (default `99`) |
+| `showZero` | `showZero: boolean` (default `false`) |
+| `dot` | `dot: boolean` — a marker with no number |
+| `children` | `children` — the **anchor**; omit it for a standalone inline marker |
+| `status` + `text` | *dropped* — that is `Badge status=…`, which already exists |
+| `color` | `tone` (semantic) — the free-form data colour stays `Badge`'s job |
+| `offset` | *dropped* — placement is `placement` + tokens, never a caller-supplied pixel pair |
+| `size: 'default' \| 'small'` | `size: 'xs' \| 'sm' \| 'md' \| 'lg'` (never `"default"`) |
+| `title` | `countLabel` — same name `Button` uses |
+| — | `placement: 'start' \| 'end'` (logical; flips under RTL) |
+
+**Required semantics**
+- The number and the cap both go through `Intl.NumberFormat` on the active locale — never
+  `String(n)`, never a hand-rolled thousands separator. Above the cap render `{overflowCount}+`.
+- `count={0}` renders nothing unless `showZero`.
+- The marker is **not** an accessible name of its own floating next to the anchor: fold it into the
+  anchor's name via a visually-hidden text node (`t()`-driven, e.g. "Notifications, 5 unread"), or
+  expose `countLabel`. A bare "5" read out of context is a bug.
+- A changing count updates a single `aria-live="polite"` region — not one per marker.
+- `dot` mode still needs a text alternative; **never colour-or-shape-only** (WCAG 1.4.1).
+- Placement uses logical offsets (`inset-inline-end`), so it flips under `dir="rtl"`.
+- The marker must not clip: it overflows the anchor box deliberately, and the anchor keeps its own
+  hit area ≥24×24px (WCAG 2.5.8).
+
+**Tokens** — `src/tokens/components/count-badge.css`, `@import`ed from `src/tokens/base.css`,
+names passing `check:token-tiers`: `--count-badge-size`, `--count-badge-dot-size`,
+`--count-badge-inset-block`, `--count-badge-inset-inline`, `--count-badge-background`,
+`--count-badge-foreground`, `--count-badge-ring-color`, `--count-badge-ring-width`,
+`--count-badge-font-size`. No literal heights.
+
+**i18n** — `countBadge.unreadCount` (a CLDR `{one, other}` plural selected by `Intl.PluralRules`,
+in en/vi/ja), `countBadge.new` for `dot`.
+
+### 4.2 EXTEND — `Badge` gains `onRemove` (this *is* the removable Chip)
+
+Rather than a new `Chip` component that would collide with `Toggle`:
+
+- Add `onRemove?: () => void` and `removeLabel?: string` to `Badge`. When `onRemove` is present the
+  badge renders a trailing `<button type="button">` with a `t()`-driven `aria-label` naming the
+  item it removes ("Remove {tag}"), a ≥24×24px target, and `Backspace`/`Delete` support when the
+  badge itself is focused. `Badge` renders a `<div>`/`<span>`, so this is **not** a button-in-button.
+- Then **fix it upstream, not at the call site**: refactor `TagInput` to render its chips as
+  `Badge onRemove=…` instead of the private `.ui-tag-input-chip` markup, so there is exactly one
+  removable-chip implementation and one remover `aria-label` in the system. `TagInput`'s public API
+  and its existing tests must not change — prove it by running them.
+- Selection is **not** added to `Badge`. A selectable chip is `Toggle` (`pressed` + `count`), and
+  the catalog must keep saying so.
+
+### 4.3 DOCUMENT — the routing rules, so consumers stop guessing
+
+The real reason this family "doesn't look like Ant Design" is that the map is unwritten. Add to
+`mcp/src/data/components.ts`, on **both** sides of each pair (a one-sided claim is the mistake
+commit `8365bf05` fixed):
+
+- `Badge` tagline: state that in the canonical taxonomy this is the **Tag / Pill** — non-interactive
+  category or status metadata — and that a count marker attached to an anchor is `CountBadge`.
+- `Badge.related`: → `CountBadge` (counts on an anchor), `Toggle` (selectable chip),
+  `TagInput` (an editable set of chips), `Label` (naming a form field).
+- `CountBadge.related`: → `Badge`, `Toggle`, `Sidebar`/`NavList` `badge` props.
+- New rules: *DON'T hand-roll a `<span>` counter or an absolutely positioned `Badge` to mark an
+  anchor — use `CountBadge`.* *DON'T nest a `Badge` inside a `Toggle` for a count — `Toggle` owns
+  `count`.* *DON'T build a selectable chip out of `Badge` + `onClick` — use `Toggle`.*
+
+### 4.4 COMPOSITION — not framework components
+
+- **Ribbon** (Ant `Badge.Ribbon`): C2 and C3 fail — it is a `Card` plus an absolutely positioned
+  `Badge` plus a corner token. Ship it as a `docs/` showcase, never in `src/components/`.
+- **Status dot + text** (Ant `Badge status text`): already `Badge status=…`, which maps the key to
+  tone + icon + an i18n label. No new API.
+
+## 5. Explicitly NOT doing: renaming `Badge`
+
+`Badge` is used across the entire library and every consumer. Renaming it to `Tag` to satisfy the
+taxonomy would be a breaking change that buys nothing a catalog tagline cannot. **Keep the name;
+document the meaning.** No agent may rename, alias or deprecate `Badge` under this work.
+
+## 6. Definition of done
+
+1. `src/components/data-display/count-badge.tsx`, exported from that group's `index.ts`
+2. `CountBadgeProp` (+ `as CountBadgeProps`) in `src/props/components/data-display.prop.ts`,
+   **registered in `src/props/registry.ts`**; `Badge`'s `onRemove`/`removeLabel` added to its prop type
+3. `src/tokens/components/count-badge.css` + `@import` in `src/tokens/base.css`
+4. i18n keys in **all three** of `en.json`, `vi.json`, `ja.json`
+5. Tests in `src/components/data-display/__tests__/`: `count-badge.test.tsx` (Intl formatting in
+   en/vi/ja, cap → `99+`, `showZero`, `dot`, RTL placement, live-region announcement, accessible
+   name folding), `badge-remove.test.tsx` (remove button name, keyboard, ≥24px), and
+   `count-badge.a11y.test.tsx` at **0 axe violations**
+6. `mcp/src/data/components.ts`: a `CountBadge` entry, `Badge`'s new props, and the §4.3 routing
+   rules on both sides
+7. A real-screen docs page `docs/data-display/count-badge.tsx`
+8. `TagInput` refactored onto `Badge onRemove`, with its existing tests still green
+
+Gates, then only the touched test files:
+
+```
+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 test` and a bare `pnpm vitest run` are **forbidden** — the full suite is CI's job.

package/docs/roadmap/list-masonry.md

@@ -0,0 +1,159 @@
+# `List` (Ant `Listy`) + `Masonry` — normalized spec
+
+> **Capability reference:** <https://ant.design/components/listy> and
+> <https://ant.design/components/masonry>. **Canonical definition:**
+> <https://namethatui.com/web/masonry>.
+> **Contract:** `.claude/skills/godxjp-ui-component/SKILL.md`.
+
+Measured facts this spec rests on: the library has **no virtualization anywhere**
+(no `react-window` / `@tanstack/react-virtual` / any `virtual` code path in `src/`), and **no
+masonry** (every `grid-template-columns` in `src/styles/` is a fixed uniform grid; `ResponsiveGrid`
+is a uniform-row card grid). Both are genuine holes, not restyling jobs.
+
+---
+
+## 1. `List` — port of Ant Design `Listy` (group: `data-display`)
+
+Ant's old `List` is **deprecated** and `Listy` replaces it. Port `Listy`, not `List`: it is the
+narrower, performance-shaped component (virtual scrolling + grouping), which is exactly the part
+that cannot be composed here.
+
+### GATE 0 ledger
+
+| # | Criterion | Verdict | Why |
+| --- | --- | --- | --- |
+| C1 | Universal | **PASS** | Long feeds, activity streams, message lists, pickers, log views. |
+| C2 | Reusable behavior | **PASS** | Windowed rendering, measured row heights, sticky group headers, an imperative `scrollTo` that resolves an item key or a group key to an offset. |
+| C3 | Not composable | **PASS** | Nothing in the library virtualizes. `ScrollArea` + `.map()` renders every row. |
+| C4 | Single responsibility + vocabulary | **PASS** | One job; maps onto `items` / `getRowId` / `size`. |
+| C5 | Token-themeable | **PASS** | Row height, group-header surface, divider are `--list-*` tokens. |
+| C6 | Earns the contract | **PASS** | A virtual list is where `role`/`aria-setsize`/`aria-posinset` are *mandatory* — the DOM no longer contains the whole set. |
+| C7 | Earns bundle cost | **PASS** | Every consumer has at least one long list. |
+
+**ALL PASS → framework component.**
+
+### API — Ant `Listy` → godx `List`
+
+| Ant `Listy` | **godx `List`** | Note |
+| --- | --- | --- |
+| `items` | `items: T[]` | |
+| `itemRender(item, index)` | `itemRender(item, index)` | |
+| `rowKey` | **`getRowId: (item: T) => string`** | The house spelling — `DataTable` already uses `getRowId`. Do not introduce `rowKey` as a second dialect. |
+| `height` | `height?: number` | Scroll container height; content scrolls past it. |
+| `virtual` | `virtual?: boolean` (default `false`) | |
+| `group: { key, title }` | `group?: { key: (item) => K; title: (key, items) => ReactNode }` | |
+| `sticky` | `sticky?: boolean` (default `false`) | Group headers stick. |
+| `onScroll` | `onScroll?: React.UIEventHandler<HTMLElement>` | |
+| `classNames` / `styles` | `classNames?: { root?; item?; groupHeader? }` | Keep the semantic-slot shape; skip the `styles` twin (inline style is not how this system themes). |
+| ref `scrollTo(config)` | ref `scrollTo(config)` | Accepts a pixel offset, `{ top }`, `{ key, align?, offset? }`, or `{ groupKey, align?, offset? }`. |
+| — | `size: 'xs' \| 'sm' \| 'md' \| 'lg'` | House requirement. |
+| — | `loading?: boolean`, `empty?: ReactNode` | Compose the real `Skeleton` / `EmptyState`; do not hand-roll either. |
+
+**Deliberately NOT ported** (and say so in the catalog entry, so nobody re-adds them): `bordered`,
+`split`, `header`, `footer`, `size: 'large'`, `pagination`, `loadMore`, `itemLayout`. `Listy`
+dropped them, and here they are already covered — the frame is `Card` + `CardContent flush`,
+dividers are `Separator`, paging is `Pagination`. Re-adding them would rebuild a second `Card`.
+
+### Required semantics
+- `role="list"` with `role="listitem"` rows; when `virtual`, every row **must** carry `aria-setsize`
+  (the full count) and `aria-posinset` — otherwise a screen reader reports the window, not the list.
+  This is the single most-skipped part of a virtual list and it is not optional.
+- Grouping renders `role="group"` with the header as its `aria-label`/`aria-labelledby`.
+- Keyboard: the scroll container is focusable; `PageUp`/`PageDown`/`Home`/`End` work. Rows are not
+  a roving-tabindex widget — interactive controls inside a row keep normal tab order.
+- `sticky` headers use `position: sticky` with logical insets and must not cover the focused row
+  (`scroll-margin-block-start`).
+- Row heights are measured, not assumed; a row whose content grows must not desynchronise the
+  window. Reserve image dimensions.
+- `prefers-reduced-motion: reduce` disables any smooth-scroll in `scrollTo`.
+
+### Tokens
+`src/tokens/components/list.css` (`@import` from `src/tokens/base.css`): `--list-row-min-height`
+(from the `--control-height` tier), `--list-divider-color`,
+`--list-group-header-background`, `--list-group-header-foreground`, `--list-group-header-height`.
+
+### Spacing — the list does NOT own its inline inset
+
+Read `docs/SPACING.md` before writing a single spacing declaration. A row inside a
+`Card` + `CardContent flush` takes its inline inset from the public class **`ui-card-inset-x`**
+(which reads `--card-space-inset`), so the row lines up with the card shell and follows the card's
+`density`. **Do not invent a `--list-row-padding-inline`** — a parallel spacing knob drifts away
+from the Card that contains it, and the block axis is owned by `--list-row-min-height`.
+
+Macro rhythm is never the component's: no Tailwind `p-*` / `m-*` / `gap-*` (the audit rejects them
+as `no-utility-spacing`), no hand-rolled `flex`/`grid` (`no-utility-layout`). Vertical rhythm comes
+from `Flex gap` on the φ scale (`xs`/`sm` = 4px grid, `md` = φ⁰, `lg` = φ¹, `xl` = φ²) — this repo
+does **not** use the 8pt grid.
+
+### i18n
+`list.empty`, `list.loading`, `list.group` (group-header accessible name), and any count through
+`Intl.NumberFormat` + `Intl.PluralRules`.
+
+---
+
+## 2. `Masonry` (group: `layout`)
+
+**Canonical definition** (NameThatUI): *a layout where each new item joins the shortest column,
+creating a staggered bottom edge with no row lines and cards keeping their individual heights.*
+The named part is the **packed column** — each column flows straight down, nothing lines up
+sideways. Aliases: Pinterest grid, waterfall, brick layout.
+
+### GATE 0 ledger
+
+| # | Criterion | Verdict | Why |
+| --- | --- | --- | --- |
+| C1 | Universal | **PASS** | Media galleries, card boards, dashboards with variable-height cards. |
+| C2 | Reusable behavior | **PASS** | Shortest-column packing, re-packing on resize/content change (`ResizeObserver`), and keeping DOM reading order row-major while the visual flow is column-major. Native `grid-template-rows: masonry` covers the paint but not the ordering or the fallback. |
+| C3 | Not composable | **PASS** | `ResponsiveGrid` is a uniform grid; nothing packs by column height. |
+| C4 | Single responsibility + vocabulary | **PASS** | One job; `columns`/`gap` reuse `ResponsiveGrid`'s exact spellings. |
+| C5 | Token-themeable | **PASS** | Gaps come from the spacing scale. |
+| C6 | Earns the contract | **PASS** | Reading order vs visual order is an accessibility decision, not a style one. |
+| C7 | Earns bundle cost | **PASS** | Small; broadly useful. |
+
+**ALL PASS → framework component.**
+
+### API — Ant `Masonry` → godx `Masonry`
+
+| Ant Design | **godx `Masonry`** | Note |
+| --- | --- | --- |
+| `columns: number \| { xs, sm, md }` | `columns: number \| { base?, sm?, md?, lg? }` (default `3`) | **Use `ResponsiveGrid`'s existing breakpoint shape** (`base/sm/md/lg`), not antd's `xs/…/xxl`. One breakpoint dialect in this library. |
+| `gutter: Gap \| [Gap, Gap]` | `gap: 'none' \| 'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl'` (default `'md'`) | Token scale, exactly as `ResponsiveGrid`. A caller-supplied pixel pair is not how this system spaces. |
+| `items: MasonryItem[]` | `items: MasonryItemProp[]` — `{ key, children?, data?, column? }` | Drop antd's `height`: heights are measured, never declared. |
+| `itemRender(item)` | `itemRender(item, index)` | `item.children` still wins. |
+| `fresh` | `observeItems?: boolean` (default `true`) | Keep watching child sizes via `ResizeObserver`; the antd name says nothing. |
+| `onLayoutChange` | `onLayoutChange?: (placements: { key: Key; column: number }[]) => void` | |
+| `classNames` / `styles` | `classNames?: { root?; item? }` | Skip the `styles` twin. |
+| — | `sequential?: boolean` | Fill columns left-to-right in order instead of shortest-first, for a strict reading order. |
+
+### Required semantics
+- **Reading order is DOM order.** Whatever the visual packing, the DOM stays in `items` order so
+  keyboard and screen-reader traversal match the source sequence. This is the reason the CSS
+  `columns` fallback alone is not acceptable — it flows column-major.
+- Prefer native `@supports (grid-template-rows: masonry)`; fall back to measured absolute/transform
+  packing. Never ship the bare `columns:` fallback as the only path.
+- The container is a plain grouping element with no invented role. If the content is a list, the
+  **caller** supplies the semantics; `Masonry` must not silently impose `role="list"`.
+- Re-pack on container resize and on item resize (`ResizeObserver`), debounced to a frame.
+- Reserve media dimensions (`AspectRatio`) so image loads do not cause layout shift — call this out
+  in the docs page.
+- Logical CSS only; column order flips under `dir="rtl"`.
+
+### Tokens
+`src/tokens/components/masonry.css`: `--masonry-gap-inline`, `--masonry-gap-block`,
+`--masonry-column-min-inline-size`.
+
+---
+
+## 3. Definition of done (both)
+
+Per component: source + group `index.ts` export · `XProp` (+ `as XProps`) in the group's
+`*.prop.ts` **and `src/props/registry.ts`** · tokens file + `@import` in `src/tokens/base.css` ·
+i18n keys in **en/vi/ja** · `@testing-library/user-event` behaviour tests + a `*.a11y.test.tsx` at
+**0 axe violations** · an `mcp/src/data/components.ts` entry (including the "deliberately not
+ported" list for `List`) · a real-screen docs page.
+
+For `List`, the virtual-mode test must assert `aria-setsize`/`aria-posinset` reflect the **full**
+item count while only a window is in the DOM. For `Masonry`, a test must assert DOM order equals
+`items` order under every `columns` value.
+
+Gates, then only the touched test files. `pnpm test` and a bare `pnpm vitest run` are **forbidden**.