@godxjp/ui 23.0.0 → 23.1.0

package/dist/props/vocabulary/index.d.ts

@@ -4,4 +4,4 @@ export type { TitleProp, SubtitleProp, StatusProp, DescriptionProp, ExtraProp, F
 export type { PageDensityProp, PageContainerVariantProp, CenteredShellWidthProp, CenteredShellAlignProp, CenteredShellPresetProp, ErrorSurfaceModeProp, ErrorSurfaceStatusProp, AuthShellPresetProp, MobileShellHeightProp, MobileShellWidthProp, OrientationProp, TableDensityProp, DensityProp, GapNameProp, PadProp, PadRawProp, PadSides, GapProp, GapStepProp, } from "./layout.prop.js";
 export type { ButtonVariantProp, ButtonSizeProp, BadgeVariantProp, AppSettingPickerAppearanceProp, AppSettingToggleAppearanceProp, ShapeProp, AvatarShapeProp, TextSizeProp, TextToneProp, FontWeightProp, HeadingLevelProp, TextAlignProp, TextWhitespaceProp, SizeProp, ControlStatusProp, ControlVariantProp, FormLayoutProp, DescriptionsLayoutProp, BreakpointProp, ConfirmVariantProp, ToneProp, AlertVariantProp, SortDirectionProp, ColumnAlignProp, SortStateProp, RevealDelayProp, ActivityVariantProp, ActivityAnnounceProp, } from "./interaction.prop.js";
 export type { BreadcrumbItemProp, BreadcrumbProp, BreadcrumbItemMenuProp, BreadcrumbItemMenuEntryProp, BreadcrumbSeparatorProp, BreadcrumbItemRenderProp, } from "./navigation.prop.js";
-export type { GetRowIdProp, OnRowClickProp, ColumnDefProp, TablePresetProp, TableColumnPriorityProp, TableCellIndentProp, SelectedIdsProp, OnSelectChangeProp, OnTableDensityChangeProp, TableRowToneProp, RowToneProp, OnSortChangeProp, OnSearchChangeProp, OnClearFiltersProp, HasActiveFiltersProp, StickyProp, ColumnFixedProp, ColumnFilterValueProp, ColumnFilterItemProp, ColumnFilterStateProp, OnColumnFilterChangeProp, ColumnCompareProp, ColumnSorterProp, TableSelectionItemProp, TableRowSelectionProp, TableExpandableProp, TableSummaryProp, TableScrollProp, TableStickyProp, OnRowProp, TablePaginationProp, DescriptionsColumnProp, DescriptionsSpanProp, DescriptionsItemsProp, } from "./data.prop.js";
+export type { GetRowIdProp, GetRowLabelProp, OnRowClickProp, ColumnDefProp, TablePresetProp, TableColumnPriorityProp, TableCellIndentProp, SelectedIdsProp, OnSelectChangeProp, OnTableDensityChangeProp, TableRowToneProp, RowToneProp, OnSortChangeProp, OnSearchChangeProp, OnClearFiltersProp, HasActiveFiltersProp, StickyProp, ColumnFixedProp, ColumnFilterValueProp, ColumnFilterItemProp, ColumnFilterStateProp, OnColumnFilterChangeProp, ColumnCompareProp, ColumnSorterProp, TableSelectionItemProp, TableRowSelectionProp, TableExpandableProp, TableSummaryProp, TableScrollProp, TableStickyProp, OnRowProp, TablePaginationProp, DescriptionsColumnProp, DescriptionsSpanProp, DescriptionsItemsProp, } from "./data.prop.js";

package/dist/styles/control.css

@@ -177,8 +177,8 @@
     content: "";
     position: absolute;
     inset: 0;
-    min-inline-size: var(--button-bare-target-size);
-    min-block-size: var(--button-bare-target-size);
+    min-inline-size: var(--button-bare-target-size, var(--control-height-xs));
+    min-block-size: var(--button-bare-target-size, var(--control-height-xs));
     margin: auto;
   }
 
@@ -1338,6 +1338,20 @@
     inline-size: 0.75rem;
     block-size: 0.75rem;
   }
+
+  @media (pointer: coarse) {
+    .ui-number-input:not([data-size="xs"]):not([data-size="sm"]) {
+      --control-height: var(--number-input-touch-height);
+    }
+
+    .ui-number-input-steppers {
+      gap: 0;
+    }
+
+    .ui-number-input-step {
+      block-size: calc(var(--control-height) / 2);
+    }
+  }
 }
 
 @layer components {
@@ -1887,6 +1901,22 @@
     transition: opacity 150ms ease;
   }
 
+  .ui-control-inline-affix-action {
+    position: relative;
+  }
+
+  .ui-control-inline-affix-action::after {
+    content: "";
+    position: absolute;
+    inset-block-start: 50%;
+    inset-inline-start: 50%;
+    translate: -50% -50%;
+    min-inline-size: var(--touch-target-min);
+    min-block-size: var(--touch-target-min);
+    inline-size: 100%;
+    block-size: 100%;
+  }
+
   .ui-control-inline-affix-action:hover,
   .ui-control-inline-affix-action:focus-visible {
     color: hsl(var(--foreground));
@@ -2108,6 +2138,8 @@
     background-color: hsl(var(--muted));
 
     border-radius: 0;
+
+    padding-block: var(--calendar-bordered-weekday-padding-block);
   }
 
   .ui-calendar[data-bordered="true"] .ui-calendar-grid {
@@ -2536,7 +2568,7 @@
   }
 
   .ui-button--xs {
-    height: var(--button-xs-height);
+    height: var(--button-xs-height, var(--control-height-xs));
     gap: var(--button-xs-space-gap);
     padding-inline: var(--button-xs-space-inline);
     font-size: var(--button-xs-font-size);
@@ -2642,8 +2674,8 @@
 
   .ui-control[data-status="warning"],
   .ui-control-multiline[data-status="warning"] {
-    --focus-ring-color: var(--control-status-warning-border-color);
-    --focus-outline-color: var(--control-status-warning-border-color);
+    --focus-ring-color: var(--control-status-warning-outline-color);
+    --focus-outline-color: var(--control-status-warning-outline-color);
     --focus-ring-glow-color: var(--control-status-warning-glow-color);
     --focus-ring-glow-alpha: var(--control-status-warning-glow-alpha);
   }
@@ -2988,6 +3020,10 @@
     justify-content: center;
   }
 
+  .ui-segmented:not([data-orientation="vertical"]) {
+    row-gap: var(--segmented-track-padding);
+  }
+
   .ui-segmented[data-orientation="vertical"] {
     flex-direction: column;
   }

package/dist/styles/focus-ring.css

@@ -13,6 +13,19 @@
     .ui-toggle,
     .ui-checkbox,
     .ui-radio,
+    .ui-slider-thumb,
+    .ui-control-affix-action,
+    .ui-control-inline-affix-action,
+    .ui-search-input-clear,
+    .ui-tag-input-remove,
+    .ui-color-picker-input,
+    .ui-upload-tile-add,
+    .ui-upload-picture-empty,
+    .ui-upload-dropzone,
+    .ui-tabs-add,
+    .ui-steps-control,
+    .ui-carousel-previous,
+    .ui-carousel-next,
     .ui-steps-inline-control,
     .ui-pagination-link,
     .ui-legal-document-toc-link,
@@ -28,6 +41,7 @@
   ):focus-visible,
 
   .ui-checkbox[data-focus-visible],
+  .ui-radio[data-focus-visible],
   .ui-switch[data-focus-visible],
   .ui-slider-thumb[data-focus-visible],
   .ui-focus-ring[data-focus-visible],
@@ -59,6 +73,19 @@
       .ui-toggle,
       .ui-checkbox,
       .ui-radio,
+      .ui-slider-thumb,
+      .ui-control-affix-action,
+      .ui-control-inline-affix-action,
+      .ui-search-input-clear,
+      .ui-tag-input-remove,
+      .ui-color-picker-input,
+      .ui-upload-tile-add,
+      .ui-upload-picture-empty,
+      .ui-upload-dropzone,
+      .ui-tabs-add,
+      .ui-steps-control,
+      .ui-carousel-previous,
+      .ui-carousel-next,
       .ui-steps-inline-control,
       .ui-pagination-link,
       .ui-legal-document-toc-link,
@@ -74,6 +101,7 @@
     ):focus-visible,
 
   :root[data-focus-outline="on"] .ui-checkbox[data-focus-visible],
+  :root[data-focus-outline="on"] .ui-radio[data-focus-visible],
   :root[data-focus-outline="on"] .ui-switch[data-focus-visible],
   :root[data-focus-outline="on"] .ui-slider-thumb[data-focus-visible],
   :root[data-focus-outline="on"] .ui-focus-ring[data-focus-visible],

package/dist/styles/form-layout.css

@@ -2,6 +2,10 @@
 
 @layer components {
 
+  .ui-form-field-note {
+    word-break: auto-phrase;
+  }
+
   .ui-form-field-required {
     margin-inline-start: var(--space-inline-xs);
     color: hsl(var(--destructive));

package/dist/styles/layout.css

@@ -997,7 +997,8 @@
     flex-wrap: nowrap;
     min-width: 0;
     align-items: center;
-    justify-content: flex-end;
+
+    justify-content: safe flex-end;
     gap: var(--pagination-gap);
   }
 

package/dist/styles/navigation-layout.css

@@ -103,6 +103,11 @@
     flex: 1 1 auto;
   }
 
+  [data-slot="tabs"][data-orientation="vertical"] > [data-slot="tabs-list"],
+  [data-slot="tabs"][data-orientation="vertical"] > .ui-tabs-bar {
+    flex-shrink: 0;
+  }
+
   .ui-tabs-extra {
     display: flex;
     flex: 0 0 auto;
@@ -194,6 +199,12 @@
     block-size: var(--tabs-add-icon-size);
   }
 
+  .ui-pagination {
+    max-inline-size: 100%;
+    overflow-x: auto;
+    scrollbar-width: thin;
+  }
+
   .ui-pagination .ui-button svg,
   .ui-pagination .ui-pagination-link svg {
     inline-size: var(--pagination-icon-size);
@@ -205,11 +216,11 @@
   }
 
   .ui-pagination[data-align="center"] {
-    justify-content: center;
+    justify-content: safe center;
   }
 
   .ui-pagination[data-align="end"] {
-    justify-content: flex-end;
+    justify-content: safe flex-end;
   }
 
   .ui-pagination[data-size="sm"] {

package/dist/styles/shell-layout.css

@@ -2322,6 +2322,10 @@
   .ui-mobile-shell {
     --control-height: var(--mobile-shell-control-height);
 
+    --control-height-sm: calc(var(--control-height) - calc(0.25rem * var(--scaling)));
+    --control-height-lg: calc(var(--control-height) + calc(0.25rem * var(--scaling)));
+    --control-height-xs: calc(var(--control-height) - calc(0.5rem * var(--scaling)));
+
     --mobile-shell-padding-inline: calc(
       var(--mobile-shell-inset-inline) + var(--mobile-shell-safe-inset-inline)
     );

package/dist/styles/table-layout.css

@@ -44,8 +44,7 @@
   }
 
   .ui-table-row[data-tone] > [data-slot="table-cell"]:first-child {
-    border-inline-start: var(--table-row-tone-rail-width) solid
-      hsl(var(--table-row-tone-color));
+    border-inline-start: var(--table-row-tone-rail-width) solid hsl(var(--table-row-tone-color));
     padding-inline-start: calc(var(--table-cell-space-x) - var(--table-row-tone-rail-width));
   }
 
@@ -206,6 +205,10 @@
   }
 
   .ui-data-table-empty {
+    padding: var(--empty-state-space-y) var(--empty-state-space-x);
+  }
+
+  .ui-data-table-empty .ui-empty-state {
     padding: 0;
   }
 

package/dist/tokens/components/control.css

@@ -32,6 +32,8 @@
   --control-status-warning-glow-color: var(--warning);
   --control-status-warning-glow-alpha: var(--control-outline-error-alpha);
 
+  --number-input-touch-height: var(--band-height-2xl);
+
   --control-variant-filled-background: var(--muted);
   --control-variant-filled-hover-background: var(--accent);
 
@@ -286,6 +288,8 @@
   --calendar-footer-space-block-start: var(--space-2);
   --calendar-footer-border-width: var(--stroke-hairline);
 
+  --calendar-bordered-weekday-padding-block: var(--space-1);
+
   --transfer-pane-min-height: 14rem;
   --transfer-pane-radius: var(--radius-md);
   --transfer-panes-space-gap: var(--space-3);
@@ -317,9 +321,9 @@
   --month-picker-icon-size: var(--icon-size-md);
   --month-picker-separator-icon-size: var(--icon-size-sm);
 
-  --button-xs-height: var(--control-height-xs);
+  --button-xs-height: initial;
 
-  --button-bare-target-size: var(--control-height-xs);
+  --button-bare-target-size: initial;
   --button-xs-space-inline: var(--space-2);
   --button-xs-space-gap: var(--space-1);
   --button-xs-font-size: var(--font-size-xs);
@@ -369,7 +373,8 @@
 
   --control-status-error-border-color: hsl(var(--destructive));
   --control-status-warning-border-color: hsl(var(--text-warning));
-  --control-status-warning-outline-color: var(--warning);
+
+  --control-status-warning-outline-color: var(--text-warning);
 }
 
 @media (pointer: coarse) {

package/dist/tokens/components/navigation.css

@@ -41,6 +41,8 @@
   --tabs-list-max-inline-size: 100%;
   --tabs-list-overflow: auto;
 
+  --tabs-placement-responsive-breakpoint-width: 48rem;
+
   --tabs-indicator-background: initial;
   --tabs-indicator-size: 2px;
   --tabs-indicator-offset: 0px;

package/docs/CONSUMER-RULES.md

@@ -11,7 +11,12 @@ Read this once; the audit enforces it. Everything else in `docs/` is for contrib
 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/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/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/table.tsx

@@ -181,7 +181,7 @@ export default function Demo() {
               full frame. The suppression above is scoped to a flush body, never to `bordered`.
             </CardDescription>
           </CardHeader>
-          <CardContent>
+          <CardContent flush>
             <Table bordered>
               <TableHeader>
                 <TableRow>

package/docs/data-entry/segmented-in-filter-row.tsx

@@ -0,0 +1,77 @@
+import {
+  Badge,
+  Card,
+  CardContent,
+  CardDescription,
+  CardHeader,
+  CardTitle,
+} from "@godxjp/ui/data-display";
+import { Segmented } from "@godxjp/ui/data-entry";
+import { Button, Text } from "@godxjp/ui/general";
+import { Flex, PageContainer } from "@godxjp/ui/layout";
+
+/**
+ * The composition a consumer actually filters a list with: a Segmented that carries a count badge
+ * per option, sharing a WRAPPING flex row with the other filter controls, inside a Card.
+ *
+ * It is a separate frame from `segmented.tsx` because the row is the variable. `#four-with-counts`
+ * over there puts the track directly in a CardContent, where it is a block box and shrinks to the
+ * column; here it is a FLEX ITEM, and a flex item's `min-inline-size` defaults to `auto` — its
+ * max-content width — so nothing makes it give ground to the row.
+ */
+const OPTIONS = [
+  { value: "all", label: "すべて", count: 133 },
+  { value: "ginou", label: "技能実習", count: 82 },
+  { value: "tokutei", label: "特定技能", count: 51 },
+  { value: "ikusei", label: "育成就労", count: 0 },
+].map(({ value, label, count }) => ({
+  value,
+  label: (
+    <>
+      {label}
+      <Badge as="span" variant="secondary">
+        {count}
+      </Badge>
+    </>
+  ),
+}));
+
+export default function SegmentedInFilterRow() {
+  return (
+    <PageContainer title="Segmented in a filter row" subtitle="4 択 + 件数バッジ · Flex wrap の中">
+      <Card id="four-in-wrap-row">
+        <CardHeader>
+          <CardTitle level={2}>制度の絞り込み</CardTitle>
+          <CardDescription>
+            `check:segmented-wrap` がこのカードも測ります。トラックは行の中でも縮み、393px
+            でラベルも件数も切り詰めません。
+          </CardDescription>
+        </CardHeader>
+        <CardContent>
+          <Flex gap="sm" align="center" wrap>
+            <Segmented aria-label="制度" defaultValue="all" options={OPTIONS} />
+            <Button variant="outline" size="sm">
+              絞り込みを解除
+            </Button>
+          </Flex>
+        </CardContent>
+      </Card>
+
+      <Card id="four-in-wrap-row-alone">
+        <CardHeader>
+          <CardTitle level={2}>同じトラック、行の中に一つだけ</CardTitle>
+          <CardDescription>
+            <Text size="sm" tone="muted">
+              兄弟が無くても行は行。フレックス項目としての縮み方を切り分けるための対照。
+            </Text>
+          </CardDescription>
+        </CardHeader>
+        <CardContent>
+          <Flex gap="sm" align="center" wrap>
+            <Segmented aria-label="制度（単独）" defaultValue="all" options={OPTIONS} />
+          </Flex>
+        </CardContent>
+      </Card>
+    </PageContainer>
+  );
+}