@godxjp/ui 19.4.1 → 19.5.0

package/docs/DESIGN-AUTHORITY.md

@@ -0,0 +1,346 @@
+# Design authority — which external standard owns which decision
+
+**Status:** accepted · 2026-09-07
+
+## Why this document exists
+
+Every design question that has no external answer gets answered by us, in a meeting, again.
+That is the expensive part — not the code. This file names, per layer, the outside system we
+defer to, so the next question is a lookup instead of an invention.
+
+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`                            |
+| Colour foundation                                                  | **SmartHR**                                   | already the palette source — `--primary` = SmartHR MAIN `#0071bd`, `--foreground` = TEXT_BLACK, `--border` = BORDER               |
+| **Derived colour — every step computed from a seed**                | **Ant Design (the algorithm itself)**         | **NEW — this decision.** antd is no longer a shape reference here: `scripts/gen-antd-tokens.mjs` runs `theme.getDesignToken()` at build time and emits the derived map |
+| **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,
+when to reach for which container. That gap is why `PageContainer` presets, `MasterDetail`,
+`CenteredShell` and the `AuthShell` variants were each designed from scratch.
+
+## Why Carbon for that layer
+
+**It is the closest fit to what this library is for.** Internal SaaS, dense, neutral, legible —
+that is Carbon's design brief almost verbatim. Its visual language is deliberately plain, so it
+does not fight the SmartHR colour foundation already in `foundation.css`.
+
+**It is the cheapest to adopt, measurably.** The spacing scale here already matches Carbon's on
+8 of 9 steps:
+
+| `@godxjp/ui` | px     | Carbon                                   |
+| ------------ | ------ | ---------------------------------------- |
+| `--space-1`  | 4      | `spacing-02`                             |
+| `--space-2`  | 8      | `spacing-03`                             |
+| `--space-3`  | 12     | `spacing-04`                             |
+| `--space-4`  | 16     | `spacing-05`                             |
+| `--space-5`  | **20** | **no equivalent — Carbon steps 16 → 24** |
+| `--space-6`  | 24     | `spacing-06`                             |
+| `--space-8`  | 32     | `spacing-07`                             |
+| `--space-10` | 40     | `spacing-08`                             |
+| `--space-12` | 48     | `spacing-09`                             |
+
+Body size agrees too: Carbon's `body-compact-01` is 14px, and `--font-size-base` is 14px.
+
+**It is the most actively maintained of the candidates**, which matters when the point is to follow
+someone rather than lead. Measured 2026-09-07 from the GitHub API:
+
+| System                | Last commit | Commits, 90 days |
+| --------------------- | ----------- | ---------------- |
+| Carbon (IBM)          | 2026-09-04  | **418**          |
+| Fluent UI (Microsoft) | 2026-09-06  | 220              |
+| Polaris (Shopify)     | 2026-08-05  | —                |
+| SLDS (Salesforce)     | 2026-06-02  | **0**            |
+| Primer (GitHub)       | 2025-07-01  | 0                |
+
+## Why not the others
+
+**Salesforce Lightning** was the first instinct and is a reasonable one — it is the archetypal
+enterprise system. Two things rule it out. Its public repo has not moved since June 2026 (SLDS 2
+lives in separate `salesforce-ux/design-system-2` repos on a much slower cadence), and the part of
+SLDS with the most value is bound to Salesforce's own object model — record home, related lists,
+object pages — which does not transfer to a product that is not Salesforce.
+
+**Fluent UI** is complete (54 component packages) and extremely well maintained. It loses on fit,
+not quality: its guidance is written for Microsoft product surfaces and its visual language carries
+more Windows/Office flavour than a white-label framework wants.
+
+**Apple HIG** is platform guidance for macOS/iOS. It has close to nothing to say about a dense web
+admin table.
+
+**Polaris** has the best content-design guidance of the group, worth borrowing from for microcopy,
+but its patterns assume the Shopify admin.
+
+**Atlassian** is a genuine alternative to Carbon and would also work. Carbon wins on being more
+visually neutral and on the spacing scale already matching.
+
+## The Japanese market comes first, and it outranks Carbon
+
+The customers are Japanese businesses. Where a Western system and a Japanese one disagree, **the
+Japanese one wins for anything the user reads or touches** — typography, line rhythm, density,
+form conventions, wording. Carbon keeps geometry (the spacing steps, the 4px grid) because that
+layer is culture-neutral.
+
+**SmartHR is the JP authority, not just the palette.** It is a Japanese HR SaaS — the same product
+shape as ours, aimed at the same buyers — its library is open source, and it is the most actively
+maintained system of any measured here: **561 commits in 90 days**, last commit 2026-09-07 (Carbon:
+418). It was already the colour source; this decision extends it to how a JP business screen
+behaves.
+
+**デジタル庁 (Digital Agency) is the standards reference.** Its design system is the closest thing
+Japan has to a public, government-backed baseline, and it is what a JP enterprise customer or
+procurement reviewer will cite. Use it to answer "which standard does this meet" (JIS X 8341-3),
+not for visual style.
+
+### Japanese conventions this library already follows — now written down
+
+These were correct decisions with no recorded reason. They are load-bearing; do not "simplify"
+them toward a Latin default:
+
+- **`--line-height-body: 1.7`.** Japanese body text needs 1.7–2.0, not the Latin 1.5. Full-width
+  kana and kanji fill the em box, so the same 1.5 that reads as airy in English reads as cramped in
+  Japanese. `--line-height-normal: 1.5` remains for Latin-only runs.
+- **14px body.** The JP business-software norm, and it happens to agree with Carbon's
+  `body-compact-01`. Do not raise it to a Western 16px default.
+- **A per-language font slot, not one merged stack.** `--font-sans-base` is deliberately a pure
+  system stack so the library renders with zero font setup; Japanese arrives through
+  `--font-sans-ja`, which `styles/base.css` wires to `[lang="ja"]`. Keep the indirection — merging
+  a JP face into the base stack looks like a simplification and quietly removes the hook a consumer
+  themes through.
+- **Density never touches type size.** `density.css` sets `--scaling` only; `font-size` appears
+  **zero** times in it. This is the single most important rule for dense JP screens: Japanese loses
+  legibility far faster than Latin when shrunk, because the strokes-per-em of a kanji do not
+  survive it. Compress spacing to fit more on screen — never the characters.
+
+## Compact without becoming ugly — the rules that hold both
+
+"Fit more on one screen" and "still looks composed" are not in tension if the compression is
+applied to the right axis:
+
+1. **Compress spacing, never type.** See above. `--scaling` is the only density knob.
+2. **Keep the ratio, shrink the unit.** The φ macro rhythm (`docs/SPACING.md`) stays intact under
+   density because `--phi-unit` is itself a spacing token — the proportions between sections are
+   preserved while the absolute gaps shrink. That is why density does not make the page look
+   broken, only tighter.
+3. **Density is a token axis, not a per-screen decision.** `data-density` on the root, three values.
+   A screen that wants to be denser than `compact` is a screen with too much on it.
+4. **The information ceiling is the row, not the page.** Dense JP admin screens get their density
+   from row height and column count (`--table-cell-padding-y`, `--band-height-*`), not from
+   squeezing the page gutter. Take row heights from SmartHR's tables.
+5. **Touch targets do not participate in density.** See divergence 5 — this is currently violated.
+
+## What this does NOT mean
+
+**We do not adopt Carbon's components.** There are 127 catalogued components here with 3,480 tests
+and a token contract that took #316/#319 to land. Swapping libraries would throw that away to buy
+guidance we can simply read. Carbon is the **specification authority**, not a dependency.
+
+**We do not adopt Carbon's colours or brand.** Colour stays SmartHR-anchored. Carbon owns
+geometry and rhythm; SmartHR owns hue.
+
+## The open divergences
+
+Recorded rather than silently fixed, because each is a real decision:
+
+1. **`--space-5` (20px) has no Carbon equivalent.** Carbon steps 16 → 24 on purpose: a scale with
+   both 20 and 24 lets two authors space the same relationship differently. Either retire it or
+   write down what it is for. Pinned by `src/tokens/__tests__/carbon-scale-alignment.test.ts`, which
+   fails if a NEW off-scale step appears.
+2. **The type scale diverges by construction.** Carbon uses integers — 12, 14, 16, 18, 20, 24, 28,
+   32, 36 — while `--font-size-ratio: 1.1227` (φ^¼) produces 11.1, 12.5, 17.6, 19.8, 22.2. Only the
+   14px body agrees. Fractional sizes do cost something measurable — they snap a line box half a
+   pixel either way, which is ±0.5px of the residual in gh#370 — but they are not what that issue
+   is. gh#370 is that `place-items: center` centres a LINE BOX and a line box is not a letterform;
+   re-measured from the painted ink, the glyph classes' optical centres lie 0.21em apart (`g` 3.69px
+   low in the 28px `md` box where `神`, `G` and `GX` are within 0.94px), so no glyph-blind rule
+   centres them all — the best glyph-blind rule, `text-box: trim-both ex alphabetic`, still leaves
+   2.25px. So the correction moved up a layer: `Logo` classifies the glyph string it is handed into
+   the ink band it occupies and CSS applies that band's offset, which measures 1.38px worst case and
+   needs no `text-box` at all (`src/styles/logo-layout.css` carries the full matrix). Aligning the
+   scale is a visual change to every screen, so it is a separate decision, not a side effect of this
+   one.
+3. **The large end is missing.** Carbon has 64/80/96/160px; this scale stops at 48px. Nothing needs
+   them yet — add from Carbon's steps when something does, rather than inventing a number.
+4. **2px (`spacing-01`) is missing.** Same rule: take Carbon's value if a hairline gap is ever
+   needed.
+5. **`--scaling` takes the whole scale off the 4px grid, and undercuts the 44px touch floor.**
+   `density="compact"` sets `--scaling: 0.92`, so every step becomes fractional — 16px → 14.72px,
+   24px → 22.08px — and the grid Carbon's scale is built on only holds at default density. Worse,
+   the coarse-pointer override in `tokens/components/control.css` raises controls to
+   `--band-height-xl` (44px, "rule #24"), but `--control-height` multiplies it by `--scaling`
+   anyway: **44 × 0.92 = 40.48px on a touch device at compact density.** That still clears WCAG 2.2
+   AA (24px), but it breaks this library's own rule #24. Carbon's answer to density is discrete
+   size variants that stay on the grid, not a continuous multiplier — worth reconsidering. Verify
+   on a real touch device before changing anything.
+6. **Type scale vs Japanese rendering.** Divergence 2 is sharper for JP than for Latin: fractional
+   sizes (12.5px, 17.6px, 19.8px) put full-width glyphs on half-pixel boundaries, where kanji
+   strokes blur far more visibly than Latin letterforms. Another reason to prefer Carbon's integer
+   steps if the scale is ever revisited.
+
+## Derived colour is GENERATED, not authored
+
+**The problem this fixes.** The library hand-authored roughly a thousand tokens and reasoned about
+each one. A hover step was chosen by eye, an active step was chosen by eye, a focus-halo alpha was
+chosen by eye and then justified in a paragraph. Every one of those is a decision with no outside
+authority behind it, and every one has to be re-argued the next time somebody looks at it.
+
+**Ant Design already solves this exactly once**: a SEED colour goes in, an ALGORITHM runs, and the
+whole derived map falls out. This document already named antd as the authority for component
+taxonomy and focus shape; that is now extended to make antd the **generator** of derived colour.
+
+`scripts/gen-antd-tokens.mjs` reads the seeds out of `src/tokens/foundation.css`, runs antd 6.6.2's
+own `theme.getDesignToken()` (`defaultAlgorithm` for light, `darkAlgorithm` for dark) and writes
+`src/tokens/antd.generated.css`. `pnpm check:antd-tokens` fails CI if that file drifts from the
+algorithm. **antd is a devDependency and a build-time tool only** — `pnpm check:no-antd-runtime`
+asserts it never reaches `dependencies`, `src/`, or `dist/`.
+
+**What is authored:** five brand colours per theme (SmartHR MAIN plus four 和色, and the lifted dark
+ramp). **What is computed:** `--primary-hover`, `--primary-active`, `--primary-border`,
+`--destructive-hover`, `--destructive-active`, `--control-outline*` and `--ring`.
+
+**What is deliberately NOT taken from antd, and why — each a measurement, not a preference:**
+
+- **The neutral spine.** Colour foundation stays SmartHR's (see the table above); the neutrals are
+  not derived from the brand seed. `colorBorder` is also the only role antd offers for a control
+  boundary and it measures **1.43:1** on the page, where `--input` is held to 3:1 by SC 1.4.11 and
+  by `input-boundary-contrast.test.ts`.
+- **The text ramp.** antd's is alpha-based (`rgba(0,0,0,0.88)`), which cannot enter this library's
+  opaque `H S% L%` triple without choosing a surface to composite against — lossy by construction.
+- **The dark `--primary` itself.** `darkAlgorithm` MOVES the seed (antd's own `#1677ff` becomes
+  `#1668dc`). Feeding this library's light seed in gives `#0363a4` at **2.81:1** on the dark spine,
+  which `primary-text-contrast.test.ts` rejects outright; antd's transform of the committed dark
+  seed gives `#3794d3` at 5.36:1 where the seed itself measures 7.07:1. The dark theme therefore
+  keeps its seed and everything derived from it is antd's. This is the one structural divergence,
+  recorded in `DIVERGENCES` in the generator.
+
+**Geometry antd owns was already correct.** `lineWidth` 1, `controlOutlineWidth` 2,
+`lineWidthFocus` 3, `borderRadius` 6, `controlHeight` 32 and `fontSize` 14 all match the named
+scales this library already ships (`--stroke-*`, `--radius`, `--band-height-md`,
+`--font-size-base`). The generator asserts that agreement rather than emitting a second copy, so
+the two cannot drift apart silently.
+
+## Focus appearance — Ant Design owns the shape, and the indicator SHIPS OFF
+
+### The two forms, read from antd's source
+
+**SmartHR** (`smarthr-ui@99.6.0`) draws focus as an opaque ring held off the control by a white
+spacer. **Ant Design** (`antd@6.6.2`) has two forms instead:
+
+- **Field** — `borderColor: colorPrimary` at the unchanged `lineWidth`, plus
+  `boxShadow: 0 0 0 ${controlOutlineWidth}px ${controlOutline}`
+  (`es/input/style/token.js:48-50`). `es/select/style/select-input.js:32` emits the same
+  declarations, which is why an antd Select focuses exactly like an antd Input.
+- **Non-field** — `genFocusOutline` (`es/style/index.js:60-64`):
+  `outline: ${lineWidthFocus}px solid ${colorPrimaryBorder}; outline-offset: 1`.
+
+**v5 → v6 changed none of this.** Both majors were unpacked and their own `formatToken` run side by
+side; every value is identical to the digit in `antd@5.29.3`.
+
+**Ant Design wins the shape.** The library shipped an opaque brand ring drawn immediately outside an
+untouched grey border — two outlines of different colours claiming the same edge — and a Select that
+could not be told to agree with an Input. antd's rule resolves both. SmartHR still owns the hue: the
+focus colour is `--ring`, which the generated tier declares as `var(--primary)` because antd has no
+separate focus-colour token at all.
+
+### The indicator ships OFF. That forfeits WCAG 2.4.7 and a JIS X 8341-3 AA claim.
+
+`--focus-outline: 0` in `foundation.css`. Nothing paints a focus indicator by default.
+
+**This is a product decision, made with the cost stated.** The indicator was reported as intrusive —
+a thick blue outline appearing on shift-tab, stacked on an already-shaded selected nav row. The
+owner chose to ship it off and let whoever needs it turn it on. What that costs, plainly:
+
+- **WCAG 2.2 SC 2.4.7 Focus Visible is an AA criterion**, and with the switch off it is not met.
+- **JIS X 8341-3:2016 tracks WCAG 2.0 AA**, so a Japanese enterprise procurement asking for that
+  conformance statement cannot be answered while the switch is off. Japanese public-sector and
+  large-enterprise buyers ask for it routinely, and デジタル庁 is this document's standards
+  reference for exactly that reason.
+
+**Turning it back on is one attribute, on the root element, with no code change:**
+
+```html
+<html data-focus-outline="on">
+```
+
+**The switch is antd's own mechanism, not one invented here.** antd 6.6.2 carries a `focusOutline`
+seed flag (`es/theme/themes/seed.js:67`) and consumes it in `es/theme/util/alias.js:71`:
+
+```js
+lineWidthFocus: mergedToken.focusOutline === false ? 0 : mergedToken.lineWidth * 3
+```
+
+The flag zeroes the focus line width. `--focus-outline` is that flag in CSS: every painted length
+multiplies by it, so no component rebind can bring the mark back while it is `0`. The two paints
+that are not lengths — the halo and a field's recoloured boundary — are scoped to the same attribute
+in `styles/focus-ring.css`. **Every `:focus-visible` selector stays exactly where it is**; only the
+painted result disappears.
+
+### The ON state is the LIGHT one
+
+The complaint was weight, not existence, so the on-position is not the old mark restored. It paints
+antd's **field** indicator on every control — one `lineWidth` (1px) in the focus hue, plus antd's
+`controlOutline` halo — rather than antd's 3px `genFocusOutline`. Measured, in Chromium, on
+`ql.test` after the transition settles:
+
+| control | switch off | switch on |
+| --- | --- | --- |
+| Input / Select trigger | border `1px rgb(144,135,127)`, resting shadow intact | border `1px rgb(0,113,189)` + `rgba(0,182,228,0.11) 0 0 0 2px` |
+| Button (primary) | outline `0px`, resting shadow intact | `outline: 1px solid rgb(0,113,189)` @ `0px` + same halo |
+| Sidebar nav row / list row | outline `0px` | `outline: 1px solid rgb(0,113,189)` @ **`-1px`** (inset into the row) |
+
+The field pair is **byte-identical to antd's own `activeBorderColor` + `activeShadow`** for this
+seed. The nav row insets its mark into its own shape rather than wrapping an already-shaded surface,
+which is the specific stacking that read as heavy.
+
+**No control's box moves when it is focused**, measured with `getBoundingClientRect()` before and
+after: the field form only recolours a border and an `outline` is painted outside the box model.
+Input, Save and Delete all stay at 32.00px.
+
+**Two criteria, and only one is met by thickness alone.** SC 1.4.11 (AA, non-text contrast) is about
+COLOUR — the 1px mark measures 5.05:1 light and 7.07:1 dark on every surface a control sits on, so
+the light weight costs nothing there. antd's own `colorPrimaryBorder` (#6dc0e3) measures **2.00:1
+light / 1.66:1 dark** and could not have satisfied it at any thickness, which is why the on-state
+takes the focus hue instead — the single place it departs from `genFocusOutline`. SC 2.4.13 Focus
+Appearance (AAA) additionally wants a 2px perimeter; the on-state does not target it, and
+`--focus-outline-weight: var(--stroke-lg)` restores antd's 3px if a customer needs the area clause.
+
+Both positions of the switch are gated in `src/tokens/__tests__/focus-ring-contrast.test.ts`: with
+it off nothing paints and no rebind can route around it, with it on the geometry and the ≥3:1
+contrast hold on every surface. Per rule 4 below: a standard that is not enforced is a standard that
+has already drifted.
+
+### The indicator is for CONTROLS, not containers
+
+Buttons, fields, links, nav and menu rows carry it. A div, a content region, a scroll wrapper and
+`body` do not. `.ui-legal-document-section` was removed from the list: it is a slab of prose that
+carries `tabIndex={-1}` only so a table-of-contents link can move focus into it, so it is never in
+the tab order and a keyboard user cannot arrive there unannounced. Its `tabIndex={-1}` stays,
+because removing it would break the contents anchor.
+
+**Every other focusable non-interactive element in this library is a genuinely scrollable region**
+— `.app-main`, `.ui-mobile-shell-main`, `.ui-timeline-grid`, `.ui-code-block` when it overflows,
+MasterDetail's bounded master, the DataTable and Table scroll containers, ScrollArea, and the
+BranchScopePicker list. Each carries `tabIndex={0}` for axe `scrollable-region-focusable` and must
+stay reachable, so each keeps BOTH halves rather than becoming focusable-but-unpainted. The region
+ring (`--region-focus-ring-width`, off by default) now also multiplies by `--focus-outline`, so a
+service that opts it in still cannot paint while the library-wide switch is off.
+
+## How a decision gets made from here
+
+1. Look it up in Carbon's guidance for the layer in question.
+2. If Carbon has an answer, take it, and cite it in the token or component comment.
+3. If Carbon has no answer, decide — and add the reason here, so it is looked up next time
+   instead of re-decided.
+4. Encode the decision as a gate wherever a gate can hold it. A standard that is not enforced is a
+   standard that has already drifted; `visual-audit-rules.test.ts` and the scale test above are the
+   pattern to follow.

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: **126**
-- With ≥1 frame: **126** · zero-frame: **0**
+- Public components: **129**
+- With ≥1 frame: **129** · zero-frame: **0**
 - Fully covered (every contract axis declared): **0**
 
 ## Per-component contract axes
@@ -22,6 +22,8 @@ Legend: ✓ covered · N/A reasoned skip · · UNTESTED (blank cell = UNTESTED).
 | MobileShell | ✓ | N/A | N/A | N/A | · | · | · | · | · | · |
 | Sidebar | ✓ | N/A | N/A | N/A | · | · | · | · | · | · |
 | Topbar | ✓ | N/A | N/A | N/A | · | · | · | · | · | · |
+| TopbarItem | ✓ | N/A | N/A | N/A | · | · | · | · | · | · |
+| NavList | ✓ | N/A | N/A | N/A | · | · | · | · | · | · |
 | MasterDetail | ✓ | N/A | N/A | N/A | · | · | · | · | · | · |
 | SplitPane | ✓ | N/A | N/A | N/A | · | · | · | · | · | · |
 | ErrorSurface | ✓ | ✓ | N/A | N/A | · | · | · | · | · | · |
@@ -113,6 +115,7 @@ Legend: ✓ covered · N/A reasoned skip · · UNTESTED (blank cell = UNTESTED).
 | PasswordStrength | ✓ | N/A | N/A | · | · | · | · | · | · | · |
 | InputOTP | ✓ | N/A | · | N/A | · | · | · | · | · | · |
 | Rating | ✓ | N/A | · | · | · | · | · | · | · | · |
+| Segmented | ✓ | N/A | · | · | · | · | · | · | · | · |
 | TagInput | ✓ | N/A | · | · | · | · | · | · | · | · |
 | ContextMenu | ✓ | N/A | N/A | · | · | · | · | · | · | · |
 | Menubar | ✓ | N/A | N/A | · | · | · | · | · | · | · |

package/docs/README.md

@@ -1,18 +1,19 @@
 # @godxjp/ui Documentation
 
-| Doc                                          | Purpose                                                                                                                                      |
-| -------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
-| [CONSUMER-RULES.md](./CONSUMER-RULES.md)     | **Start here if you build an app with @godxjp/ui** — the ten rules the audit enforces (styles entry, layout owners, real primitives, tokens) |
-| [DEVELOPMENT.md](./DEVELOPMENT.md)           | **Contributor guideline** — role/boundary, architecture, how to add/extend, verify                                                           |
-| [COMPONENTS.md](./COMPONENTS.md)             | Component catalog by Ant Design group                                                                                                        |
-| [PROPS-VOCABULARY.md](./PROPS-VOCABULARY.md) | Atomic prop types (`*Prop` suffix)                                                                                                           |
-| [PROPS-REGISTRY.md](./PROPS-REGISTRY.md)     | Machine-readable registry + forbidden aliases                                                                                                |
-| [DATETIME.md](./DATETIME.md)                 | **Mandatory** `formatDate` — all date/time display                                                                                           |
-| [SPACING.md](./SPACING.md)                   | Golden ratio (φ) macro spacing — PageContainer sections, Flex gap, Card rhythm                                                               |
-| [FORMS.md](./FORMS.md)                       | **Mandatory** react-hook-form + Zod 4                                                                                                        |
-| [TESTING.md](./TESTING.md)                   | **Mandatory** Vitest per component                                                                                                           |
-| [FRAME-A11Y-CI.md](./FRAME-A11Y-CI.md)       | Per-frame axe a11y + geometry + coverage CI gates — how to run/regenerate locally                                                            |
-| [../README.md](../README.md)                 | Setup, workspace wiring, theme                                                                                                               |
+| Doc                                          | Purpose                                                                                                                                                                         |
+| -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [CONSUMER-RULES.md](./CONSUMER-RULES.md)     | **Start here if you build an app with @godxjp/ui** — the ten rules the audit enforces (styles entry, layout owners, real primitives, tokens)                                    |
+| [DEVELOPMENT.md](./DEVELOPMENT.md)           | **Contributor guideline** — role/boundary, architecture, how to add/extend, verify                                                                                              |
+| [COMPONENTS.md](./COMPONENTS.md)             | Component catalog by Ant Design group                                                                                                                                           |
+| [PROPS-VOCABULARY.md](./PROPS-VOCABULARY.md) | Atomic prop types (`*Prop` suffix)                                                                                                                                              |
+| [PROPS-REGISTRY.md](./PROPS-REGISTRY.md)     | Machine-readable registry + forbidden aliases                                                                                                                                   |
+| [DATETIME.md](./DATETIME.md)                 | **Mandatory** `formatDate` — all date/time display                                                                                                                              |
+| [DESIGN-AUTHORITY.md](./DESIGN-AUTHORITY.md) | **Which external standard owns which decision** — APG, Radix, shadcn, Ant Design groups, SmartHR colour, Carbon geometry. Read before inventing a spacing/density/layout answer |
+| [SPACING.md](./SPACING.md)                   | Golden ratio (φ) macro spacing — PageContainer sections, Flex gap, Card rhythm                                                                                                  |
+| [FORMS.md](./FORMS.md)                       | **Mandatory** react-hook-form + Zod 4                                                                                                                                           |
+| [TESTING.md](./TESTING.md)                   | **Mandatory** Vitest per component                                                                                                                                              |
+| [FRAME-A11Y-CI.md](./FRAME-A11Y-CI.md)       | Per-frame axe a11y + geometry + coverage CI gates — how to run/regenerate locally                                                                                               |
+| [../README.md](../README.md)                 | Setup, workspace wiring, theme                                                                                                                                                  |
 
 ## Preview
 

package/docs/data-display/list-row.tsx

@@ -26,6 +26,27 @@ export default function Demo() {
       subtitle="leading · title/description · trailing action · short entity lists inside a Card"
     >
       <Flex direction="col" gap="lg">
+        <Card>
+          <CardHeader>
+            <CardTitle level={2}>Navigation rows</CardTitle>
+            <CardDescription>
+              The whole row is one link, including its metadata. Current location uses aria-current.
+            </CardDescription>
+          </CardHeader>
+          <CardContent flush>
+            <ListRow
+              asChild
+              title="Roles and permissions"
+              description="Inspect organization access"
+              overflow="wrap"
+            >
+              <a href="?section=roles" aria-current="page" />
+            </ListRow>
+            <ListRow asChild title="Members" description="Assign roles to organization members">
+              <a href="?section=members" />
+            </ListRow>
+          </CardContent>
+        </Card>
         <Card>
           <CardHeader>
             <CardTitle level={2}>アクティブなセッション Active sessions</CardTitle>

package/docs/data-entry/search-input.tsx

@@ -7,6 +7,7 @@ import { Flex, PageContainer } from "@godxjp/ui/layout";
 
 /**
  * SearchInput — debounced search box with a built-in clear button.
+ * onSearch runs after a changed query settles, never on mount.
  * Always listen to onSearch (NOT onChange). Uncontrolled for local filters,
  * controlled when search state lives in a URL param. Never a raw <input>.
  * Composed only from real @godxjp/ui components.

package/docs/data-entry/segmented.tsx

@@ -0,0 +1,124 @@
+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 { Flex, PageContainer } from "@godxjp/ui/layout";
+import { CalendarDays, Columns3, LayoutList, Monitor, Moon, Sun } from "lucide-react";
+
+/**
+ * Segmented — one-of-N from a small, closed, always-visible set. antd's Segmented drawn on Radix
+ * RadioGroup: a recessed track with the chosen item as a lifted slab, radiogroup semantics, arrow
+ * keys between members. The track measures exactly --control-height, so it sits level with an
+ * Input or a Button on the same row.
+ */
+export default function Demo() {
+  const [theme, setTheme] = useState("system");
+  const [view, setView] = useState("list");
+  const [range, setRange] = useState("week");
+
+  return (
+    <PageContainer title="Segmented" subtitle="閉じた選択肢からひとつだけ · テーマ・表示形式・期間">
+      <Flex direction="col" gap="lg">
+        <Card>
+          <CardHeader>
+            <CardTitle level={2}>ラベルのみ</CardTitle>
+            <CardDescription>
+              選択肢が 2〜4 個で、すべて画面に出せるときは Select ではなくこちら。ひとつは必ず
+              選ばれている状態なので、ToggleGroup ではなく radiogroup として読み上げられます。
+            </CardDescription>
+          </CardHeader>
+          <CardContent>
+            <Flex direction="col" gap="md">
+              <Segmented
+                aria-label="期間"
+                value={range}
+                onValueChange={setRange}
+                options={[
+                  { value: "day", label: "日" },
+                  { value: "week", label: "週" },
+                  { value: "month", label: "月" },
+                ]}
+              />
+              <Text size="xs" tone="muted">
+                選択中: {range}
+              </Text>
+            </Flex>
+          </CardContent>
+        </Card>
+
+        <Card>
+          <CardHeader>
+            <CardTitle level={2}>アイコン付き</CardTitle>
+            <CardDescription>
+              `icon` は aria-hidden で描かれ、読み上げ名は `label` のままです。
+            </CardDescription>
+          </CardHeader>
+          <CardContent>
+            <Flex direction="col" gap="md">
+              <Segmented
+                aria-label="テーマ"
+                value={theme}
+                onValueChange={setTheme}
+                options={[
+                  { value: "light", label: "ライト", icon: <Sun aria-hidden="true" /> },
+                  { value: "dark", label: "ダーク", icon: <Moon aria-hidden="true" /> },
+                  { value: "system", label: "システム", icon: <Monitor aria-hidden="true" /> },
+                ]}
+              />
+              <Segmented
+                aria-label="表示形式"
+                value={view}
+                onValueChange={setView}
+                options={[
+                  { value: "list", label: "一覧", icon: <LayoutList aria-hidden="true" /> },
+                  { value: "board", label: "ボード", icon: <Columns3 aria-hidden="true" /> },
+                  {
+                    value: "calendar",
+                    label: "カレンダー",
+                    icon: <CalendarDays aria-hidden="true" />,
+                  },
+                ]}
+              />
+            </Flex>
+          </CardContent>
+        </Card>
+
+        <Card>
+          <CardHeader>
+            <CardTitle level={2}>フォームの中で</CardTitle>
+            <CardDescription>
+              `name` を渡すとネイティブフォームで送信されます。無効化は選択肢ごとにも、グループ
+              全体にもかけられます。
+            </CardDescription>
+          </CardHeader>
+          <CardContent>
+            <Flex direction="col" gap="md">
+              <FormField id="segmented-plan" label="プラン">
+                <Segmented
+                  id="segmented-plan"
+                  name="plan"
+                  defaultValue="standard"
+                  options={[
+                    { value: "light", label: "ライト" },
+                    { value: "standard", label: "スタンダード" },
+                    { value: "enterprise", label: "エンタープライズ", disabled: true },
+                  ]}
+                />
+              </FormField>
+              <Segmented
+                aria-label="無効化されたグループ"
+                defaultValue="a"
+                disabled
+                options={[
+                  { value: "a", label: "A" },
+                  { value: "b", label: "B" },
+                ]}
+              />
+            </Flex>
+          </CardContent>
+        </Card>
+      </Flex>
+    </PageContainer>
+  );
+}

package/docs/general/button/index.md

@@ -10,3 +10,7 @@ For filter tabs / segmented toggles that show a per-option total, pass the `coun
 (`<Button variant="outline" count={18}>Chờ bay</Button>`) instead of nesting a `Badge` —
 it renders a borderless counter pill, formatted in the active locale and toned to the
 button variant, so an outline button never ends up with a doubled border.
+
+For long collection labels, use `wrap` with `align="start"` and `fullWidth`. The button
+grows vertically while retaining the size preset's minimum target height. Keep badges
+and other row metadata outside the button. `align="end"` follows the document direction.

package/docs/layout/master-detail.tsx

@@ -15,6 +15,9 @@ import { Button, Text } from "@godxjp/ui/general";
 import { Flex, MasterDetail, PageContainer } from "@godxjp/ui/layout";
 
 /**
+ * Pass mobilePane="master" or "detail" for one-pane navigation below the token-owned collapse threshold.
+ * Supply detailBack with a native back link; own selection in URL/router history.
+ * Omit mobilePane to retain the original stacked composition.
  * MasterDetail · チーム画面 (SCR-110) の正準構成 — 流動的な一覧 + 固定幅の詳細レール。
  *
  * Shows: rail="detail" (既定 · 1fr / 320px) と rail="master" (先頭ナビゲーションレール)、