@nocoo/basalt 3.2.0 → 3.2.4

package/README.md

@@ -52,12 +52,14 @@ Import order is strict. Register Basalt tokens before the Tailwind framework imp
 @import "tailwindcss";
 
 @layer base {
-  html, body, #root {
-    height: 100%;
-  }
-  body {
-    @apply bg-basalt-background text-basalt-foreground antialiased;
-  }
+	html,
+	body,
+	#root {
+		height: 100%;
+	}
+	body {
+		@apply bg-basalt-background text-basalt-foreground antialiased;
+	}
 }
 ```
 
@@ -79,21 +81,23 @@ Standalone CSS contains compiled design tokens, scoped control classes, keyframe
 ## Import Architecture
 
 ### 1. Root Barrel (`@nocoo/basalt`)
+
 Contains lightweight base components, inputs, layout surfaces, and providers:
 ```tsx compile:pkg-readme-root-import
 import {
-  Button,
-  Input,
-  LayerCard,
-  ThemeProvider,
-  ThemeToggle,
-  Tooltip,
-  Toast,
-  Sidebar
+	Button,
+	Input,
+	LayerCard,
+	ThemeProvider,
+	ThemeToggle,
+	Tooltip,
+	Toast,
+	Sidebar,
 } from "@nocoo/basalt";
 ```
 
 ### 2. Granular Subpaths (`@nocoo/basalt/components/*`, `@nocoo/basalt/charts/*`, `@nocoo/basalt/providers/*`)
+
 Keeps initial bundle size small by isolating complex or specialized dependencies:
 ```tsx compile:pkg-readme-granular-import
 import { DatePicker } from "@nocoo/basalt/components/date-picker";
@@ -107,6 +111,7 @@ import { useTheme } from "@nocoo/basalt/providers/theme";
 ## Framework Integration Highlights
 
 ### React 19 & Next.js Client Boundaries
+
 Basalt controls require browser event listeners and React context. When using Next.js App Router, render Basalt components within a client module:
 
 ```tsx compile:pkg-readme-client-app
@@ -116,15 +121,16 @@ Basalt controls require browser event listeners and React context. When using Ne
 import { Button, ThemeProvider } from "@nocoo/basalt";
 
 export function BasaltApp() {
-  return (
-    <ThemeProvider>
-      <Button variant="default">Client Control</Button>
-    </ThemeProvider>
-  );
+	return (
+		<ThemeProvider>
+			<Button variant="default">Client Control</Button>
+		</ThemeProvider>
+	);
 }
 ```
 
 ### Server-Side Theme Pre-Hydration
+
 To eliminate theme flashing (FOUC), inject the theme class before React renders:
 
 ```html

package/ai/COMPATIBILITY.md

@@ -30,6 +30,7 @@ The initial public baseline is locked to version **`2.0.3`** (commit `e61efc1`).
   - `@nocoo/basalt/styles/standalone` (Zero-dependency compiled tokens and utility CSS)
 
 ### Machine Verification
+
 All 110 entrypoints, their export targets, 3 CSS paths, and all 572 exported symbols (with value/type fidelity) are cataloged in `packages/basalt/public-api-baseline.json` and verified via `packages/basalt/scripts/verify-public-api.ts`. No entrypoint or public symbol present in this baseline may be removed or have its value/type identity degraded without a major version bump.
 
 ---
@@ -37,8 +38,9 @@ All 110 entrypoints, their export targets, 3 CSS paths, and all 572 exported sym
 ## 2. Export Architecture & Root vs. Granular Principles
 
 ### Root Barrel (`@nocoo/basalt`)
+
 The root barrel is reserved for lightweight, frequently-used leaves, standard inputs, core surfaces, and global providers.
-- **Included on root:** `Button`, `Input`, `Checkbox`, `Switch`, `Badge`, `Text`, `Label`, `Separator`, `LayerCard`, `DescriptionList`, `Sidebar`, `Dialog`, `Sheet`, `Popover`, `Tooltip`, `Toast`, `ThemeProvider`, `ThemeToggle`, `LinkProvider`.
+- **Included on root:** `Button`, `Input`, `Checkbox`, `Switch`, `Badge`, `Text`, `Label`, `Separator`, `LayerCard`, `DescriptionList`, `Sidebar`, `SidebarBrand`, `SidebarToggle`, `Dialog`, `Sheet`, `Popover`, `Tooltip`, `Toast`, `ThemeProvider`, `ThemeToggle`, `LinkProvider`.
 - **Excluded from root:**
   - Radio inputs (`@nocoo/basalt/components/radio`)
   - Heavy visualization libraries (`@nocoo/basalt/charts/*`)
@@ -47,6 +49,7 @@ The root barrel is reserved for lightweight, frequently-used leaves, standard in
   - Application frame layout chrome (`@nocoo/basalt/components/app-shell`, `app-header`, `page-header`, `section-rule`)
 
 ### Wildcard Subpaths & Legacy Internal Helpers
+
 <a id="wildcard-subpaths"></a>
 In `v2.0.3`, wildcard exports (`./components/*`, `./charts/*`, `./providers/*`) exposed all non-test modules in the package, including internal building blocks:
 - **`@nocoo/basalt/components/typeahead-field`**: Internal composite input controller for autocomplete and combobox (`TypeaheadField`, `TypeaheadItem`). Provides popup list and keyboard navigation wiring.
@@ -64,13 +67,14 @@ In `v2.0.3`, wildcard exports (`./components/*`, `./charts/*`, `./providers/*`)
 
 Basalt strictly follows [SemVer 2.0.0](https://semver.org/):
 
-| Change Level | Permitted Changes | Examples |
-|---|---|---|
-| **PATCH** (`2.0.x`) | Backward-compatible bug fixes, internal optimizations, visual refinements that do not alter layout bounding boxes or break existing snapshots. | Fixing event propagation in `Button`, correcting border contrast ratio, fixing broken types. |
-| **MINOR** (`2.x.0`) | Additive, backward-compatible features; new components, new optional props, new granular export paths. | Adding a new `FilterBar` component, introducing an optional `variant` prop to `Badge`. |
-| **MAJOR** (`3.0.0`) | Breaking changes to existing public component signatures, DOM/ARIA structures, or removal of deprecated export paths. | Renaming required props, removing legacy wildcard subpaths, updating peer dependency minimums to React 20. |
+| Change Level        | Permitted Changes                                                                                                                              | Examples                                                                                                   |
+| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
+| **PATCH** (`2.0.x`) | Backward-compatible bug fixes, internal optimizations, visual refinements that do not alter layout bounding boxes or break existing snapshots. | Fixing event propagation in `Button`, correcting border contrast ratio, fixing broken types.               |
+| **MINOR** (`2.x.0`) | Additive, backward-compatible features; new components, new optional props, new granular export paths.                                         | Adding a new `FilterBar` component, introducing an optional `variant` prop to `Badge`.                     |
+| **MAJOR** (`3.0.0`) | Breaking changes to existing public component signatures, DOM/ARIA structures, or removal of deprecated export paths.                          | Renaming required props, removing legacy wildcard subpaths, updating peer dependency minimums to React 20. |
 
 ### Layout & Default Geometry Policy
+
 Changes to default geometry (such as outer padding, default margins, or intrinsic dimensions) alter the visual balance of consuming applications.
 - **Bug Fixes vs Breaking Changes:** Correcting an unintended layout collapse or overflow bug (e.g., popup clipping in cards or chart height collapsing to 0px) is considered a patch/minor fix. Altering default container padding (e.g. changing `LayerCard` padding from `none` to `md`) affects caller assumptions.
 - If default geometry must evolve, before/after migration notes must be published in `CHANGELOG.md`, and backward-compatible props or opt-ins must be offered.
@@ -93,6 +97,7 @@ Basalt chart components build upon modular configuration tokens and series utili
 
 <a id="chart-config"></a>
 ### Chart Configuration (`@nocoo/basalt/charts/config`)
+
 Defines shared tokens, styles, and props for cartesian charts:
 - **Constants**:
   - `CHART_TYPE`: Font sizes (`axisFontSize: 11`, `legendFontSize: 12`, `tooltipTitleSize: 12`, `tooltipBodySize: 12`), `tooltipDot: 8`, stroke width (`strokeWidth: 2`), `gridDash: "3 3"`, `gridOpacity: 0.15`, and `areaFillAlpha: 0.2`.
@@ -117,6 +122,7 @@ Defines shared tokens, styles, and props for cartesian charts:
 
 <a id="chart-series"></a>
 ### Chart Series Utilities (`@nocoo/basalt/charts/series`)
+
 Manages series descriptor shapes, point definitions, and data key fallbacks:
 - **Types**:
   - `ChartSeriesDescriptor`: `{ key: string, label?: string, color?: string }`.
@@ -133,7 +139,6 @@ Manages series descriptor shapes, point definitions, and data key fallbacks:
   - `applyLeadColor(items: ChartSeriesDescriptor[], color?: string): ChartSeriesDescriptor[]`: If `color` is provided and the first item does not specify a `color` (`item.color ?? color`), sets the first item's color. Preserves an explicit first-item color.
   - `xyFallbackKeys(data: Array<{ y2?: number; y3?: number }>): string[]`: Scans data array and dynamically includes `"y2"` and `"y3"` if present, returning `["y", ...]` keys. Compatible with legacy XY series fallback.
 
-
 ---
 
 <a id="6-unreleased-migration-notes-p1p10"></a>
@@ -143,14 +148,14 @@ These notes cover the components, documentation, examples and palette changes in
 
 ### Palettes and production URL
 
-| Before | Current behavior | Consumer action |
-|---|---|---|
-| 24 control accents sharing chart tokens | 12 iMac / iPhone 5C-inspired accents on `--basalt-accent-1…12` | Build pickers from `useAccent().swatches`; do not assume the former count, order, labels, or token values. |
-| 24 distinct `CHART_COLORS` entries | Fixed five-color Blue / Pink / Green / Yellow / Gray cycle; the first four match classic control swatches exactly | Replace direct indexing beyond 4 with `getChartColor(index)` or `index % CHART_COLORS.length`. This is an intentional visual and runtime-value change, not a claim that all prior palette behavior is unchanged. |
-| Numbered chart tokens and 24 `chart` keys | Existing names retained as aliases of five chart colors | Keep imports; expect repeated colors. Use explicit per-series colors and descriptive legends where five categories are insufficient. |
-| Presets only | Optional `AccentProvider.paletteOverrides` with light/dark HSL pairs | Application owns validation and persistence. Overrides affect control swatches and semantic primary, never chart tokens. |
-| Ring remainder tied to a series color | Theme-aware neutral `chartMuted` track | No prop migration. Gauge is static under reduced motion and displays 0, partial, and full values without a black remainder. |
-| `https://basalt.hexly.ai` | `https://basaltui.com` | Update bookmarks and production links. Browser storage is origin-scoped, so old-domain theme/palette preferences cannot transfer automatically. Local `basalt.dev.hexly.ai` is unchanged. |
+| Before                                    | Current behavior                                                                                                  | Consumer action                                                                                                                                                                                                  |
+| ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 24 control accents sharing chart tokens   | 12 iMac / iPhone 5C-inspired accents on `--basalt-accent-1…12`                                                    | Build pickers from `useAccent().swatches`; do not assume the former count, order, labels, or token values.                                                                                                       |
+| 24 distinct `CHART_COLORS` entries        | Fixed five-color Blue / Pink / Green / Yellow / Gray cycle; the first four match classic control swatches exactly | Replace direct indexing beyond 4 with `getChartColor(index)` or `index % CHART_COLORS.length`. This is an intentional visual and runtime-value change, not a claim that all prior palette behavior is unchanged. |
+| Numbered chart tokens and 24 `chart` keys | Existing names retained as aliases of five chart colors                                                           | Keep imports; expect repeated colors. Use explicit per-series colors and descriptive legends where five categories are insufficient.                                                                             |
+| Presets only                              | Optional `AccentProvider.paletteOverrides` with light/dark HSL pairs                                              | Application owns validation and persistence. Overrides affect control swatches and semantic primary, never chart tokens.                                                                                         |
+| Ring remainder tied to a series color     | Theme-aware neutral `chartMuted` track                                                                            | No prop migration. Gauge is static under reduced motion and displays 0, partial, and full values without a black remainder.                                                                                      |
+| `https://basalt.hexly.ai`                 | `https://basaltui.com`                                                                                            | Update bookmarks and production links. Browser storage is origin-scoped, so old-domain theme/palette preferences cannot transfer automatically. Local `basalt.dev.hexly.ai` is unchanged.                        |
 
 Chart gray retains its prior light/dark values. Marks use solid candy colors without contrasting outlines or shadows; their fills are not darkened. Raw candy fills can fall below 3:1 on light surfaces; use descriptive labels and `summary` / `dataAlternative` alongside them. Custom control palettes remain independent.
 
@@ -160,31 +165,31 @@ v2.1.0 includes the palette count and value changes above as an explicit excepti
 
 Persisted accent IDs are normalized on reads and selections:
 
-| Old ID | Retained ID |
-|---|---|
-| `jade`, `seafoam` | `teal` |
-| `vermilion`, `crimson` | `red` |
-| `magenta` | `rose` |
-| `orchid` | `purple` |
-| `cobalt` | `indigo` |
-| `steel` | `primary` |
-| `cadet` | `sky` |
-| `olive` | `lime` |
-| `gold` | `amber` |
-| `tangerine` | `orange` |
+| Old ID                 | Retained ID |
+| ---------------------- | ----------- |
+| `jade`, `seafoam`      | `teal`      |
+| `vermilion`, `crimson` | `red`       |
+| `magenta`              | `rose`      |
+| `orchid`               | `purple`    |
+| `cobalt`               | `indigo`    |
+| `steel`                | `primary`   |
+| `cadet`                | `sky`       |
+| `olive`                | `lime`      |
+| `gold`                 | `amber`     |
+| `tangerine`            | `orange`    |
 
 Other retained IDs keep their identity with the new palette values. Unknown IDs fall back to `primary`. Use IDs rather than array positions for saved selections.
 
 ### Components and application recipes
 
-| Area | Additions and compatibility | Application responsibility |
-|---|---|---|
-| Resource screens | Additive DataTable sorting, manual processing/pagination, header and retry options; ResourceList state/toolbar/bulk/footer slots; granular BatteryMeter | Queries, authorization, selection policy, total counts and backend requests |
-| Filtering | MultiSelect, FilterBar and FilterChip, including controlled search and native form/reset support | Search results and business filter state |
-| Uploads | FileDropzone plus UploadQueue/UploadItem, validation, progress and action callbacks | Transport, retry/cancel, object URL lifetime and server validation |
-| Editing and navigation | InlineEditable, EditableNavItem/FolderNavItem, IconPicker, TagBadge/TagColorPicker, ResponsiveMasterDetail | Persistence, routing, allowed icons, stable item IDs and tree policy |
-| App templates | Complete AppFrame, Login and Resources modules in `ai/RECIPES.md`, compiled from the installed package | Router adapters, authentication, permissions, API calls and real data |
-| Chart details | Values heatmap and Timeline rails use fixed chart tokens; optional `TimelineEvent.textColor` pairs custom event backgrounds with readable titles and subtitles | Choose text color for custom backgrounds; omitted `textColor` keeps the legacy white treatment for explicit event colors |
-| Documentation | Generated props retain generics, callback/constructor union precedence, readonly arrays and tuples | Use the declared type parameters; generated text no longer substitutes `unknown` for caller data types |
+| Area                   | Additions and compatibility                                                                                                                                    | Application responsibility                                                                                               |
+| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
+| Resource screens       | Additive DataTable sorting, manual processing/pagination, header and retry options; ResourceList state/toolbar/bulk/footer slots; granular BatteryMeter        | Queries, authorization, selection policy, total counts and backend requests                                              |
+| Filtering              | MultiSelect, FilterBar and FilterChip, including controlled search and native form/reset support                                                               | Search results and business filter state                                                                                 |
+| Uploads                | FileDropzone plus UploadQueue/UploadItem, validation, progress and action callbacks                                                                            | Transport, retry/cancel, object URL lifetime and server validation                                                       |
+| Editing and navigation | InlineEditable, EditableNavItem/FolderNavItem, IconPicker, TagBadge/TagColorPicker, ResponsiveMasterDetail                                                     | Persistence, routing, allowed icons, stable item IDs and tree policy                                                     |
+| App templates          | Complete AppFrame, Login and Resources modules in `ai/RECIPES.md`, compiled from the installed package                                                         | Router adapters, authentication, permissions, API calls and real data                                                    |
+| Chart details          | Values heatmap and Timeline rails use fixed chart tokens; optional `TimelineEvent.textColor` pairs custom event backgrounds with readable titles and subtitles | Choose text color for custom backgrounds; omitted `textColor` keeps the legacy white treatment for explicit event colors |
+| Documentation          | Generated props retain generics, callback/constructor union precedence, readonly arrays and tuples                                                             | Use the declared type parameters; generated text no longer substitutes `unknown` for caller data types                   |
 
 New workflow modules stay on granular subpaths. Existing string table headers, legacy chart `y`/`y2`/`y3` inputs, required ResourceList data, and explicit series colors remain supported. No automatic downstream migration is performed. A full tree adapter, draggable SplitPane, and maps remain outside this release scope.

package/ai/DESIGN.md

@@ -28,23 +28,23 @@ different density; opening the page layout must not enlarge compact controls.
 
 ## Spacing
 
-| Step | Token | Value | Reference |
-| --- | --- | --- | --- |
-| Extra small | `--basalt-space-xs` | `.125rem` | 2px |
-| Small | `--basalt-space-sm` | `.25rem` | 4px |
-| Medium | `--basalt-space-md` | `.375rem` | 6px |
-| Large / default | `--basalt-space-lg`, `--basalt-space-default` | `.5rem` | 8px |
+| Step            | Token                                         | Value     | Reference |
+| --------------- | --------------------------------------------- | --------- | --------- |
+| Extra small     | `--basalt-space-xs`                           | `.125rem` | 2px       |
+| Small           | `--basalt-space-sm`                           | `.25rem`  | 4px       |
+| Medium          | `--basalt-space-md`                           | `.375rem` | 6px       |
+| Large / default | `--basalt-space-lg`, `--basalt-space-default` | `.5rem`   | 8px       |
 
 These four steps belong to control content: labels, icons, fields, actions,
 selectable rows, menus and banner content. They are not the maximum spacing for a page
 or content surface. Card and layout boundaries use their own four-step roles:
 
-| Step | Card token | Layout token | Value | Reference |
-| --- | --- | --- | --- | --- |
-| Small | `--basalt-space-card-sm` | `--basalt-space-layout-sm` | `.75rem` | 12px |
-| Medium | `--basalt-space-card` | `--basalt-space-layout` | `1rem` | 16px |
-| Large | `--basalt-space-card-lg` | `--basalt-space-layout-lg` | `1.5rem` | 24px |
-| Extra large | `--basalt-space-card-xl` | `--basalt-space-layout-xl` | `2rem` | 32px |
+| Step        | Card token               | Layout token               | Value    | Reference |
+| ----------- | ------------------------ | -------------------------- | -------- | --------- |
+| Small       | `--basalt-space-card-sm` | `--basalt-space-layout-sm` | `.75rem` | 12px      |
+| Medium      | `--basalt-space-card`    | `--basalt-space-layout`    | `1rem`   | 16px      |
+| Large       | `--basalt-space-card-lg` | `--basalt-space-layout-lg` | `1.5rem` | 24px      |
+| Extra large | `--basalt-space-card-xl` | `--basalt-space-layout-xl` | `2rem`   | 32px      |
 
 Card padding defaults to medium. LayerCard headers flow into Body by default:
 16px horizontal/top insets, no bottom inset and an 8px internal gap, without a divider.
@@ -64,10 +64,12 @@ Wrapping and enlarged text may grow the header; do not impose a fixed height.
 
 Layout grids default to medium (16px). ContentIsland owns 16px insets on mobile,
 24px on tablets and 24px vertical / 32px horizontal from 1024px. The catalog shell
-keeps 8px outside the island on mobile and 12px from 768px. Ordinary application
-sections use 24px gaps, including catalog documentation. SectionRule
-uses 12px content separation for compact labels and 16px for reading headings. `Grid gap="sm|md|lg|xl"`
-and semantic utilities such as `gap-basalt-layout-xl` select these tiers.
+keeps 8px outside the island on mobile and 12px from 768px; AppHeader uses the
+same 8px / 12px horizontal inset to align with that outer island boundary, not its
+inner content edge. Ordinary application sections use 24px gaps, including catalog
+documentation. SectionRule uses 12px content separation for compact labels and
+16px for reading headings. `Grid gap="sm|md|lg|xl"` and semantic utilities such as
+`gap-basalt-layout-xl` select these tiers.
 There is no universal height for either category.
 
 Dialog and AlertDialog panels use 16px outer insets on mobile and 24px from
@@ -100,8 +102,9 @@ TagBadge uses 6px horizontal padding at `sm` and 8px at `md`.
 All nonzero padding, margin and gaps use the appropriate category scale or aliases.
 Zero, auto margins and hairline seams are structural exceptions, not new density
 levels. Negative margins may cancel an owned boundary, not invent a new gap.
-Use `p-basalt-card`, `gap-basalt-layout`, `gap-basalt-space-sm`, etc. Default nav
-insets and field gaps remain 8px. Selectable rows use 8px horizontal / 6px vertical
+Container spacing uses 4px multiples (4/8/12/16/24/32px); 2px and 6px
+control-internal spacing remains unchanged. Use `p-basalt-card`, `gap-basalt-layout`,
+`gap-basalt-space-sm`, etc. Default nav insets and field gaps remain 8px. Selectable rows use 8px horizontal / 6px vertical
 insets and an 8px icon gap. Sidebar destinations alone use 8px vertical padding;
 menus, editable navigation and chat rows retain their compact role. One component
 owns each boundary: nested sections must not accidentally double the same inset.
@@ -117,15 +120,15 @@ media and shell widths. They are not an alternative margin/padding scale.
 Choose a category before implementing a component. A composite's root and its
 children can have different categories. Root module inventory:
 
-| Category | Reference | Component modules |
-| --- | --- | --- |
-| Inline | 22px single line | `badge`, `tag-badge` |
-| Action | 34px default | `button`, `input`, `select`, `toggle`, `toggle-group`, `segment-control`, `autocomplete`, `combobox`, `typeahead-field`, `sensitive-input`, `input-group`, `input-area`, `clipboard-text`, `inline-editable`, `multi-select`, `date-picker`, `icon-picker`, `tag-color-picker`, `theme-toggle`, `pagination`, `table-pager` |
-| Banner | 38px single line | `banner`, `toast` |
-| Card / content surface | Natural | `layer-card`, `approval-card`, `context-cards`, `recommendation-card`, `chat-bubble`, `code`, `empty`, `file-dropzone`, `resource-list`, `upload-queue` |
-| Layout / composite | Natural | `accordion`, `collapsible`, `app-header`, `app-shell`, `sidebar`, `navigation-menu`, `editable-nav-item`, `breadcrumbs`, `page-header`, `section-rule`, `filter-bar`, `toolbar`, `grid`, `flow`, `field`, `description-list`, `table`, `data-table`, `diff-table`, `tabs`, `table-of-contents`, `responsive-master-detail`, `scroll-area`, `separator`, `stat-strip`, `chat-header`, `chat-inbox`, `chat-message`, `chat-markdown`, `chat-composer`, `prompt-bar`, `thinking`, `tool-chips`, `loading-screen` |
-| Overlay composite | Natural; triggers/actions follow Action | `dialog`, `alert-dialog`, `confirm-dialog`, `delete-resource`, `sheet`, `dock`, `popover`, `hover-card`, `tooltip`, `dropdown-menu`, `context-menu`, `menu-bar`, `command-palette` |
-| Graphic / text primitive | Content-specific | `avatar`, `basalt-mark`, `battery-meter`, `meter`, `loader`, `skeleton-line`, `text`, `label`, `link`, `checkbox`, `radio`, `switch`, `slider`, `fab` |
+| Category                 | Reference                               | Component modules                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
+| ------------------------ | --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Inline                   | 22px single line                        | `badge`, `tag-badge`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
+| Action                   | 34px default                            | `button`, `input`, `select`, `toggle`, `toggle-group`, `segment-control`, `autocomplete`, `combobox`, `typeahead-field`, `sensitive-input`, `input-group`, `input-area`, `clipboard-text`, `inline-editable`, `multi-select`, `date-picker`, `icon-picker`, `tag-color-picker`, `theme-toggle`, `pagination`, `table-pager`                                                                                                                                                                                   |
+| Banner                   | 38px single line                        | `banner`, `toast`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
+| Card / content surface   | Natural                                 | `layer-card`, `approval-card`, `context-cards`, `recommendation-card`, `chat-bubble`, `code`, `empty`, `file-dropzone`, `resource-list`, `upload-queue`                                                                                                                                                                                                                                                                                                                                                       |
+| Layout / composite       | Natural                                 | `accordion`, `collapsible`, `app-header`, `app-shell`, `sidebar`, `navigation-menu`, `editable-nav-item`, `breadcrumbs`, `page-header`, `section-rule`, `filter-bar`, `toolbar`, `grid`, `flow`, `field`, `description-list`, `table`, `data-table`, `diff-table`, `tabs`, `table-of-contents`, `responsive-master-detail`, `scroll-area`, `separator`, `stat-strip`, `chat-header`, `chat-inbox`, `chat-message`, `chat-markdown`, `chat-composer`, `prompt-bar`, `thinking`, `tool-chips`, `loading-screen` |
+| Overlay composite        | Natural; triggers/actions follow Action | `dialog`, `alert-dialog`, `confirm-dialog`, `delete-resource`, `sheet`, `dock`, `popover`, `hover-card`, `tooltip`, `dropdown-menu`, `context-menu`, `menu-bar`, `command-palette`                                                                                                                                                                                                                                                                                                                            |
+| Graphic / text primitive | Content-specific                        | `avatar`, `basalt-mark`, `battery-meter`, `meter`, `loader`, `skeleton-line`, `text`, `label`, `link`, `checkbox`, `radio`, `switch`, `slider`, `fab`                                                                                                                                                                                                                                                                                                                                                         |
 
 Graphic primitives preserve their intrinsic shape: a checkbox mark is not a
 34px square and an avatar is not a text input. Their containing action rows use
@@ -150,7 +153,8 @@ The shared classes calculate natural size as follows:
 - `basalt-action`: 14px font, 24px line box + 4px vertical padding each side +
   1px border each side = 34px. Explicit `sm` (28px) and `lg` (40px) are shared
   size variants, not ad-hoc height utilities. Icon-only actions use a minimum
-  derived from `1lh`, not a fixed height; icons are normally 14px.
+  derived from `1lh`; `icon-sm` is an actual 28px by 28px control, while `icon`
+  retains the default 34px contract. Icons are normally 14px.
 - `basalt-banner`: 14px font, 22px line box + 12px vertical padding = 46px.
   The outer boundary uses 16px horizontal / 12px vertical panel insets; internal
   icons and actions retain compact control spacing.
@@ -158,7 +162,9 @@ The shared classes calculate natural size as follows:
 - Action rows: 22px text line (`--basalt-line-row`) + 6px vertical padding each
   side = 34px. Body prose/code retain the 20px line box. Compound inputs own one
   outer border; inset children do not add another. Segmented tracks keep 14px text
-  on a 20px line box: 30px items + 2px track inset per side = 34px.
+  on a 20px line box: 30px items + 2px track inset per side = 34px. A horizontally
+  scrolling SegmentControl viewport adds 4px clearance on all four edges and uses
+  matching scroll-padding; this does not enlarge the ToggleGroup track.
 - Sidebar destination and disclosure rows use the same 22px line box with 8px
   vertical padding, yielding 38px reference rows without changing shared controls.
 - Cards, dialogs and layout containers have no mandatory height. Textareas and
@@ -186,12 +192,12 @@ interaction contracts; do not change their containment as a global workaround.
   tokens below, with `--basalt-leading-*` for line boxes. Do not shrink text to
   fit a fixed box or introduce responsive intermediate sizes.
 
-  | Tier | Reference | Token / utility | Roles |
-  | --- | --- | --- | --- |
-  | Auxiliary | 12px / `.75rem` | `--basalt-text-sm` / `text-basalt-sm` | Badges, table column headers, field hints/errors, sidebar uppercase group/partition labels, secondary metadata, chart axes/legends/tooltips, inline code and code block source (`font-mono`) |
-  | Body | 14px / `.875rem` | `--basalt-text-base` / `text-basalt-base` | Body prose, all interactive controls and option rows (including ApprovalCard, RecommendationCard, Table cells and ContextCards), card/panel titles (LayerCard.Header, CodeBlock title, ContextCards header, StatCard title, Popover title and Empty title), PageHeader descriptions and modal/sheet descriptions (DialogDescription, AlertDialogDescription and SheetDescription) |
-  | Section | 18px / `1.125rem` | `--basalt-text-xl` / `text-basalt-xl` | Section/category h2/h3 headings, SectionRule variant="heading" h2, modal/drawer titles (DialogTitle, AlertDialogTitle and SheetTitle) |
-  | Page / metric | 24px / `1.5rem` | `--basalt-text-3xl` / `text-basalt-3xl` | Page main title (PageHeader h1) and primary KPI numerals (StatCard value, StatStrip value and dashboard metrics) |
+  | Tier          | Reference         | Token / utility                           | Roles                                                                                                                                                                                                                                                                                                                                                                             |
+  | ------------- | ----------------- | ----------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+  | Auxiliary     | 12px / `.75rem`   | `--basalt-text-sm` / `text-basalt-sm`     | Badges, table column headers, field hints/errors, sidebar uppercase group/partition labels, secondary metadata, chart axes/legends/tooltips, inline code and code block source (`font-mono`)                                                                                                                                                                                      |
+  | Body          | 14px / `.875rem`  | `--basalt-text-base` / `text-basalt-base` | Body prose, all interactive controls and option rows (including ApprovalCard, RecommendationCard, Table cells and ContextCards), card/panel titles (LayerCard.Header, CodeBlock title, ContextCards header, StatCard title, Popover title and Empty title), PageHeader descriptions and modal/sheet descriptions (DialogDescription, AlertDialogDescription and SheetDescription) |
+  | Section       | 18px / `1.125rem` | `--basalt-text-xl` / `text-basalt-xl`     | Section/category h2/h3 headings, SectionRule variant="heading" h2, modal/drawer titles (DialogTitle, AlertDialogTitle and SheetTitle)                                                                                                                                                                                                                                             |
+  | Page / metric | 24px / `1.5rem`   | `--basalt-text-3xl` / `text-basalt-3xl`   | Page main title (PageHeader h1) and primary KPI numerals (StatCard value, StatStrip value and dashboard metrics)                                                                                                                                                                                                                                                                  |
 
   The only independent display-scale exemptions are LandingPage
   (`src/styles/landing.css`), LoginPage (`src/pages/LoginPage.tsx`) and the 404
@@ -235,18 +241,29 @@ interaction contracts; do not change their containment as a global workaround.
   expose that state instead of switching to a gray secondary variant alone.
   Checkbox/radio/switch glyphs, primary/destructive actions and semantic diff
   colors keep their semantic fills. Color swatches retain their actual palette.
-- Keyboard focus is separate from selection. Navigation uses an inset focus ring
-  so overflow and collapsed groups cannot clip it. Disabled controls retain
+- Keyboard focus is separate from selection. Ordinary focus uses a 1px theme
+  `--basalt-ring` stroke with a 2px outer offset; flush structural targets use the
+  same stroke inset with a 2px negative offset (`basalt-focus-inset`). External
+  focus targets need 4px clearance inside their nearest clipping container;
+  existing padding of at least 4px counts and is not stacked. Forced-colors mode
+  may use a 2px system outline. Focus causes no layout shift, and error indicators
+  remain independent. Navigation uses inset focus so overflow and collapsed groups
+  cannot clip it. Disabled controls retain
   subdued opacity and cannot become moving-hover targets; selection never lowers
   opacity or mutes its primary label.
 - SidebarPartition is a major section label (12px / `text-basalt-sm`, semibold,
   uppercase, 16px top spacing). SidebarGroup is a compact disclosure label
   (12px / `text-basalt-sm`, semibold, uppercase, 22px line box, 8px inset, 12px
   group separation), not a destination or hover-highlight target. Ordinary sidebar
-  destinations use 14px (`text-basalt-base`) text and 8px row insets. Groups preserve
-  keyboard expansion and chevron motion; collapsed rails omit labels. Icons stay centered on the 68px collapsed rail, and the brand
-  mark keeps the same center when expanded. Do not trade that axis for a global
-  left-edge alignment.
+  destinations use 14px (`text-basalt-base`) text and 8px row insets. Sidebar owns
+  a private 24px content column: its 16px region inset composes with the row's
+  8px inset, without changing the shared 8px navigation inset used by other
+  components. Header, footer, search, group and destination content align to that
+  column. `SidebarBrand` reserves a fixed 20px logo slot at 24px, keeping the logo
+  center on the 68px rail axis during the width transition. Its action remains
+  reachable below the header when collapsed. Groups preserve keyboard expansion
+  and chevron motion; collapsed rails omit labels. Icons stay centered on the 68px
+  collapsed rail. Do not trade the rail axis for a global left-edge alignment.
 - Content wells use the actual surface hierarchy, not selected tokens or muted
   fills. Skeletons, progress tracks and decorative code marks may remain subdued.
   Skeleton shimmer uses foreground at 10% opacity so it remains visible in both themes.
@@ -354,12 +371,12 @@ islands rather than wrapping the whole page in another card.
 Alignment is local to a meaningful scope, not a requirement that every text node
 start at the page edge. Establish the outer rail before composing the inner one:
 
-| Scope | Alignment rule |
-| --- | --- |
-| Page | PageHeader and region edges share the ContentIsland rail |
-| Surface | Header, body and footer share their panel inset |
-| Field or column | Labels, controls and values follow that group's start or end rail |
-| Semantic slot | Checkboxes, row numbers and status glyphs reserve their own consistent space |
+| Scope           | Alignment rule                                                               |
+| --------------- | ---------------------------------------------------------------------------- |
+| Page            | PageHeader and region edges share the ContentIsland rail                     |
+| Surface         | Header, body and footer share their panel inset                              |
+| Field or column | Labels, controls and values follow that group's start or end rail            |
+| Semantic slot   | Checkboxes, row numbers and status glyphs reserve their own consistent space |
 
 Related text keeps its rail across sorting, selection and missing optional icons.
 Numeric headings and values share the end rail; a sort glyph sits inward of that
@@ -395,15 +412,15 @@ content width, not uniformly loose controls or one global density multiplier.
 Choose the boundary before choosing a spacing token. A valid token on the wrong
 owner is still a design error:
 
-| Boundary | Owner | Composition |
-| --- | --- | --- |
-| Page/region separation | `ShowcasePage` / `SectionRule` | Layout gaps, no second page inset |
-| Painted content or navigation panel | `LayerCard` | Header and Body slots, never an unpadded painted div |
-| Full-width disclosure heading | `LayerCard.Header asChild` | Slot onto `CollapsibleTrigger`; one hit target, 16/12px insets |
-| Expanded prose or fields | `LayerCard.Body` | Inside `CollapsibleContent unstyled`; one 16px inset |
-| Attached code | `CodeBlock attached` / `CodeHighlighted attached` | Direct child of unstyled disclosure; code owns its 16/12px insets |
-| Edge-to-edge table/list | Its row/cell components | Direct card child; panel inset on edge cells, no Body with `p-0` or compensating margins |
-| Compact status/action strip | `Banner` | Control spacing, not a hand-drawn card |
+| Boundary                            | Owner                                             | Composition                                                                              |
+| ----------------------------------- | ------------------------------------------------- | ---------------------------------------------------------------------------------------- |
+| Page/region separation              | `ShowcasePage` / `SectionRule`                    | Layout gaps, no second page inset                                                        |
+| Painted content or navigation panel | `LayerCard`                                       | Header and Body slots, never an unpadded painted div                                     |
+| Full-width disclosure heading       | `LayerCard.Header asChild`                        | Slot onto `CollapsibleTrigger`; one hit target, 16/12px insets                           |
+| Expanded prose or fields            | `LayerCard.Body`                                  | Inside `CollapsibleContent unstyled`; one 16px inset                                     |
+| Attached code                       | `CodeBlock attached` / `CodeHighlighted attached` | Direct child of unstyled disclosure; code owns its 16/12px insets                        |
+| Edge-to-edge table/list             | Its row/cell components                           | Direct card child; panel inset on edge cells, no Body with `p-0` or compensating margins |
+| Compact status/action strip         | `Banner`                                          | Control spacing, not a hand-drawn card                                                   |
 
 Collapsible owns visibility, focus semantics and motion; it does not add another
 surface. Its default inset is for plain standalone text. Use `unstyled` when a