@godxjp/ui 20.2.1 → 22.0.0

package/dist/styles/focus-ring.css

@@ -14,7 +14,6 @@
     .ui-checkbox,
     .ui-radio,
     .ui-slider-thumb,
-    .ui-switch,
     .ui-steps-inline-control,
     .ui-pagination-link,
     .ui-legal-document-toc-link,
@@ -30,6 +29,8 @@
   ):focus-visible,
 
   .ui-checkbox[data-focus-visible],
+  .ui-switch[data-focus-visible],
+  .ui-focus-ring[data-focus-visible],
   .ui-control-trigger[data-state="open"],
   .ui-tag-input:focus-within,
   .ui-control-composite-field:focus-within,
@@ -59,7 +60,6 @@
       .ui-checkbox,
       .ui-radio,
       .ui-slider-thumb,
-      .ui-switch,
       .ui-steps-inline-control,
       .ui-pagination-link,
       .ui-legal-document-toc-link,
@@ -75,6 +75,8 @@
     ):focus-visible,
 
   :root[data-focus-outline="on"] .ui-checkbox[data-focus-visible],
+  :root[data-focus-outline="on"] .ui-switch[data-focus-visible],
+  :root[data-focus-outline="on"] .ui-focus-ring[data-focus-visible],
   :root[data-focus-outline="on"] .ui-control-trigger[data-state="open"],
   :root[data-focus-outline="on"] .ui-tag-input:focus-within,
   :root[data-focus-outline="on"] .ui-control-composite-field:focus-within,

package/dist/styles/navigation-layout.css

@@ -96,6 +96,10 @@
 
   .ui-tabs-bar > [data-slot="tabs-list"] {
     min-inline-size: 0;
+    flex: 0 1 auto;
+  }
+
+  [data-slot="tabs"]:not([data-orientation="vertical"]) .ui-tabs-bar > [data-slot="tabs-list"] {
     flex: 1 1 auto;
   }
 
@@ -146,6 +150,27 @@
     block-size: var(--tabs-tab-remove-icon-size);
   }
 
+  .ui-tabs-overflow {
+    display: inline-flex;
+    flex: 0 0 auto;
+    inline-size: var(--tabs-overflow-size);
+    block-size: var(--tabs-overflow-size);
+    align-items: center;
+    justify-content: center;
+    border-radius: var(--tabs-overflow-radius);
+    color: hsl(var(--muted-foreground));
+  }
+
+  .ui-tabs-overflow:hover {
+    background: hsl(var(--accent));
+    color: hsl(var(--accent-foreground));
+  }
+
+  .ui-tabs-overflow-icon {
+    inline-size: var(--tabs-overflow-icon-size);
+    block-size: var(--tabs-overflow-icon-size);
+  }
+
   .ui-tabs-add {
     display: inline-flex;
     flex: 0 0 auto;

package/dist/styles/shell-layout.css

@@ -12,7 +12,8 @@
       "sidebar footer";
     grid-template-columns: var(--app-shell-sidebar-width) minmax(0, 1fr);
     grid-template-rows: var(--app-shell-bar-height) minmax(0, 1fr) auto;
-    height: 100vh;
+
+    height: calc(100vh - var(--app-shell-viewport-inset, 0px));
     background: hsl(var(--background));
   }
 
@@ -2331,6 +2332,11 @@
     --mobile-shell-block-size: 100%;
   }
 
+  .ui-mobile-shell[data-width="phone"] {
+    max-inline-size: var(--mobile-shell-max-inline-size);
+    margin-inline: auto;
+  }
+
   .ui-mobile-shell-chrome {
     display: flex;
     min-inline-size: 0;

package/dist/styles/table-layout.css

@@ -15,6 +15,40 @@
     border-block-end-width: 0;
   }
 
+  .ui-table-row[data-tone="primary"] {
+    --table-row-tone-color: var(--mark-primary);
+  }
+
+  .ui-table-row[data-tone="success"] {
+    --table-row-tone-color: var(--mark-success);
+  }
+
+  .ui-table-row[data-tone="warning"] {
+    --table-row-tone-color: var(--mark-warning);
+  }
+
+  .ui-table-row[data-tone="info"] {
+    --table-row-tone-color: var(--mark-info);
+  }
+
+  .ui-table-row[data-tone="attention"] {
+    --table-row-tone-color: var(--mark-attention);
+  }
+
+  .ui-table-row[data-tone="destructive"] {
+    --table-row-tone-color: var(--mark-destructive);
+  }
+
+  .ui-table-row[data-tone] {
+    background: hsl(var(--table-row-tone-color) / var(--table-row-tone-wash-alpha));
+  }
+
+  .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));
+    padding-inline-start: calc(var(--table-cell-space-x) - var(--table-row-tone-rail-width));
+  }
+
   [data-slot="table-head"] {
     height: var(--table-row-height);
     padding: var(--table-cell-padding-y) var(--table-cell-space-x);

package/dist/tokens/base.css

@@ -22,9 +22,11 @@
 @import "./components/data-display.css";
 @import "./components/scroll-area.css";
 @import "./components/list-row.css";
+@import "./components/chat-bubble.css";
 @import "./components/logo.css";
 @import "./components/email.css";
 @import "./components/data-entry.css";
+@import "./components/chat-composer.css";
 @import "./components/upload.css";
 @import "./components/shell.css";
 @import "./components/separator.css";
@@ -33,3 +35,4 @@
 @import "./components/error-surface.css";
 @import "./components/activity.css";
 @import "./components/text.css";
+@import "./components/tree.css";

package/dist/tokens/components/chat-bubble.css

@@ -0,0 +1,36 @@
+
+:root {
+
+  --chat-bubble-background: initial;
+
+  --chat-bubble-foreground: initial;
+
+  --chat-bubble-border-color: initial;
+  --chat-bubble-radius: var(--radius-lg);
+
+  --chat-bubble-gap: var(--space-3);
+
+  --chat-bubble-max-inline-size: 34rem;
+
+  --chat-bubble-avatar-size: initial;
+
+  --chat-bubble-padding-block: var(--space-2);
+  --chat-bubble-padding-inline: var(--space-3);
+
+  --chat-bubble-list-gap: var(--space-4);
+
+  --chat-bubble-list-jump-inset: var(--space-3);
+
+  --chat-bubble-typing-caret-color: initial;
+  --chat-bubble-typing-caret-width: var(--stroke-md);
+
+  --chat-bubble-typing-caret-height: 1em;
+
+  --chat-bubble-skeleton-short-inline-size: 60%;
+
+  --chat-bubble-tone-background-alpha: 0.08;
+  --chat-bubble-tone-border-alpha: 0.35;
+
+  --chat-bubble-end-background: initial;
+  --chat-bubble-end-foreground: initial;
+}

package/dist/tokens/components/chat-composer.css

@@ -0,0 +1,19 @@
+
+:root {
+
+  --chat-composer-min-height: initial;
+  --chat-composer-max-height: initial;
+
+  --chat-composer-gap: var(--space-2);
+
+  --chat-composer-padding-block: var(--space-2);
+  --chat-composer-padding-inline: var(--space-2);
+
+  --chat-composer-row-gap: var(--space-2);
+
+  --chat-composer-radius: initial;
+
+  --chat-composer-header-border: initial;
+
+  --chat-composer-footer-font-size: var(--font-size-xs);
+}

package/dist/tokens/components/data-display.css

@@ -31,9 +31,6 @@
   --prose-code-space-inline: var(--space-1);
   --prose-code-radius: var(--radius-sm);
   --prose-image-radius: var(--radius-md);
-  --tree-item-indent-width: var(--space-5);
-  --tree-item-title-font-size: var(--font-size-xs);
-  --tree-item-description-font-size: var(--font-size-xs);
   --timeline-note-font-size: var(--font-size-xs);
 
   --avatar-background: initial;
@@ -68,6 +65,15 @@
   --progress-breakdown-block-size: 1.375rem;
   --progress-breakdown-radius: var(--radius);
 
+  --progress-meter-block-size: 0.5rem;
+  --progress-meter-block-size-sm: 0.25rem;
+  --progress-breakdown-block-size-sm: 0.5rem;
+
+  --progress-ring-size: 2.75rem;
+  --progress-ring-size-sm: 2rem;
+  --progress-ring-border-width: var(--stroke-lg);
+  --progress-ring-label-font-size: var(--font-size-xs);
+
   --legend-gap: 0.875rem;
   --legend-item-gap: 0.3125rem;
   --legend-swatch-size: 0.625rem;
@@ -80,9 +86,6 @@
   --timeline-dot-current-background: initial;
   --timeline-line-completed-background: initial;
 
-  --tree-item-active-border: initial;
-  --tree-item-active-background: initial;
-
   --qr-code-foreground: 0 0% 0%;
   --qr-code-background: 0 0% 100%;
   --qr-code-size-xs: 6rem;

package/dist/tokens/components/descriptions.css

@@ -14,6 +14,10 @@
 
   --descriptions-value-line-height: calc(1.25 / 0.875);
 
+  --descriptions-label-font-size: var(--descriptions-value-font-size);
+
+  --descriptions-label-line-height: var(--descriptions-value-line-height);
+
   --descriptions-row-border: none;
   --descriptions-row-min-height: auto;
 

package/dist/tokens/components/navigation.css

@@ -49,6 +49,8 @@
 
   --tabs-list-line-space-inset: 0px;
 
+  --tabs-list-line-space-gap: 0.25rem;
+
   --tabs-list-focus-ring-space-inset: initial;
 
   --tabs-trigger-line-radius: 0px;
@@ -74,6 +76,10 @@
 
   --tabs-bar-gap: var(--space-2);
   --tabs-extra-gap: var(--space-2);
+
+  --tabs-overflow-size: var(--band-height-md);
+  --tabs-overflow-radius: var(--radius-md);
+  --tabs-overflow-icon-size: var(--control-icon-size);
   --tabs-add-size: var(--band-height-md);
   --tabs-add-radius: var(--radius-md);
   --tabs-add-icon-size: var(--control-icon-size);

package/dist/tokens/components/segmented.css

@@ -9,8 +9,6 @@
   --segmented-track-radius: var(--radius);
   --segmented-item-radius: var(--radius-md);
 
-  --segmented-item-height: calc(var(--control-height) - var(--segmented-track-padding) * 2);
-
   --segmented-item-padding-inline: calc(var(--control-padding-x) - 1px);
 
   --segmented-item-gap: calc(var(--space-3) / 2);

package/dist/tokens/components/shell.css

@@ -36,6 +36,7 @@
   --sidebar-gradient: none;
   --topbar-gradient: none;
 
+  --app-shell-viewport-inset: 0px;
   --app-shell-bar-height: var(--band-height-2xl);
 
   --app-shell-bar-inset: var(--space-page-x);
@@ -354,6 +355,8 @@
 
 :root {
   --mobile-shell-block-size: 100dvh;
+
+  --mobile-shell-max-inline-size: 26.875rem;
   --mobile-shell-safe-inset-block-start: env(safe-area-inset-top);
   --mobile-shell-safe-inset-block-end: env(safe-area-inset-bottom);
   --mobile-shell-safe-inset-inline: max(env(safe-area-inset-left), env(safe-area-inset-right));

package/dist/tokens/components/table.css

@@ -91,4 +91,7 @@
   --table-row-border-width: var(--stroke-hairline);
 
   --table-flush-divider-width: var(--table-row-border-width);
+
+  --table-row-tone-rail-width: var(--stroke-2xl);
+  --table-row-tone-wash-alpha: 0.06;
 }

package/dist/tokens/components/tree.css

@@ -0,0 +1,27 @@
+
+
+:root {
+
+  --tree-node-height: initial;
+
+  --tree-indent-width: var(--space-5);
+
+  --tree-node-padding-inline: var(--space-2);
+  --tree-node-gap: var(--space-2);
+  --tree-node-radius: var(--radius-sm);
+  --tree-node-font-size: var(--font-size-sm);
+
+  --tree-switcher-size: 1.25rem;
+
+  --tree-switcher-color: initial;
+
+  --tree-icon-size: var(--icon-size-md);
+
+  --tree-line-color: initial;
+
+  --tree-node-hover-background: initial;
+  --tree-node-selected-background: initial;
+  --tree-node-selected-foreground: initial;
+
+  --tree-loading-bar-inline-size: 40%;
+}

package/dist/tokens/foundation.css

@@ -47,6 +47,13 @@
   --text-info: 221 70% 38%;
   --text-error: 357 75% 38%;
 
+  --mark-primary: var(--text-primary);
+  --mark-success: var(--text-success);
+  --mark-warning: var(--text-warning);
+  --mark-info: var(--text-info);
+  --mark-destructive: var(--text-error);
+  --mark-attention: var(--attention);
+
   --secondary-hover: 45 15% 91%;
   --secondary-active: 45 15% 88%;
 

package/docs/COMPONENTS.md

@@ -48,8 +48,8 @@ All UI is **mobile-first**: base layout targets ~320–428px viewport; `sm` (640
 
 Default `direction="row"`; use `direction="col"` for vertical rhythm.
 
-| Component | Prop       | Key props                                                                                            |
-| --------- | ---------- | ---------------------------------------------------------------------------------------------------- |
+| Component | Prop       | Key props                                                                                                           |
+| --------- | ---------- | ------------------------------------------------------------------------------------------------------------------- |
 | `Flex`    | `FlexProp` | `direction: "row" \| "col"`, `gap: GapProp`, `gapRaw`, `pad`, `padRaw`, `fill`, `width`, `align`, `justify`, `wrap` |
 
 `fill` / `width` are the `fixed | elastic | fixed` row: `width` pins a column (number = px, and
@@ -82,25 +82,25 @@ and sets `min-inline-size: 0` so a truncating child ellipses instead of widening
 | `Textarea`    | `TextareaProp`    | extends native textarea                            |
 | `FormField`   | `FormFieldProp`   | `id`, `label`, `required`, `helper`, `error`       |
 | `SearchInput` | `SearchInputProp` | `onSearchChange: OnSearchChangeProp`               |
-| `Checkbox`    | `CheckboxProp`    | Radix checkbox; `Checkbox.Group` với `options`     |
+| `Checkbox`    | `CheckboxProp`    | Checkbox (RAC); `Checkbox.Group` với `options`     |
 | `Radio`       | `RadioGroupProp`  | `Radio.Group` single-select; `Radio.Root` compound |
 
 ---
 
 ## Data Display
 
-| Component      | Prop type          | Key props                                |
-| -------------- | ------------------ | ---------------------------------------- |
-| `EmptyState`   | `EmptyStateProp`   | `icon`, `title`, `description`, `action` |
-| `DataTable`    | `DataTableProp<T>` | `columns`, `density: TableDensityProp`   |
-| `Descriptions` | `DescriptionsProp` | `items[]`                                |
-| `Badge`        | `BadgeProp`        | `status`, `tone: ToneProp`               |
-| `Badge`        | `BadgeProp`        | shadcn badge variants                    |
+| Component      | Prop type          | Key props                                 |
+| -------------- | ------------------ | ----------------------------------------- |
+| `EmptyState`   | `EmptyStateProp`   | `icon`, `title`, `description`, `action`  |
+| `DataTable`    | `DataTableProp<T>` | `columns`, `density: TableDensityProp`    |
+| `Descriptions` | `DescriptionsProp` | `items[]`                                 |
+| `Badge`        | `BadgeProp`        | `status`, `tone: ToneProp`                |
+| `Badge`        | `BadgeProp`        | shadcn badge variants                     |
 | `Progress`     | `ProgressProp`     | `value` (meter) \| `segments` (breakdown) |
-| `Legend`       | `LegendProp`       | `items[]` — the key for a tone           |
-| `Popover`      | Radix primitives   | floating content panel                   |
-| `ScrollArea`   | Radix primitives   | scrollable regions                       |
-| `Collapsible`  | Radix primitives   | expand/collapse sections                 |
+| `Legend`       | `LegendProp`       | `items[]` — the key for a tone            |
+| `Popover`      | Radix primitives   | floating content panel                    |
+| `ScrollArea`   | Radix primitives   | scrollable regions                        |
+| `Collapsible`  | Radix primitives   | expand/collapse sections                  |
 
 ---
 

package/docs/CONSUMER-RULES.md

@@ -6,7 +6,7 @@ Read this once; the audit enforces it. Everything else in `docs/` is for contrib
 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`.
-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"`.
+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]`.
@@ -25,3 +25,26 @@ const legacyClasses = ["gap-3", "p-2"];
 ```
 
 A block with no reason (or under 12 characters of it) is ignored and the finding stands; an unclosed block runs to the end of the file. The class-shaped rules (`gap-*`, `bg-red-500`, `w-[37px]`, `pr-*`, `dark:*`) only read class expressions — a `className`/`class` attribute, a class-named binding (`baseClass`, `statusStyles`, `badgeVariants`) or a `cn()`/`clsx()`/`cva()` call — so product copy or an i18n value that happens to spell a utility is never a finding.
+
+---
+
+## Why a disabled control's reason cannot be a tooltip
+
+A disabled `<button>` receives no pointer events and is not in the tab order, so an explanation
+attached to it never reaches anyone. Measured in Chromium on this package's own tooltip page: the
+same trigger produced **1** tooltip on hover while enabled and **0** while disabled, and calling
+`focus()` on it left `document.activeElement` as `BODY` — so keyboard and touch get nothing either.
+Hover-only would fail a touch user in any case.
+
+This is not a gap waiting for a DS prop. The reason is required information, and required
+information belongs on the screen:
+
+- Render it as a `<Text size="xs" tone="muted">` line **before** the control, so a screen-reader or
+  keyboard user meets the explanation ahead of the thing they cannot use (WCAG 2.2 · 1.3.2,
+  meaningful sequence).
+- `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
+explaining on submit: an inert control with a paragraph beside it is often a validation message
+wearing a disguise.

package/docs/FRAME-COVERAGE-LEDGER.md

@@ -112,7 +112,7 @@ The executed geometry sweep (`pnpm check:frame-geometry`, `scripts/frame-geometr
 
 ## Known gaps
 
-The issue's "Initial known gaps to encode" are locked in code (`KNOWN_GAPS` in `scripts/frame-coverage-contract.mjs`) and mirrored into `policy.knownGaps`: Button, Card, Card subcomponents, EmptyState, Progress, Carousel, DataTable, Charts and the Timeline/TreeList/PasswordStrength locale stress. They cannot be deleted, and they cannot be waived through `policy.notApplicable` — they must be **covered** or stay **UNTESTED**.
+The issue's "Initial known gaps to encode" are locked in code (`KNOWN_GAPS` in `scripts/frame-coverage-contract.mjs`) and mirrored into `policy.knownGaps`: Button, Card, Card subcomponents, EmptyState, Progress, Carousel, DataTable, Charts and the Timeline/PasswordStrength locale stress. They cannot be deleted, and they cannot be waived through `policy.notApplicable` — they must be **covered** or stay **UNTESTED**.
 
 ## Current state — read this before quoting coverage
 

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: **137**
-- With ≥1 frame: **133** · zero-frame: **4**
+- Public components: **138**
+- With ≥1 frame: **133** · zero-frame: **5**
 - Fully covered (every contract axis declared): **0**
 
 ## UNTESTED — no `/frame/**` route
@@ -13,6 +13,7 @@
 - [ ] `CardBar`
 - [ ] `VisuallyHidden`
 - [ ] `RangeTimeline`
+- [ ] `ChatBubbleList`
 
 ## Per-component contract axes
 
@@ -59,7 +60,7 @@ Legend: ✓ covered · N/A reasoned skip · · UNTESTED (blank cell = UNTESTED).
 | QrCode | ✓ | ✓ | N/A | · | · | · | · | · | · | · |
 | Descriptions | ✓ | N/A | N/A | N/A | · | · | · | · | · | · |
 | EmptyState | ✓ | ✓ | N/A | N/A | · | · | · | · | · | · |
-| Progress | ✓ | ✓ | N/A | · | · | · | · | · | · | · |
+| Progress | ✓ | · | N/A | · | · | · | · | · | · | · |
 | CodeBlock | ✓ | · | N/A | N/A | · | · | · | · | · | · |
 | Prose | ✓ | · | N/A | N/A | · | · | · | · | · | · |
 | Timeline | ✓ | ✓ | N/A | N/A | · | · | · | · | · | · |
@@ -79,8 +80,6 @@ Legend: ✓ covered · N/A reasoned skip · · UNTESTED (blank cell = UNTESTED).
 | Label | ✓ | N/A | N/A | N/A | · | · | · | · | · | · |
 | Checkbox | ✓ | N/A | · | · | · | · | · | · | · | · |
 | RadioGroup | ✓ | N/A | · | · | · | · | · | · | · | · |
-| MonthPicker | ✓ | · | · | · | · | · | · | · | · | · |
-| MonthRangePicker | ✓ | · | · | · | · | · | · | · | · | · |
 | DatePicker | ✓ | · | · | · | · | · | · | · | · | · |
 | Dialog | ✓ | N/A | N/A | · | · | · | · | · | · | · |
 | AlertDialog | ✓ | ✓ | · | · | · | · | · | · | · | · |
@@ -98,7 +97,6 @@ Legend: ✓ covered · N/A reasoned skip · · UNTESTED (blank cell = UNTESTED).
 | AppProvider | ✓ | · | · | · | · | · | · | · | · | · |
 | formatDate | ✓ | · | · | · | · | · | · | · | · | · |
 | TimePicker | ✓ | · | · | · | · | · | · | · | · | · |
-| DateRangePicker | ✓ | · | · | · | · | · | · | · | · | · |
 | Cascader | ✓ | ✓ | · | · | · | · | · | · | · | · |
 | TreeSelect | ✓ | ✓ | · | · | · | · | · | · | · | · |
 | Transfer | ✓ | N/A | · | · | · | · | · | · | · | · |
@@ -113,7 +111,7 @@ Legend: ✓ covered · N/A reasoned skip · · UNTESTED (blank cell = UNTESTED).
 | Popover | ✓ | N/A | N/A | · | · | · | · | · | · | · |
 | ScrollArea | ✓ | N/A | N/A | N/A | · | · | · | · | · | · |
 | Collapsible | ✓ | N/A | · | · | · | · | · | · | · | · |
-| TreeList | ✓ | N/A | N/A | N/A | · | · | · | · | · | · |
+| Tree | ✓ | · | · | · | · | · | · | · | · | · |
 | Tooltip | ✓ | N/A | N/A | · | · | · | · | · | · | · |
 | PrefetchLink | ✓ | N/A | N/A | N/A | · | · | · | · | · | · |
 | Avatar | ✓ | ✓ | N/A | N/A | · | · | · | · | · | · |
@@ -157,4 +155,8 @@ Legend: ✓ covered · N/A reasoned skip · · UNTESTED (blank cell = UNTESTED).
 | PermissionMatrix | ✓ | N/A | · | N/A | · | · | · | · | · | · |
 | BranchScopePicker | ✓ | N/A | · | · | · | · | · | · | · | · |
 | ServiceRolePanel | ✓ | N/A | · | · | · | · | · | · | · | · |
+| ChatBubble | ✓ | · | · | N/A | · | · | · | · | · | · |
+| ChatBubbleList | **✗** | N/A | N/A | N/A | · | · | · | · | · | · |
+| ChatComposer | ✓ | · | · | · | · | · | · | · | · | · |
+| ChatSuggestion | ✓ | N/A | N/A | · | · | · | · | · | · | · |
 

package/docs/TOKENS.md

@@ -44,6 +44,71 @@ src/styles/
 
 Default brand tokens use the GodX Agent Portal palette: navy primary, 朱 orange focus/accent, warm neutral surfaces. App or customer identity colors belong in the consuming app theme, not in package tokens.
 
+#### The three tone tiers — FILL, TEXT, MARK
+
+A status tone can be painted three ways, and each way is judged against a different thing. Reading
+the wrong tier is this palette's most expensive recurring bug, because nothing about it looks wrong
+in the source.
+
+| Tier     | Tokens                                      | What it paints                                                     | Contrast bar                                              |
+| -------- | ------------------------------------------- | ------------------------------------------------------------------ | --------------------------------------------------------- |
+| **FILL** | `--success`, `--warning`, `--info`, `--destructive` | A solid chip, band or bar with a label ON it                        | AA **4.5:1** against its own `*-foreground` label          |
+| **TEXT** | `--text-success`, `--text-warning`, `--text-info`, `--text-error` | Small coloured type — a StatCard delta, an outline badge label      | AA **4.5:1** against the surface BEHIND it                 |
+| **MARK** | `--mark-success`, `--mark-warning`, `--mark-info`, `--mark-destructive`, `--mark-primary`, `--mark-attention` | A thin shape carrying meaning with nothing written on it — a `Card accent` rail, a `DataTable rowTone` rail | SC 1.4.11 **3:1** against the surface it sits on |
+
+The MARK tier exists because both rails were reading FILL, and two of them were effectively
+invisible. Measured in Chromium on the light card: `Card accent="warning"` drew its 6px rail at
+**1.74:1**, `accent="success"` at **2.18:1**. `--warning` is a bright 山吹 tuned to carry dark text
+on top of it; on a near-white card it is barely a colour at all.
+
+`--mark-*` resolve THROUGH the TEXT tier rather than restating its numbers, so a theme retunes one
+place and both follow — and since 3:1 is looser than 4.5:1, anything legible as text is legible as
+a mark by construction. `--mark-attention` is the exception: there is no `--text-attention`, and
+the fill already clears the floor in both themes (3.32 / 6.75).
+
+Two guards, because one was not enough:
+`src/tokens/__tests__/tone-mark-contrast.test.ts` recomputes every tone × ground × theme off the
+committed tokens and reads the alias out of the CSS (so repointing a mark back at FILL fails the
+ratio, not just a name check); and `check:contrast` grew a **rail pass** — its graphic pass only
+ever measured elements ≤24px on both axes, and a rail is 6px by the full height of a card, so no
+gate had ever looked at one.
+
+**Progress and Legend joined the tier, and the wa-iro question is settled.** `.ui-legend-swatch`,
+`.ui-progress-bar` and `.ui-progress-segment` all read FILL as standalone graphics and all failed
+the same floor. The floor applies: nothing is written on a progress fill, so *where the colour
+stops* is the entire datum, and a slice of a partition carries its share of the whole with no words
+on it — that is precisely a "graphical object required to understand the content". The hue loses.
+The two moved together because a swatch is a SAMPLE of the bar beside it; a key that is not the
+colour it is a key to is not a key.
+
+| surface | tone | ground | FILL (before) | MARK (after) |
+| --- | --- | --- | --- | --- |
+| `.ui-legend-swatch` | warning | light card | **1.74** | **5.90** |
+| `.ui-legend-swatch` | success | light card | **2.18** | **6.84** |
+| `.ui-legend-swatch` | destructive | dark card | **2.95** | **5.52** |
+| `.ui-progress-segment` | warning | light track | **1.60** | **5.41** |
+| `.ui-progress-segment` | success | light track | **2.00** | **6.28** |
+| `.ui-progress-segment` | destructive | dark track | **2.42** | **4.52** |
+
+Worst case anywhere on the two routes after the move: **4.52:1**. `.ui-progress-bar` (meter and
+over-capacity) reads the same tokens as the slice, so a `tone="warning"` meter and a `warning`
+slice on one screen stay the same colour.
+
+**A theme that repoints `--secondary` owes `--progress-track-background`.** The track defaults to
+`hsl(var(--secondary))`, which is a pale neutral in the stock palette. `docs/showcase/acme-portal`
+repurposes `--secondary` as a navy *button* colour, so its bars were drawn on a near-black track
+and the mark fills measured 2.50 (success) / 2.90 (warning) on it. Naming the track explicitly is
+the fix — 6.49 / 5.59 after — not dragging the tier back.
+
+Three guards now, and each sees something the others cannot: the ratio tests in
+`tone-mark-contrast.test.ts` (rails against card/background, progress marks against the track);
+the *same file's* CSS-alias assertions, which fail if a rule is repointed at the fill tier and
+which also pin the swatch and the slice to the **same** token per tone; and `check:contrast`'s
+**thin fill** pass — added because adding `/isolate/data-display-progress` to that gate's route
+list on its own changed nothing at all. The graphic pass wants ≤24px on both axes and the rail
+pass wants a one-sided border; a progress fill is 8px (meter) or 22px (slice) tall by whatever
+width its share makes it, so the sweep printed "AA clean" over a bar sitting at 1.60:1.
+
 #### `--border` vs `--input` — decorative chrome vs control boundary (gh#315)
 
 These two look like synonyms and are not. Keep them apart:

package/docs/data-display/badge.tsx

@@ -262,6 +262,43 @@ export default function Demo() {
           </CardContent>
         </Card>
 
+        <Card>
+          <CardHeader>
+            <CardTitle level={2}>tabular · 数字を桁で揃える</CardTitle>
+            <CardDescription>
+              件数のチップが縦に並ぶときは tabular を。プロポーショナル数字だと 1 が 0
+              より狭いので、列で見たときに桁がずれてチップ幅も揺れます。既定はオフ — 語を載せる
+              チップまで幅の広い数字を払う必要はありません。
+            </CardDescription>
+          </CardHeader>
+          <CardContent>
+            <Flex direction="row" gap="lg">
+              <Flex direction="col" align="start" gap="xs">
+                <Text size="xs" tone="muted">
+                  既定（比例数字）
+                </Text>
+                <Badge tone="info">11</Badge>
+                <Badge tone="info">100</Badge>
+                <Badge tone="warning">1811</Badge>
+              </Flex>
+              <Flex direction="col" align="start" gap="xs">
+                <Text size="xs" tone="muted">
+                  tabular
+                </Text>
+                <Badge tone="info" tabular>
+                  11
+                </Badge>
+                <Badge tone="info" tabular>
+                  100
+                </Badge>
+                <Badge tone="warning" tabular>
+                  1811
+                </Badge>
+              </Flex>
+            </Flex>
+          </CardContent>
+        </Card>
+
         <Card>
           <CardHeader>
             <CardTitle level={2}>Icon overrides</CardTitle>