@nocoo/basalt 3.2.1 → 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.
@@ -120,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
@@ -153,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.
@@ -191,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
@@ -254,10 +255,15 @@ interaction contracts; do not change their containment as a global workaround.
   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.
@@ -365,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
@@ -406,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