@godxjp/ui 21.0.0 → 23.0.0

package/dist/styles/shell-layout.css

@@ -17,116 +17,118 @@
     background: hsl(var(--background));
   }
 
-  .app-root[data-collapsed="true"] {
-    grid-template-columns: var(--app-shell-sidebar-collapsed-width) minmax(0, 1fr);
-  }
+  @media (width > 56.25rem) {
+    .app-root[data-collapsed="true"] {
+      grid-template-columns: var(--app-shell-sidebar-collapsed-width) minmax(0, 1fr);
+    }
 
-  .app-root[data-topbar-span="full"] {
-    grid-template-areas:
-      "topbar topbar"
-      "sidebar main"
-      "sidebar footer";
-  }
+    .app-root[data-topbar-span="full"] {
+      grid-template-areas:
+        "topbar topbar"
+        "sidebar main"
+        "sidebar footer";
+    }
 
-  .app-root[data-nav-rail][data-nav-rail-position="start"] {
-    grid-template-areas:
-      "navrail sidebar topbar"
-      "navrail sidebar main"
-      "navrail sidebar footer";
-    grid-template-columns:
-      var(--app-shell-nav-rail-width)
-      var(--app-shell-sidebar-width)
-      minmax(0, 1fr);
-  }
+    .app-root[data-nav-rail][data-nav-rail-position="start"] {
+      grid-template-areas:
+        "navrail sidebar topbar"
+        "navrail sidebar main"
+        "navrail sidebar footer";
+      grid-template-columns:
+        var(--app-shell-nav-rail-width)
+        var(--app-shell-sidebar-width)
+        minmax(0, 1fr);
+    }
 
-  .app-root[data-nav-rail][data-nav-rail-position="start"][data-topbar-span="full"] {
-    grid-template-areas:
-      "topbar  topbar  topbar"
-      "navrail sidebar main"
-      "navrail sidebar footer";
-  }
+    .app-root[data-nav-rail][data-nav-rail-position="start"][data-topbar-span="full"] {
+      grid-template-areas:
+        "topbar  topbar  topbar"
+        "navrail sidebar main"
+        "navrail sidebar footer";
+    }
 
-  .app-root[data-nav-rail][data-nav-rail-position="end"] {
-    grid-template-areas:
-      "sidebar topbar  navrail"
-      "sidebar main    navrail"
-      "sidebar footer  navrail";
-    grid-template-columns:
-      var(--app-shell-sidebar-width)
-      minmax(0, 1fr)
-      var(--app-shell-nav-rail-width);
-  }
+    .app-root[data-nav-rail][data-nav-rail-position="end"] {
+      grid-template-areas:
+        "sidebar topbar  navrail"
+        "sidebar main    navrail"
+        "sidebar footer  navrail";
+      grid-template-columns:
+        var(--app-shell-sidebar-width)
+        minmax(0, 1fr)
+        var(--app-shell-nav-rail-width);
+    }
 
-  .app-root[data-nav-rail][data-nav-rail-position="end"][data-topbar-span="full"] {
-    grid-template-areas:
-      "topbar  topbar  topbar"
-      "sidebar main    navrail"
-      "sidebar footer  navrail";
-  }
+    .app-root[data-nav-rail][data-nav-rail-position="end"][data-topbar-span="full"] {
+      grid-template-areas:
+        "topbar  topbar  topbar"
+        "sidebar main    navrail"
+        "sidebar footer  navrail";
+    }
 
-  .app-root[data-nav-rail][data-nav-rail-position="top"] {
-    grid-template-areas:
-      "navrail navrail"
-      "sidebar topbar"
-      "sidebar main"
-      "sidebar footer";
-    grid-template-columns: var(--app-shell-sidebar-width) minmax(0, 1fr);
-    grid-template-rows:
-      var(--app-shell-nav-rail-height)
-      var(--app-shell-bar-height)
-      minmax(0, 1fr)
-      auto;
-  }
+    .app-root[data-nav-rail][data-nav-rail-position="top"] {
+      grid-template-areas:
+        "navrail navrail"
+        "sidebar topbar"
+        "sidebar main"
+        "sidebar footer";
+      grid-template-columns: var(--app-shell-sidebar-width) minmax(0, 1fr);
+      grid-template-rows:
+        var(--app-shell-nav-rail-height)
+        var(--app-shell-bar-height)
+        minmax(0, 1fr)
+        auto;
+    }
 
-  .app-root[data-nav-rail][data-nav-rail-position="top"][data-topbar-span="full"] {
-    grid-template-areas:
-      "navrail navrail"
-      "topbar  topbar"
-      "sidebar main"
-      "sidebar footer";
-  }
+    .app-root[data-nav-rail][data-nav-rail-position="top"][data-topbar-span="full"] {
+      grid-template-areas:
+        "navrail navrail"
+        "topbar  topbar"
+        "sidebar main"
+        "sidebar footer";
+    }
 
-  .app-root[data-nav-rail][data-nav-rail-position="bottom"] {
-    grid-template-areas:
-      "sidebar topbar"
-      "sidebar main"
-      "sidebar footer"
-      "navrail navrail";
-    grid-template-columns: var(--app-shell-sidebar-width) minmax(0, 1fr);
-    grid-template-rows:
-      var(--app-shell-bar-height)
-      minmax(0, 1fr)
-      auto
-      var(--app-shell-nav-rail-height);
-  }
+    .app-root[data-nav-rail][data-nav-rail-position="bottom"] {
+      grid-template-areas:
+        "sidebar topbar"
+        "sidebar main"
+        "sidebar footer"
+        "navrail navrail";
+      grid-template-columns: var(--app-shell-sidebar-width) minmax(0, 1fr);
+      grid-template-rows:
+        var(--app-shell-bar-height)
+        minmax(0, 1fr)
+        auto
+        var(--app-shell-nav-rail-height);
+    }
 
-  .app-root[data-nav-rail][data-nav-rail-position="bottom"][data-topbar-span="full"] {
-    grid-template-areas:
-      "topbar  topbar"
-      "sidebar main"
-      "sidebar footer"
-      "navrail navrail";
-  }
+    .app-root[data-nav-rail][data-nav-rail-position="bottom"][data-topbar-span="full"] {
+      grid-template-areas:
+        "topbar  topbar"
+        "sidebar main"
+        "sidebar footer"
+        "navrail navrail";
+    }
 
-  .app-root[data-nav-rail][data-nav-rail-position="start"][data-collapsed="true"] {
-    grid-template-columns:
-      var(--app-shell-nav-rail-width)
-      var(--app-shell-sidebar-collapsed-width)
-      minmax(0, 1fr);
-  }
+    .app-root[data-nav-rail][data-nav-rail-position="start"][data-collapsed="true"] {
+      grid-template-columns:
+        var(--app-shell-nav-rail-width)
+        var(--app-shell-sidebar-collapsed-width)
+        minmax(0, 1fr);
+    }
 
-  .app-root[data-nav-rail][data-nav-rail-position="end"][data-collapsed="true"] {
-    grid-template-columns:
-      var(--app-shell-sidebar-collapsed-width)
-      minmax(0, 1fr)
-      var(--app-shell-nav-rail-width);
-  }
+    .app-root[data-nav-rail][data-nav-rail-position="end"][data-collapsed="true"] {
+      grid-template-columns:
+        var(--app-shell-sidebar-collapsed-width)
+        minmax(0, 1fr)
+        var(--app-shell-nav-rail-width);
+    }
 
-  .app-root[data-nav-rail]:is(
-      [data-nav-rail-position="top"],
-      [data-nav-rail-position="bottom"]
-    )[data-collapsed="true"] {
-    grid-template-columns: var(--app-shell-sidebar-collapsed-width) minmax(0, 1fr);
+    .app-root[data-nav-rail]:is(
+        [data-nav-rail-position="top"],
+        [data-nav-rail-position="bottom"]
+      )[data-collapsed="true"] {
+      grid-template-columns: var(--app-shell-sidebar-collapsed-width) minmax(0, 1fr);
+    }
   }
 
   .app-root[data-topbar="none"] {
@@ -817,51 +819,54 @@
     font-size: var(--font-size-base);
   }
 
-  .app-root:where([data-sidebar="none"])[data-nav-rail][data-nav-rail-position="start"] {
-    grid-template-columns: var(--app-shell-nav-rail-width) minmax(0, 1fr);
-    grid-template-areas: "navrail topbar" "navrail main" "navrail footer";
-  }
-  .app-root:where([data-sidebar="none"])[data-nav-rail][data-nav-rail-position="start"][data-topbar-span="full"] {
-    grid-template-areas: "topbar topbar" "navrail main" "navrail footer";
-  }
-  .app-root:where([data-sidebar="none"])[data-nav-rail][data-nav-rail-position="end"] {
-    grid-template-columns: minmax(0, 1fr) var(--app-shell-nav-rail-width);
-    grid-template-areas: "topbar navrail" "main navrail" "footer navrail";
-  }
-  .app-root:where([data-sidebar="none"])[data-nav-rail][data-nav-rail-position="end"][data-topbar-span="full"] {
-    grid-template-areas: "topbar topbar" "main navrail" "footer navrail";
-  }
+  @media (width > 56.25rem) {
+    .app-root:where([data-sidebar="none"])[data-nav-rail][data-nav-rail-position="start"] {
+      grid-template-columns: var(--app-shell-nav-rail-width) minmax(0, 1fr);
+      grid-template-areas: "navrail topbar" "navrail main" "navrail footer";
+    }
+    .app-root:where([data-sidebar="none"])[data-nav-rail][data-nav-rail-position="start"][data-topbar-span="full"] {
+      grid-template-areas: "topbar topbar" "navrail main" "navrail footer";
+    }
+    .app-root:where([data-sidebar="none"])[data-nav-rail][data-nav-rail-position="end"] {
+      grid-template-columns: minmax(0, 1fr) var(--app-shell-nav-rail-width);
+      grid-template-areas: "topbar navrail" "main navrail" "footer navrail";
+    }
+    .app-root:where([data-sidebar="none"])[data-nav-rail][data-nav-rail-position="end"][data-topbar-span="full"] {
+      grid-template-areas: "topbar topbar" "main navrail" "footer navrail";
+    }
 
-  .app-root:where([data-sidebar="none"])[data-nav-rail][data-nav-rail-position="top"] {
-    grid-template-columns: minmax(0, 1fr);
-    grid-template-areas: "navrail" "topbar" "main" "footer";
-    grid-template-rows:
-      var(--app-shell-nav-rail-height)
-      var(--app-shell-bar-height)
-      minmax(0, 1fr)
-      auto;
-  }
-  .app-root:where([data-sidebar="none"])[data-nav-rail][data-nav-rail-position="top"][data-topbar-span="full"] {
-    grid-template-areas: "navrail" "topbar" "main" "footer";
-  }
-  .app-root:where([data-sidebar="none"])[data-nav-rail]:is(
-      [data-nav-rail-position="bottom"]
-    ) {
-    grid-template-columns: minmax(0, 1fr);
-    grid-template-areas: "topbar" "main" "footer" "navrail";
-    grid-template-rows:
-      var(--app-shell-bar-height)
-      minmax(0, 1fr)
-      auto
-      var(--app-shell-nav-rail-height);
+    .app-root:where([data-sidebar="none"])[data-nav-rail][data-nav-rail-position="top"] {
+      grid-template-columns: minmax(0, 1fr);
+      grid-template-areas: "navrail" "topbar" "main" "footer";
+      grid-template-rows:
+        var(--app-shell-nav-rail-height)
+        var(--app-shell-bar-height)
+        minmax(0, 1fr)
+        auto;
+    }
+    .app-root:where([data-sidebar="none"])[data-nav-rail][data-nav-rail-position="top"][data-topbar-span="full"] {
+      grid-template-areas: "navrail" "topbar" "main" "footer";
+    }
+    .app-root:where([data-sidebar="none"])[data-nav-rail]:is(
+        [data-nav-rail-position="bottom"]
+      ) {
+      grid-template-columns: minmax(0, 1fr);
+      grid-template-areas: "topbar" "main" "footer" "navrail";
+      grid-template-rows:
+        var(--app-shell-bar-height)
+        minmax(0, 1fr)
+        auto
+        var(--app-shell-nav-rail-height);
+    }
+
+    .app-root:where([data-sidebar="none"])[data-nav-rail][data-nav-rail-position="bottom"][data-topbar-span="full"] {
+      grid-template-areas: "topbar" "main" "footer" "navrail";
+    }
   }
 
   @media (width <= 56.25rem) {
-    .app-root,
-    .app-root[data-collapsed="true"],
-    .app-root[data-nav-rail],
-    .app-root[data-nav-rail][data-collapsed="true"],
-    .app-root[data-nav-rail][data-topbar-span="full"] {
+
+    .app-root {
       grid-template-areas:
         "topbar"
         "main"
@@ -2332,6 +2337,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);
@@ -154,7 +188,7 @@
 
     overflow: clip;
 
-    min-inline-size: var(--table-surface-min-inline-size);
+    min-inline-size: min-content;
     border: 1px solid hsl(var(--border));
     border-radius: var(--radius-md);
   }
@@ -163,6 +197,10 @@
     min-inline-size: 0;
   }
 
+  .ui-data-table-surface:not([data-preset]) > * > [data-slot="table"] {
+    min-inline-size: var(--table-surface-min-inline-size);
+  }
+
   .ui-data-table-surface[data-striped] tbody tr:nth-child(even):not([data-state="selected"]) {
     background-color: var(--table-row-striped-background, hsl(var(--muted) / 0.4));
   }
@@ -252,7 +290,7 @@
       inset-inline-end: 0;
     }
 
-    .ui-data-table-surface {
+    .ui-data-table-surface:not([data-preset]) > * > [data-slot="table"] {
       min-inline-size: 0;
     }
   }
@@ -322,7 +360,7 @@
     max-block-size: var(--table-scroll-block-size, none);
   }
 
-  .ui-data-table-scroll[data-scroll-x] :is(.ui-data-table-surface, [data-slot="table"]) {
+  .ui-data-table-scroll[data-scroll-x] [data-slot="table"] {
     min-inline-size: var(--table-scroll-inline-size, auto);
   }
 

package/dist/tokens/components/control.css

@@ -105,6 +105,8 @@
   --slider-track-height: 0.375rem;
   --slider-thumb-size: 1rem;
 
+  --slider-vertical-min-block-size: 10rem;
+
   --otp-slot-size: initial;
 
   --otp-slot-inline-size: initial;
@@ -198,6 +200,8 @@
   --search-select-panel-inline-size: auto;
   --search-select-panel-viewport-inset: var(--space-6);
   --search-select-list-space-inset: var(--space-1);
+
+  --search-select-list-max-height: none;
   --search-select-footer-space-inset: var(--space-1);
   --search-select-option-space-gap: var(--space-2);
   --search-select-option-font-size: var(--font-size-sm);

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

@@ -65,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;
@@ -84,11 +93,6 @@
   --qr-code-size-md: 10rem;
   --qr-code-size-lg: 12.5rem;
 
-  --scroll-area-bar-size: 0.625rem;
-
-  --scroll-area-bar-padding: 1px;
-  --scroll-area-thumb-radius: var(--radius-pill);
-
   --timeline-grid-hour-height: 2.5rem;
   --timeline-grid-axis-width: 3.25rem;
   --timeline-grid-column-min-width: 6rem;

package/dist/tokens/components/navigation.css

@@ -37,7 +37,7 @@
   --breadcrumb-font-size: var(--font-size-xs);
 
   --breadcrumb-menu-trigger-gap: var(--space-inline-xs);
-  --menubar-shortcut-font-size: var(--font-size-xs);
+  --menu-shortcut-font-size: var(--font-size-xs);
   --tabs-list-max-inline-size: 100%;
   --tabs-list-overflow: auto;
 
@@ -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);
@@ -83,8 +89,8 @@
   --tabs-tab-remove-icon-size: var(--icon-size-xs);
   --tabs-tab-remove-space-inline-end: var(--space-1);
 
-  --menubar-item-hover-background: initial;
-  --menubar-item-hover-foreground: initial;
+  --menu-item-hover-background: initial;
+  --menu-item-hover-foreground: initial;
 
   --filter-bar-sticky-offset: 0px;
 
@@ -122,8 +128,6 @@
   --menu-separator-space-block: var(--space-1);
   --menu-separator-space-inline: calc(var(--space-1) * -1);
 
-  --navigation-menu-trigger-icon-size: var(--icon-size-sm);
-
   --steps-dot-size: 0.625rem;
   --steps-dot-process-ring-width: var(--stroke-xl);
   --steps-marker-border-width: var(--stroke-md);

package/dist/tokens/components/scroll-area.css

@@ -1,5 +1,12 @@
 
 :root {
 
+  --scroll-area-scrollbar-width: thin;
+
+  --scroll-area-thumb-color: initial;
+  --scroll-area-track-color: initial;
+
+  --scroll-area-scrollbar-space: auto;
+
   --scroll-area-anchor-offset: 3rem;
 }

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

@@ -355,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/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.