@godxjp/ui 23.0.0 → 23.2.0

package/dist/tokens/foundation.css

@@ -238,6 +238,24 @@
   --phi-0: var(--phi-unit);
   --phi-p1: calc(var(--phi-unit) * var(--ratio-phi));
   --phi-p2: calc(var(--phi-p1) * var(--ratio-phi));
+
+  --duration-fast: 150ms;
+  --duration-base: 250ms;
+  --duration-slow: 500ms;
+  --ease-standard: cubic-bezier(0.2, 0, 0, 1);
+  --ease-emphasized: cubic-bezier(0.32, 0.72, 0, 1);
+  --ease-decelerate: cubic-bezier(0, 0, 0, 1);
+  --ease-accelerate: cubic-bezier(0.3, 0, 1, 1);
+  --reveal-distance: 10px;
+
+  --reveal-stagger-step: 60ms;
+
+  --duration-loop: 1400ms;
+
+  --activity-interval: var(--duration-loop);
+
+  --activity-stagger-step: 160ms;
+
 }
 
 .ui-scale-fixed {
@@ -289,22 +307,6 @@
   --space-chrome-gap: var(--space-2);
   --field-label-gap: var(--space-2);
 
-  --duration-fast: 150ms;
-  --duration-base: 250ms;
-  --duration-slow: 500ms;
-  --ease-standard: cubic-bezier(0.2, 0, 0, 1);
-  --ease-emphasized: cubic-bezier(0.32, 0.72, 0, 1);
-  --ease-decelerate: cubic-bezier(0, 0, 0, 1);
-  --ease-accelerate: cubic-bezier(0.3, 0, 1, 1);
-  --reveal-distance: 10px;
-
-  --reveal-stagger-step: 60ms;
-
-  --duration-loop: 1400ms;
-
-  --activity-interval: var(--duration-loop);
-
-  --activity-stagger-step: 160ms;
 }
 
 .dark,

package/docs/CONSUMER-RULES.md

@@ -5,13 +5,18 @@ Read this once; the audit enforces it. Everything else in `docs/` is for contrib
 1. Load styles with `@import "@godxjp/ui/styles"` (fonts bundled) or `@import "@godxjp/ui/styles/core"` (no fonts). Never cherry-pick `*-layout.css`.
 2. Every page is `<PageContainer title subtitle extra footer>`; its sections are spaced by the page. Group items inside a section with `<Flex direction="col" gap>` or `<ResponsiveGrid>`.
 3. No Tailwind layout on your own elements: no `flex`, `grid`, `gap-*`, `p-*`, `m-*`, `space-*`. Rows are `<Flex>` (default row), stacks are `<Flex direction="col">`, grids are `<ResponsiveGrid>`.
-4. No hand-rolled surfaces: no `rounded-* border bg-*` divs. A box is `Card`, a pill is `Badge`, a person is `Avatar`, a row is `ListRow`, a label/value pair is `Descriptions`, an empty area is `EmptyState`.
+4. No hand-rolled surfaces: no `rounded-* border bg-*` divs. A box is `Card`, a pill is `Badge`, a person is `Avatar`, a row is `ListRow`, a label/value pair is `Descriptions`, an empty area is `EmptyState`, a read-only sample of a colour the USER chose is `Swatch`.
 5. Real controls only: `Button`, `Input`, `Select`, `Textarea`, `Checkbox`… never raw `<button>`/`<input>`; a labelled control lives in `<FormField label>`. A Select outside a form takes `width="auto"`. **A disabled control's reason is visible text, never a tooltip** — see below.
 6. Text is `<Text>` / `<Heading>` with `tone`, `size`, `weight`, `truncate`, `mono` — not `className="text-muted-foreground font-semibold"`.
 7. Colours are semantic tokens (`tone="destructive"`, `bg-primary`), never palette names, hex, or `bg-black` / `text-white`.
 8. Sizes come from props (`size`, `width`, `columns`), never `w-[240px]` / `max-h-[420px]`.
 9. Logical directions (`ms-`, `me-`, `start-`, `end-`) when a utility is unavoidable; never `ml-` / `left-`.
-10. Run `node node_modules/@godxjp/ui/scripts/ui-audit.mjs <dir>` before every review; then `visual-audit.mjs <url>` on the running app. Zero errors is the bar.
+10. A `Card` whose whole body is a table gets `<CardContent flush>` — the table must touch the
+    card's inner edge. A default `CardContent` pads 16px while the table draws its own border, so
+    the table reads as a second box inside the card, and a wide one runs past the card entirely.
+    (`flush` alone is enough: it drops the border, the radius and the inline padding. `tight` is a
+    different knob — it governs the header band, not the body's edges.)
+11. Run `node node_modules/@godxjp/ui/scripts/ui-audit.mjs --changed` before every review; a browser sweep with `visual-audit.mjs` is a separate, heavier run — do it when the work is a visual review, not on every change; `visual-audit.mjs <url>` on the running app. Zero errors is the bar.
 
 **Opting a deliberate exception out.** Name the rule; the block form also has to say why.
 
@@ -45,6 +50,6 @@ information belongs on the screen:
 - `ServiceLauncherCard` already has this shape as a prop — `disabledReason`, rendered above the
   action — and it is the pattern to copy anywhere else.
 
-If the control is disabled *pending something the user can fix*, prefer leaving it enabled and
+If the control is disabled _pending something the user can fix_, prefer leaving it enabled and
 explaining on submit: an inert control with a paragraph beside it is often a validation message
 wearing a disguise.

package/docs/CUSTOMER-THEMING.md

@@ -89,7 +89,7 @@ Import the styles, then set anchor tokens in your app's `theme.css` (loaded afte
 
 /* ── Shadow tint — ONE knob ─────────────────────────────────────── */ --shadow-color: 12 26 49; /* RGB channels (default 0 0 0). Tints the WHOLE shadow ramp. */
 
-/* ── Brand depth — all opt-in, all quiet by default ─────────────── */ --shadow-glow: 0 8px 20px hsl(var(--primary) / 0.32); /* glow halo on the primary CTA */ --card-shadow: 0 1px 2px rgb(12 26 49 / 0.06), 0 10px 28px -14px rgb(12 26 49 / 0.2); /* lift every Card */ --focus-ring-color: var(--ring); /* hue of every focus ring */ --focus-ring-width: 2px; /* thickness of every focus ring — 0 turns it OFF */ --focus-ring-opacity: 1; /* alpha of every focus ring */ --focus-ring-offset: 0px; /* gap, outline-form rings only (star, dot, anchor) */ --gradient-hero: linear-gradient( 180deg, hsl(var(--accent)), transparent ); /* PageContainer header banner */ --gradient-glow: radial-gradient( 60% 70% at 90% -8%, hsl(var(--primary) / 0.1), transparent 70% ); /* AppShell ambient wash */ --overlay-background: rgb(12 26 49 / 0.55); /* modal scrim (Dialog / Sheet / Drawer) */ } ```
+/* ── Brand depth — all opt-in, all quiet by default ─────────────── */ --shadow-glow: 0 8px 20px hsl(var(--primary) / 0.32); /* glow halo on the primary CTA */ --card-shadow: 0 1px 2px rgb(12 26 49 / 0.06), 0 10px 28px -14px rgb(12 26 49 / 0.2); /* lift every Card */ --focus-ring-color: var(--ring); /* hue of every focus ring */ --focus-ring-weight: var(--stroke-md); /* thickness of every focus ring — 2px; nothing paints until <html data-focus-outline="on"> */ --focus-ring-opacity: 1; /* alpha of every focus ring */ --focus-ring-offset: 0px; /* gap, outline-form rings only (star, dot, anchor) */ --gradient-hero: linear-gradient( 180deg, hsl(var(--accent)), transparent ); /* PageContainer header banner */ --gradient-glow: radial-gradient( 60% 70% at 90% -8%, hsl(var(--primary) / 0.1), transparent 70% ); /* AppShell ambient wash */ --overlay-background: rgb(12 26 49 / 0.55); /* modal scrim (Dialog / Sheet / Drawer) */ } ```
 
 ### The anchor tokens (single knobs that propagate)
 
@@ -101,23 +101,33 @@ Import the styles, then set anchor tokens in your app's `theme.css` (loaded afte
 | `--shadow-color`                                                           | `0 0 0`                 | every shadow step `--shadow-{xs…2xl}` (`rgb(color / α)`)                                |
 | `--shadow-glow`                                                            | invisible               | brand glow halo on the primary CTA (set the full shadow value)                          |
 | `--card-shadow`                                                            | `none`                  | resting elevation of every Card                                                         |
-| `--focus-ring-color` / `--focus-ring-width`                                | `var(--ring)` / `2px`   | hue & thickness of every keyboard-focus ring (`width: 0` turns every ring OFF)          |
+| `--focus-ring-color` / `--focus-ring-weight`                               | `var(--ring)` / `1px`   | hue & thickness of every keyboard-focus ring — but nothing paints until the switch below is on |
 | `--focus-ring-opacity` / `--focus-ring-offset`                             | `1` / `0px`             | alpha of every ring · gap for outline-form rings (star, carousel dot, heading anchor)   |
 | `--gradient-{hero,glow,brand}`                                             | `none`                  | hero header banner / AppShell ambient wash / spare (set the full gradient)              |
 | `--overlay-background`                                                     | `rgb(0 0 0 / .5)`       | the scrim of every overlay (Dialog / AlertDialog / Sheet / Drawer)                      |
 
-### Focus ring — one definition, three levels of override
+### Focus ring — THE SWITCH FIRST, then three levels of override
 
-Every keyboard-focus ring in the system is drawn by a single rule (`src/styles/focus-ring.css`) reading the four tokens above. Nothing else paints one; a test fails the build if a stylesheet tries.
+**The indicator ships OFF.** `--focus-outline` is `0`, and every painted focus length multiplies by it, so by default nothing paints a focus mark. That is a product decision with a stated cost — it forfeits WCAG 2.2 SC 2.4.7 (AA) and a JIS X 8341-3 AA claim — recorded in `docs/DESIGN-AUTHORITY.md`. Turning it on is ONE attribute on the root element, no CSS:
 
-That means retuning is a one-liner and it reaches everything:
+```html
+<html data-focus-outline="on"></html>
+```
+
+(`AppProvider` has the equivalent.) Every `:focus-visible` selector is present either way; only the paint is switched.
+
+Every ring is then drawn by a single rule (`src/styles/focus-ring.css`) reading the tokens above. Nothing else paints one; a test fails the build if a stylesheet tries.
+
+**Thickness is `--focus-ring-weight`, never `--focus-ring-width`.** The width is DERIVED — `calc(var(--focus-ring-weight) * var(--focus-outline))` — so assigning it directly paints a ring even while the indicator is switched off, and that is exactly what the build-failing test forbids a stylesheet to do.
 
 ```css
 :root {
   --focus-ring-color: 24 99% 46%; /* every ring, brand orange */
-  --focus-ring-width: 3px; /* every ring, thicker */
+  --focus-ring-weight: var(--stroke-md); /* every ring, 2px */
 }
-````
+```
+
+**A slim ring that still satisfies the criteria.** Switched on, the shipped weight is one hairline (1px) in the focus hue, measured in Chromium at **5.05:1** light and **7.07:1** dark on every surface a control sits on — so SC 1.4.11 (3:1, non-text contrast) is met on colour, independent of thickness. SC 2.4.13 Focus Appearance (AAA) additionally wants a perimeter of at least 2 CSS px: set `--focus-ring-weight: var(--stroke-md)` (measured: a 2px ring, same hue, same ratio). `var(--stroke-lg)` is the heavy 3px mark.
 
 **Per component.** A component that genuinely needs a different ring publishes its own knob and the rule picks it up locally — Toggle and TimeInput ship a heavier, softer ring because they are filled surfaces where a hard 2px reads as a second border:
 
@@ -136,7 +146,7 @@ That means retuning is a one-liner and it reaches everything:
 <div style={{ "--focus-ring-color": "0 84% 60%" } as React.CSSProperties}>…</div>
 ```
 
-**Turning it off** — `--focus-ring-width: 0`, at any of the three levels. It ships **on** (WCAG 2.4.7 / 2.4.11); switching it off is a deliberate act on your side, never a default of this package. Removing the visible focus indicator fails WCAG 2.4.7 — do it only where another indicator takes over.
+**Turning it back off** — drop the `data-focus-outline` attribute (or set `--focus-outline: 0`), which is the shipped state. Do NOT reach for `--focus-ring-width`: it is derived from the weight and the switch, and pinning it to any value is the same mistake in the other direction. Note the cost either way — with no visible focus indicator the package does not meet WCAG 2.2 SC 2.4.7.
 
 **Adding your own component to the system**: put `ui-focus-ring` (or `ui-focus-ring-outline` when the mark needs a gap) on the focusable element.
 

package/docs/DATETIME.md

@@ -23,10 +23,18 @@ Omit `locale`, `timezone`, `timeFormat`, `dateFormat` → synced from AppProvide
 
 | value | Pattern      | Default locale |
 | ----- | ------------ | -------------- |
-| `iso` | `yyyy-MM-dd` | ja             |
+| `iso` | `yyyy-MM-dd` | —              |
+| `ymd` | `yyyy/MM/dd` | ja             |
 | `dmy` | `dd/MM/yyyy` | vi             |
 | `mdy` | `MM/dd/yyyy` | en             |
 
+`ymd` and `iso` are both year-first and are NOT interchangeable: a Japanese business document
+(請求書, 申請書) is written `2026/05/01`, never `2026-05-01`. `ja` defaulted to `iso` until a
+Japanese-first consumer shipped its own date formatter as an explicit stopgap purely to get the
+slashes — rule 1 above broken by this package's own default. Only the DEFAULT moved: a stored
+preference still wins, `defaultDateFormat` still pins any value, and `iso` is one option away in
+`<DateFormatPicker />`.
+
 Sent to backend as `x-date-format`. Pick with `<DateFormatPicker />`.
 
 ## kind presets
@@ -43,9 +51,10 @@ Sent to backend as `x-date-format`. Pick with `<DateFormatPicker />`.
 
 ## ISO 8601 patterns
 
-Date order follows `dateFormat` from AppProvider (`iso` | `dmy` | `mdy`):
+Date order follows `dateFormat` from AppProvider (`iso` | `ymd` | `dmy` | `mdy`):
 
 - `iso`: `yyyy-MM-dd` + `yyyy-MM-dd HH:mm`
+- `ymd`: `yyyy/MM/dd` + `yyyy/MM/dd HH:mm`
 - `dmy`: `dd/MM/yyyy` + `dd/MM/yyyy HH:mm`
 - `mdy`: `MM/dd/yyyy` + `MM/dd/yyyy HH:mm`
 

package/docs/DESIGN-AUTHORITY.md

@@ -253,7 +253,8 @@ a weaker one.** An algorithm guarantees a value is _consistent_; this repo had t
 times (below) precisely because consistent is not the same as _accessible_. A threshold guarantees
 the property actually being sold.
 
-**To change a derived value:** change it, run `pnpm test`, and if a threshold breaks the value is
+**To change a derived value:** change it, run the test file that owns the threshold (never the full
+suite — that is CI's job on the PR), and if a threshold breaks the value is
 wrong. Do not relax the threshold.
 
 **The four overrides that existed even while a generator did** — the clearest evidence the

package/docs/FRAME-COVERAGE-REPORT.md

@@ -3,16 +3,27 @@
 > 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: **135**
-- With ≥1 frame: **130** · zero-frame: **5**
+- Public components: **150**
+- With ≥1 frame: **134** · zero-frame: **16**
 - Fully covered (every contract axis declared): **0**
 
 ## UNTESTED — no `/frame/**` route
 
 - [ ] `inertiaUpload`
+- [ ] `FormFieldControl`
+- [ ] `FormFieldArray`
+- [ ] `useZodForm`
 - [ ] `CardBar`
 - [ ] `VisuallyHidden`
 - [ ] `RangeTimeline`
+- [ ] `ServiceCatalogCta`
+- [ ] `OverlayPortalProvider`
+- [ ] `SkeletonArticle`
+- [ ] `SkeletonAvatar`
+- [ ] `SkeletonButton`
+- [ ] `SkeletonInput`
+- [ ] `SkeletonNode`
+- [ ] `SkeletonImage`
 - [ ] `ChatBubbleList`
 
 ## Per-component contract axes
@@ -22,6 +33,10 @@ Legend: ✓ covered · N/A reasoned skip · · UNTESTED (blank cell = UNTESTED).
 | Component | Frame | visua | state | owner | conte | respo | inter | acces | prefe | async |
 | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
 | inertiaUpload | **✗** | · | · | · | · | · | · | · | · | · |
+| FormRoot | ✓ | · | · | · | · | · | · | · | · | · |
+| FormFieldControl | **✗** | · | · | · | · | · | · | · | · | · |
+| FormFieldArray | **✗** | · | · | · | · | · | · | · | · | · |
+| useZodForm | **✗** | · | · | · | · | · | · | · | · | · |
 | CardBar | **✗** | N/A | N/A | N/A | · | · | · | · | · | · |
 | TimeRangePicker | ✓ | · | · | · | · | · | · | · | · | · |
 | VisuallyHidden | **✗** | N/A | N/A | N/A | · | · | · | · | · | · |
@@ -53,8 +68,12 @@ Legend: ✓ covered · N/A reasoned skip · · UNTESTED (blank cell = UNTESTED).
 | CardContent | ✓ | N/A | N/A | N/A | · | · | · | · | · | · |
 | StatCard | ✓ | N/A | N/A | · | · | · | · | · | · | · |
 | ServiceLauncherCard | ✓ | N/A | N/A | N/A | · | · | · | · | · | · |
+| ServiceCatalogCta | **✗** | N/A | N/A | N/A | · | · | · | · | · | · |
 | Badge | ✓ | ✓ | N/A | N/A | · | · | · | · | · | · |
 | Legend | ✓ | N/A | N/A | N/A | · | · | · | · | · | · |
+| Swatch | ✓ | N/A | N/A | N/A | · | · | · | · | · | · |
+| FeatureList | ✓ | N/A | N/A | N/A | · | · | · | · | · | · |
+| Thumbnail | ✓ | · | N/A | N/A | · | · | · | · | · | · |
 | ListRow | ✓ | ✓ | N/A | N/A | · | · | · | · | · | · |
 | CredentialReveal | ✓ | ✓ | N/A | N/A | · | · | · | · | · | · |
 | QrCode | ✓ | ✓ | N/A | · | · | · | · | · | · | · |
@@ -95,6 +114,7 @@ Legend: ✓ covered · N/A reasoned skip · · UNTESTED (blank cell = UNTESTED).
 | Steps | ✓ | ✓ | N/A | · | · | · | · | · | · | · |
 | Toolbar | ✓ | N/A | · | N/A | · | · | · | · | · | · |
 | AppProvider | ✓ | · | · | · | · | · | · | · | · | · |
+| OverlayPortalProvider | **✗** | · | · | · | · | · | · | · | · | · |
 | formatDate | ✓ | · | · | · | · | · | · | · | · | · |
 | TimePicker | ✓ | · | · | · | · | · | · | · | · | · |
 | Cascader | ✓ | ✓ | · | · | · | · | · | · | · | · |
@@ -116,7 +136,13 @@ Legend: ✓ covered · N/A reasoned skip · · UNTESTED (blank cell = UNTESTED).
 | PrefetchLink | ✓ | N/A | N/A | N/A | · | · | · | · | · | · |
 | Avatar | ✓ | ✓ | N/A | N/A | · | · | · | · | · | · |
 | Separator | ✓ | · | N/A | N/A | · | · | · | · | · | · |
-| Skeleton | ✓ | N/A | N/A | N/A | · | · | · | · | · | · |
+| Skeleton | ✓ | N/A | · | N/A | · | · | · | · | · | · |
+| SkeletonArticle | **✗** | N/A | · | N/A | · | · | · | · | · | · |
+| SkeletonAvatar | **✗** | ✓ | N/A | N/A | · | · | · | · | · | · |
+| SkeletonButton | **✗** | ✓ | N/A | N/A | · | · | · | · | · | · |
+| SkeletonInput | **✗** | ✓ | N/A | N/A | · | · | · | · | · | · |
+| SkeletonNode | **✗** | N/A | N/A | N/A | · | · | · | · | · | · |
+| SkeletonImage | **✗** | N/A | N/A | N/A | · | · | · | · | · | · |
 | Toggle | ✓ | ✓ | · | N/A | · | · | · | · | · | · |
 | ToggleGroup | ✓ | ✓ | · | · | · | · | · | · | · | · |
 | AspectRatio | ✓ | N/A | N/A | N/A | · | · | · | · | · | · |

package/docs/SPACING.md

@@ -42,11 +42,11 @@ Implementation: `src/tokens/base.css` (values) · layout owners: `src/styles/*-l
 | `--card-space-body-y`                             | `--space-section-active` | Header↔body gap                            |
 | `--card-space-header-y` / `--card-space-footer-y` | `--space-stack-sm`       | Banded header + separated footer band      |
 
-| Component                 | Use                                         |
-| ------------------------- | ------------------------------------------- |
-| `StatCard`                | KPI / stat tile (`solo` path)               |
-| `CardContent solo`        | Body-only card (same padding as `StatCard`) |
-| `CardContent flush tight` | Edge-to-edge table/tabs in card             |
+| Component           | Use                                                                                                                                                                                     |
+| ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `StatCard`          | KPI / stat tile (`solo` path)                                                                                                                                                           |
+| `CardContent solo`  | Body-only card (same padding as `StatCard`)                                                                                                                                             |
+| `CardContent flush` | Edge-to-edge table/tabs in card — REQUIRED when the table IS the body (rule 10). `flush` alone drops the border, radius and inline padding; add `tight` only to change the HEADER band. |
 
 See preview **Data Display → Card** for live examples.
 
@@ -64,6 +64,36 @@ Pick by AXIS, and note that the three do **not** share one value: each reads a d
 
 Because `ui-card-inset-x` reads `--card-space-inset`, it follows the card it sits in: a `Card density="tight"` or `"cozy"` moves those cells with the shell. The other two read fixed steps (band and body) and do not.
 
+## Control interiors are NOT on this scale
+
+Everything above is the space **between** things — page sections, siblings in a stack, a card's
+shell against its content. A control's **inside** is a different measurement and it is derived from
+the control band (`--control-height`, `--control-padding-x`), never from `--space-*`. The two do not
+meet, and reading a step off the table above as a minimum for a control's interior gives the wrong
+answer.
+
+The case that keeps coming up is `Segmented`'s track (gh#503). Its padding is **2px**, and the
+label inside it therefore sits ~5px from the track's outer edge — under `--space-2` (8px), which is
+NOT a floor this document sets for anything.
+
+2px is the whole geometry of the control:
+
+```
+label height = --control-height − track padding × 2     →  32 − 4 = 28
+```
+
+so the track measures **exactly** `--control-height` and a `Segmented` sits level with the `Input`
+and the `Button` beside it on the same row. Raise the padding to 8px and one of two things has to
+give: either the label band drops to 16px — a 14px type size in a 16px box, under every hit target
+this library holds — or the track grows to 44px (28 + 8 × 2) and stops lining up with every other
+control. The same derivation is why a `Button`'s own label sits ~5px inside its border. A control
+is sized by its band; the band is what a dense enterprise UI is for.
+
+**The knob, if a service wants a roomier control.** `--segmented-track-padding` is a published
+component token (`src/tokens/components/segmented.css`); raising it re-derives the item height from
+the same formula, so the track stays exactly one control tall. Do not reach for a Tailwind `p-*` on
+the control — the audit rejects it, and it would break the identity above.
+
 ## MCP
 
 `get_pattern page-sections` (a page of Cards, spaced by the page) · `get_rule 40` (mobile-first spacing) · `list_audit_rules` (the spacing rules the CLI enforces).

package/docs/TOKENS.md

@@ -220,7 +220,7 @@ The census confirmed the number and rejected the diagnosis: **`width` is not one
 
 **Px, never rem.** A stroke is a _device_ line: its job is to read as one crisp rule at any type size, so it must not grow when the root font-size does. Every token that moved onto this scale was already `px` for that reason; a `rem` thickness (`--slider-track-height: 0.375rem`) is a different decision and stayed where it was. **Not `--scaling`-multiplied** either — `--scaling` is a density knob, and a 1px divider at 0.92px would blur rather than tighten.
 
-`--focus-ring-width` is now a member (`var(--stroke-md)`) rather than a parallel authority, so a high-contrast theme that wants every emphasis stroke at 3px sets one token.
+The focus mark reads this scale too, through `--focus-ring-weight` — `var(--focus-outline-weight)`, which is `var(--stroke-hairline)` (the light 1px mark the ON state ships). `--focus-ring-width` is DERIVED from it (`weight × --focus-outline`, the on/off switch) and must never be set directly; a theme that wants a 2px focus perimeter (WCAG 2.2 SC 2.4.13) sets `--focus-ring-weight: var(--stroke-md)`. See docs/CUSTOMER-THEMING.md.
 
 #### `--band-height-*` — the vertical extent of a horizontal band
 

package/docs/assets/shot-landscape.svg

@@ -0,0 +1,12 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="960" height="540" viewBox="0 0 960 540" role="img">
+  <rect width="960" height="540" fill="hsl(210 20% 97%)"/>
+  <rect width="960" height="56" fill="hsl(152 34% 38%)"/>
+  <rect x="24" y="22" width="140" height="12" rx="6" fill="hsl(152 34% 80%)"/>
+  <rect y="56" width="216" height="484" fill="hsl(210 16% 92%)"/>
+  <rect x="24" y="92" width="160" height="10" rx="5" fill="hsl(210 12% 76%)"/>
+  <rect x="24" y="124" width="160" height="10" rx="5" fill="hsl(210 12% 82%)"/>
+  <rect x="24" y="156" width="160" height="10" rx="5" fill="hsl(210 12% 82%)"/>
+  <rect x="248" y="92" width="320" height="160" rx="12" fill="hsl(210 16% 88%)"/>
+  <rect x="592" y="92" width="320" height="160" rx="12" fill="hsl(210 16% 88%)"/>
+  <rect x="248" y="284" width="664" height="212" rx="12" fill="hsl(210 16% 90%)"/>
+</svg>

package/docs/assets/shot-portrait.svg

@@ -0,0 +1,10 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="360" height="640" viewBox="0 0 360 640" role="img">
+  <rect width="360" height="640" fill="hsl(210 20% 97%)"/>
+  <rect width="360" height="72" fill="hsl(204 60% 46%)"/>
+  <rect x="20" y="30" width="120" height="12" rx="6" fill="hsl(204 60% 82%)"/>
+  <rect x="20" y="104" width="320" height="120" rx="10" fill="hsl(210 16% 88%)"/>
+  <rect x="20" y="248" width="320" height="64" rx="10" fill="hsl(210 16% 90%)"/>
+  <rect x="20" y="336" width="320" height="64" rx="10" fill="hsl(210 16% 90%)"/>
+  <rect x="20" y="424" width="320" height="64" rx="10" fill="hsl(210 16% 90%)"/>
+  <rect x="20" y="540" width="320" height="44" rx="10" fill="hsl(204 60% 46%)"/>
+</svg>

package/docs/data-display/card/index.tsx

@@ -111,6 +111,12 @@ export default function Demo() {
               </CardHeader>
               <CardContent>枠線のみ</CardContent>
             </Card>
+            <Card variant="borderless">
+              <CardHeader>
+                <CardTitle level={2}>borderless</CardTitle>
+              </CardHeader>
+              <CardContent>塗りのみ · 枠線なし</CardContent>
+            </Card>
             <Card variant="featured">
               <CardHeader>
                 <CardTitle level={2}>featured</CardTitle>
@@ -120,6 +126,40 @@ export default function Demo() {
           </ResponsiveGrid>
         </Flex>
 
+        <Flex direction="col" gap="sm">
+          <Text as="div" weight="medium">
+            hoverable · actions — Ant Design の hoverable と actions
+          </Text>
+          <ResponsiveGrid columns={{ sm: 1, md: 2 }}>
+            {/*
+             * `hoverable` は見た目だけのフラグです。カード全体が押せるように見えるなら、
+             * キーボードでも届く本物のコントロールを必ず同居させます（ここでは footer の
+             * Button）。div に onClick を置くのは禁止です。
+             */}
+            <Card hoverable>
+              <CardHeader>
+                <CardTitle level={2}>ホバーで浮き上がる</CardTitle>
+                <CardDescription>--card-hover-shadow まで一段上がります</CardDescription>
+              </CardHeader>
+              <CardFooter actions>
+                <Button variant="ghost">複製</Button>
+                <Button variant="ghost">共有</Button>
+                <Button variant="ghost">削除</Button>
+              </CardFooter>
+            </Card>
+            <Card hoverable accent="info" accentPlacement="perimeter">
+              <CardHeader>
+                <CardTitle level={2}>accent と併用</CardTitle>
+                <CardDescription>ホバー中もアテンションのリングは消えません</CardDescription>
+              </CardHeader>
+              <CardFooter actions>
+                <Button variant="ghost">承認</Button>
+                <Button variant="ghost">却下</Button>
+              </CardFooter>
+            </Card>
+          </ResponsiveGrid>
+        </Flex>
+
         <Flex direction="col" gap="sm">
           <Text as="div" weight="medium">
             Accent · accentPlacement=&quot;edge&quot; (既定 · 先頭エッジのレール)

package/docs/data-display/data-table/index.tsx

@@ -290,13 +290,28 @@ export default function Demo() {
           </AppProvider>
         </Flex>
 
-        <Flex direction="col" gap="sm">
+        <Flex direction="col" gap="sm" id="empty-builtin">
           <Text as="div" weight="medium">
             空の状態（data が空のとき自動表示）
           </Text>
           <DataTable data={[]} columns={columns} getRowId={(row) => row.id} />
         </Flex>
 
+        {/* The SAME cell with consumer content in it. `empty` takes a ReactNode, so a plain string
+            is a legal call — and the lifecycle cell used to be `padding: 0`, which put that string
+            flush against the table's edge. Measured here; see check:data-table-empty-inset. */}
+        <Flex direction="col" gap="sm" id="empty-plain-string">
+          <Text as="div" weight="medium">
+            空の状態（empty に文字列を渡す）
+          </Text>
+          <DataTable
+            data={[]}
+            columns={columns}
+            getRowId={(row) => row.id}
+            empty="まだ登録がありません"
+          />
+        </Flex>
+
         {/* — the two failure states, in the same table grid as empty/loading. */}
         <Flex direction="col" gap="sm">
           <Text as="div" weight="medium">
@@ -318,7 +333,7 @@ export default function Demo() {
           <DataTable data={[]} columns={columns} getRowId={(row) => row.id} error />
         </Flex>
 
-        <Flex direction="col" gap="sm">
+        <Flex direction="col" gap="sm" id="error-custom-node">
           <Text as="div" weight="medium">
             エラー（error にノードを渡して文言を差し替え）
           </Text>

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

@@ -0,0 +1,159 @@
+import {
+  Card,
+  CardContent,
+  CardDescription,
+  CardFooter,
+  CardHeader,
+  CardTitle,
+  FeatureList,
+} from "@godxjp/ui/data-display";
+import { Button, Text } from "@godxjp/ui/general";
+import { Flex, PageContainer, ResponsiveGrid } from "@godxjp/ui/layout";
+
+const STARTER = [
+  { state: "included", label: "ユーザー 10 名まで" },
+  { state: "included", label: "監査ログ", description: "直近 30 日分を保持します。" },
+  {
+    state: "limited",
+    label: "API 呼び出し",
+    description: "月 10,000 回を超えると 429 を返します。",
+  },
+  { state: "excluded", label: "SAML / OIDC シングルサインオン" },
+  { state: "excluded", label: "監査ログのエクスポート" },
+] as const;
+
+const ENTERPRISE = [
+  { state: "included", label: "ユーザー数 無制限" },
+  { state: "included", label: "監査ログ", description: "保持期間は契約単位で設定します。" },
+  { state: "included", label: "API 呼び出し", description: "レート上限は個別に調整します。" },
+  {
+    state: "included",
+    label: "SAML / OIDC シングルサインオン",
+    description: "SAML 2.0 と OIDC の両方に対応。",
+  },
+  { state: "included", label: "監査ログのエクスポート" },
+] as const;
+
+/**
+ * FeatureList — 先頭の状態グリフ（含む／含まない／制限あり）を持つ「文」のリスト。
+ *
+ * ListRow は 1 行のエンティティ行（区切り線・末尾アクション）、Timeline は順序のあるイベント
+ * レール、Descriptions は用語／値のグリッド。どれも「折り返す説明文つきの状態リスト」ではない。
+ * Composed only from real @godxjp/ui components.
+ */
+export default function Demo() {
+  return (
+    <PageContainer
+      title="FeatureList"
+      subtitle="状態グリフつきの文のリスト · グリフは最初の行に揃う"
+    >
+      <Flex direction="col" gap="lg">
+        <Card>
+          <CardHeader>
+            <CardTitle level={2}>三つの状態</CardTitle>
+            <CardDescription>
+              included（✓）· limited（−）· excluded（✗）。色は意味を運ぶ唯一の手段ではありません ——
+              形が違い、読み上げ用の語も添えられます（WCAG 1.4.1）。excluded を赤で塗らないのは、
+              「含まれない」は失敗ではなく事実だからです。
+            </CardDescription>
+          </CardHeader>
+          <CardContent>
+            <FeatureList items={[...STARTER]} />
+          </CardContent>
+        </Card>
+
+        <Card>
+          <CardHeader>
+            <CardTitle level={2}>折り返しても、グリフは最初の行に揃う</CardTitle>
+            <CardDescription>
+              グリフの枠は 1 行分（1lh）の高さで、その中央にグリフが置かれます。だから 3 行に
+              折り返すラベルでも、揃う先は箱の上端ではなく最初の行です。呼び出し側に数値は
+              ありません。
+            </CardDescription>
+          </CardHeader>
+          <CardContent>
+            <FeatureList
+              items={[
+                {
+                  state: "included",
+                  label:
+                    "組織をまたぐ権限の委譲（部門管理者が自部門の範囲内でだけロールを付け替えられる設定を含みます）",
+                  description:
+                    "委譲の範囲は組織ツリーのノード単位で決まり、親を超える付与はできません。監査ログには委譲元と委譲先の両方が記録されます。",
+                },
+                { state: "limited", label: "短いラベル" },
+              ]}
+            />
+          </CardContent>
+        </Card>
+
+        <ResponsiveGrid columns={{ base: 1, md: 2 }}>
+          <Card>
+            <CardHeader>
+              <CardTitle level={2}>Starter</CardTitle>
+              <CardDescription>小さなチームのための最小構成。</CardDescription>
+            </CardHeader>
+            <CardContent>
+              <FeatureList items={[...STARTER]} />
+            </CardContent>
+            <CardFooter>
+              <Button variant="outline">Starter を選ぶ</Button>
+            </CardFooter>
+          </Card>
+
+          <Card>
+            <CardHeader>
+              <CardTitle level={2}>Enterprise</CardTitle>
+              <CardDescription>監査と SSO を必要とする組織向け。</CardDescription>
+            </CardHeader>
+            <CardContent>
+              <FeatureList items={[...ENTERPRISE]} />
+            </CardContent>
+            <CardFooter>
+              <Button>Enterprise を選ぶ</Button>
+            </CardFooter>
+          </Card>
+        </ResponsiveGrid>
+
+        <Card>
+          <CardHeader>
+            <CardTitle level={2}>数量はラベルに組み立てる</CardTitle>
+            <CardDescription>
+              「· 10,000 req/mo」のような数量に専用の prop はありません。Text を label に入れる
+              書き方がすでに合法で audit も通るため、prop を足すと docs/WHAT-BELONGS-HERE.md の問い
+              1（consumer に手がないか）に落ちます。
+            </CardDescription>
+          </CardHeader>
+          <CardContent>
+            <FeatureList
+              items={[
+                {
+                  state: "limited",
+                  label: (
+                    <>
+                      API 呼び出し{" "}
+                      <Text tone="muted" tabular>
+                        10,000 req/mo
+                      </Text>
+                    </>
+                  ),
+                },
+                {
+                  state: "included",
+                  label: (
+                    <>
+                      ストレージ{" "}
+                      <Text tone="muted" tabular>
+                        250 GB
+                      </Text>
+                    </>
+                  ),
+                },
+              ]}
+            />
+          </CardContent>
+        </Card>
+      </Flex>
+    </PageContainer>
+  );
+}