@nocoo/basalt 2.2.0 → 3.1.0

package/ai/INTEGRATION.md

@@ -1,5 +1,7 @@
 # Basalt application chrome
 
+Design tokens, component categories, intrinsic sizing and motion rules are authoritative in [DESIGN.md](DESIGN.md). Follow that contract for library code and examples.
+
 This is the one-pass setup for a Basalt app. An MVP is **login + shell + one page**. After that, product work is arranging `LayerCard` on the island. Do not invent a second header, a second rail, or a second title above the content heading.
 
 The library owns the rail, the main column, collapse motion, the island, the page heading, and region rules. The app owns navigation data, brand, version, identity, and page bodies.
@@ -43,7 +45,7 @@ AppShell                          ← dashboard and catalog routes
 ├── Sidebar                       ← product title + version + nav
 └── AppMain                       ← id="main-content"
     ├── AppHeader                 ← crumbs + current page | top-right
-    └── island wrap               ← px-2 pb-2 md:px-3 md:pb-3
+    └── island wrap               ← px-basalt-space-lg pb-basalt-space-lg md:px-basalt-space-lg md:pb-basalt-space-lg
         └── ContentIsland
             ├── PageHeader        ← title + subtitle | create / short filters
             │                     ← optional own-row complex filters
@@ -291,7 +293,7 @@ function PreferencesControls() {
   const { accent, setAccent } = useAccent();
 
   return (
-    <div className="flex flex-wrap items-center gap-2">
+    <div className="flex flex-wrap items-center gap-basalt-space-lg">
       <span className="text-sm font-medium">Theme: {theme}</span>
       <Button
         variant="outline"
@@ -300,7 +302,7 @@ function PreferencesControls() {
       >
         Toggle {theme === "dark" ? "Light" : "Dark"}
       </Button>
-      <span className="text-sm font-medium ml-2">Accent: {accent}</span>
+      <span className="text-sm font-medium ml-basalt-space-lg">Accent: {accent}</span>
       <Button
         variant="outline"
         size="sm"
@@ -332,7 +334,7 @@ export function HostPreferencesApp() {
         accent={accent}
         onAccentChange={setAccent}
       >
-        <div className="p-4 border rounded-lg space-y-3">
+        <div className="p-basalt-space-lg border rounded-lg space-y-basalt-space-lg">
           <p className="text-xs text-basalt-muted-foreground">
             Host owns document root DOM and persistence. Basalt contexts operate safely without side-effects.
           </p>
@@ -388,16 +390,16 @@ Bounded shells use border-box `height/max-height: 100dvh`. Document shells use `
   <AppSkipLink>Skip to content</AppSkipLink>
   <AppMain>
     <AppHeader title="Field notes" actions={actions} />
-    <div className="flex min-h-0 min-w-0 flex-1 flex-col md:px-3 md:pb-3">
+    <div className="flex min-h-0 min-w-0 flex-1 flex-col md:px-basalt-space-lg md:pb-basalt-space-lg">
       <ContentIsland mobileSurface="edge-to-edge">
-        <div className="mx-auto max-w-prose px-4 py-3 md:p-0">{content}</div>
+        <div className="mx-auto max-w-prose px-basalt-space-lg py-basalt-space-lg md:p-0">{content}</div>
       </ContentIsland>
     </div>
   </AppMain>
 </AppShell>
 ```
 
-The wrapper intentionally has **no mobile `px-2` / `pb-2`**. ContentIsland cannot remove spacing owned by its parent. Remove consumer `h-screen`, `h-full`, `overflow-hidden`, fixed heights and body scroll locks from the document path; all intermediate wrappers must be natural-height columns. Do not target private descendants to undo the library.
+The wrapper intentionally has **no mobile `px-basalt-space-lg` / `pb-basalt-space-lg`**. ContentIsland cannot remove spacing owned by its parent. Remove consumer `h-screen`, `h-full`, `overflow-hidden`, fixed heights and body scroll locks from the document path; all intermediate wrappers must be natural-height columns. Do not target private descendants to undo the library.
 
 The consumer owns `viewport` metadata: `width=device-width, initial-scale=1, viewport-fit=cover`. Do not disable zoom. The library never edits document metadata or body styles for layout. Floating modal navigation has a separate portal tree: `Sheet` or overlay `Sidebar` owns modal scroll locking/focus; the Sidebar within it remains bounded and applies that portal's safe-area padding once. Do not add a manual body overflow effect.
 
@@ -418,45 +420,30 @@ Copyable complete recipes: [mobile layouts](packages/basalt/ai/RECIPES.md#mobile
 - shell-derived bounded height (standalone `100dvh`), `flex-col`, `shrink-0`, sticky positioning at the shell-owned safe top
 - expanded width **260px** (inline `width`)
 - collapsed width **68px**
-- collapse animation `transition-all duration-300 ease-in-out`
+- collapse animation `transition-[width] duration-basalt-normal ease-basalt` (disabled for reduced motion)
 
 Children of `Sidebar` are **regions only**: header, search, nav, footer. They fill that column. `SidebarNav` is `flex-1 min-h-0 overflow-y-auto`, so the footer stays at the bottom.
 
 Do not wrap those regions in another full-viewport column. Do not set `h-screen`, `w-[260px]`, or `w-[68px]` on an inner element. Width and height stay on `Sidebar`.
 
-### Expanded tree
+### Shared navigation geometry
 
-```
-Sidebar                          ← collapsed={false}; owns 260px and bounded height
-├── SidebarHeader                ← h-14 px-3 already
-│   └── brand row                ← flex, items-center, justify-between, w-full
-│                                 (no extra horizontal padding)
-├── search wrap                  ← px-3 pb-1 only
-│   └── SidebarSearch
-├── SidebarNav                   ← pt-1; flex-1
-│   ├── SidebarPartition         ← label; already px-6
-│   └── item stack               ← flex flex-col gap-0.5 px-3
-│       └── SidebarItem          ← already px-3 py-2.5
-└── SidebarFooter                ← px-4 py-3 already
-    └── SidebarUser
-```
+`SidebarNav` and `NavigationMenuList` own one `--basalt-space-nav-inset` (8px) boundary and `--basalt-space-nav-gap` (2px) between rows. Sidebar groups do not add another horizontal inset. Sidebar destinations and search use 8px horizontal/vertical padding, an 8px icon gap and a 22px line box for a 38px reference row. This is local to Sidebar: editable/folder rows, horizontal navigation links and menus retain 6px vertical padding and 34px rows. Header, search wrapper and footer share the same navigation inset. Do not add caller-owned `px-basalt-space-lg`, `pt-basalt-space-sm` or item-stack padding to compensate for missing package geometry.
 
-`SidebarHeader` already pads horizontally. Brand, version pill, and collapse control go **directly** in it. The version string is read from the app `package.json` at build time. Never hardcode it.
+Use `SidebarNav` for vertical lists, including standalone lists of `EditableNavItem` / `FolderNavItem`; `NavigationMenuList` owns horizontal/vertical Radix navigation. Both compose the existing list-local hover adapter. One background moves with transform between enabled rows. Sidebar hover appears at the actual pointer row and disappears there on leave or over a gap/disclosure label; it never launches from or returns to the active route or stale pointer focus. Only continuous row-to-row hover animates. Keyboard focus remains independent. NavigationMenuList retains its focus/selection-following behavior. Nested lists own separate highlights. Hidden, disabled and actively renamed rows are excluded. Geometry reads are batched per animation frame, same-row pointer motion causes no updates, and reduced motion disables transitions. Navigation state, routes and rename operations remain application-owned; the adapter is View-only.
 
-Nav labels use `SidebarPartition`. The item stack is **one** `px-3` column (the same gutter `SidebarGroup` uses). `SidebarItem` already has its own `px-3`. That is the whole horizontal rhythm: partition at 24px, item content at 24px.
-
-Collapsible sections use `SidebarGroup` instead of Partition + stack. `SidebarGroup` already includes the item gutter. Do not add another `px-3` around it.
+`SidebarHeader` and `SidebarFooter` already pad horizontally. Brand, version pill, and collapse control go directly in the header. The version string is read from the app `package.json` at build time. Never hardcode it. `SidebarPartition` aligns with row text. `SidebarGroup` adds only section spacing, never a second item gutter.
 
 ```tsx excerpt:sidebar-expanded-structure
 <Sidebar collapsed={collapsed}>
   <SidebarHeader>
     <div className="flex w-full items-center justify-between">
-      <div className="flex min-w-0 items-center gap-3">
+      <div className="flex min-w-0 items-center gap-basalt-space-lg">
         <BasaltMark className="h-5 w-5 shrink-0" />
         <span className="truncate text-lg font-semibold text-basalt-foreground md:text-xl">
           Acme
         </span>
-        <span className="shrink-0 rounded-md bg-basalt-secondary px-1.5 py-0.5 text-[10px] leading-none font-medium text-basalt-muted-foreground">
+        <span className="shrink-0 rounded-md bg-basalt-secondary px-basalt-space-md py-basalt-space-xs text-[10px] leading-none font-medium text-basalt-muted-foreground">
           v{version}
         </span>
       </div>
@@ -471,14 +458,14 @@ Collapsible sections use `SidebarGroup` instead of Partition + stack. `SidebarGr
       </Button>
     </div>
   </SidebarHeader>
-  <div className="px-3 pb-1">
+  <div className="px-basalt-nav-inset">
     <SidebarSearch onClick={() => setSearchOpen(true)}>Search</SidebarSearch>
   </div>
-  <SidebarNav className="pt-1">
+  <SidebarNav>
     {groups.map((group) => (
       <div key={group.label}>
         <SidebarPartition>{group.label}</SidebarPartition>
-        <div className="flex flex-col gap-0.5 px-3">
+        <div className="flex flex-col gap-basalt-nav-gap">
           {group.items.map((item) => (
             <SidebarItem
               key={item.href}
@@ -499,56 +486,48 @@ Collapsible sections use `SidebarGroup` instead of Partition + stack. `SidebarGr
 </Sidebar>
 ```
 
+SidebarPartition marks a major section; SidebarGroup is a smaller uppercase, semibold disclosure label with a 22px line box, 8px insets and 12px group separation. Group labels do not participate in the destination hover layer. Do not restyle them as ordinary SidebarItem rows or add per-page indentation repairs.
+
 ### Collapsed tree
 
 Pass `collapsed` on `Sidebar`. The element becomes 68px. Children are icon-sized and centered. Still no inner width/height wrapper.
 
-```
-Sidebar                          ← collapsed; owns 68px
-├── SidebarHeader                ← justify-center px-0
-├── collapse Button              ← ghost icon, mb-1
-├── search SidebarIconItem       ← mb-2; tooltip
-├── SidebarNav                   ← w-full items-center gap-1 pt-1
-│   └── SidebarIconItem          ← h-10 w-10; tooltip
-└── SidebarFooter                ← flex w-full justify-center px-0
-```
+The 68px rail uses `--basalt-size-rail`. Header and footer center their content automatically; SidebarIconItem keeps the 34px control width and derives its 38px minimum height from the sidebar line box and padding. The navigation region centers its icon rows on that same rail axis without caller margin overrides. Render icon-only content with an accessible name and tooltip when collapsed; the library does not hide arbitrary application text. Keep a brand mark's expanded inset consistent with the collapsed axis instead of adding collapse-only offsets.
 
 ```tsx excerpt:sidebar-collapsed-structure
 <Sidebar collapsed={collapsed}>
-  <SidebarHeader className="justify-center px-0">
+  <SidebarHeader>
     <BasaltMark className="h-5 w-5" />
   </SidebarHeader>
   <Button
     variant="ghost"
     size="icon"
-    className="mb-1 self-center"
+    className="mb-basalt-space-sm self-center"
     onClick={onToggle}
     aria-label="Expand sidebar"
   >
     <PanelLeft aria-hidden="true" />
   </Button>
-  <Tooltip delayDuration={0}>
-    <TooltipTrigger asChild>
-      <SidebarIconItem
-        className="mb-2 self-center"
-        onClick={() => setSearchOpen(true)}
-        aria-label="Search (⌘K)"
-      >
-        <Search className="h-4 w-4" strokeWidth={1.5} aria-hidden="true" />
-      </SidebarIconItem>
-    </TooltipTrigger>
-    <TooltipContent side="right" sideOffset={8}>
-      Search (⌘K)
-    </TooltipContent>
-  </Tooltip>
-  <SidebarNav className="w-full items-center gap-1 pt-1">
+  <SidebarNav>
+    <Tooltip delayDuration={0}>
+      <TooltipTrigger asChild>
+        <SidebarIconItem
+          onClick={() => setSearchOpen(true)}
+          aria-label="Search (⌘K)"
+        >
+          <Search className="h-4 w-4" strokeWidth={1.5} aria-hidden="true" />
+        </SidebarIconItem>
+      </TooltipTrigger>
+      <TooltipContent side="right" sideOffset={8}>
+        Search (⌘K)
+      </TooltipContent>
+    </Tooltip>
     {items.map((item) => (
       <Tooltip key={item.href} delayDuration={0}>
         <TooltipTrigger asChild>
           <SidebarIconItem
             active={active(item.href)}
             aria-label={item.label}
-            className="self-center"
             onClick={() => navigate(item.href)}
           >
             <item.icon className="h-4 w-4" strokeWidth={1.5} />
@@ -560,7 +539,7 @@ Sidebar                          ← collapsed; owns 68px
       </Tooltip>
     ))}
   </SidebarNav>
-  <SidebarFooter className="flex w-full justify-center px-0">
+  <SidebarFooter>
     <Tooltip delayDuration={0}>
       <TooltipTrigger asChild>
         <span className="inline-flex">{avatar}</span>
@@ -605,6 +584,8 @@ Breakpoint: `768px`. Below that, the in-flow rail is omitted. The same sidebar c
 
 `SheetContent` bounds its Sidebar to the available height. Sidebar owns the 260px column and the portal safe area. Close the sheet on pathname change. Radix Sheet owns modal scroll locking and focus restoration; do not set body overflow separately.
 
+Sheets slide from their declared edge in 350ms and return in 250ms, while the backdrop fades and blurs to 6px. DropdownMenu, Select, ContextMenu, MenuBar, Popover, HoverCard and Tooltip scale from their trigger origin and fade in/out in 200/150ms. Shared motion tokens live in the package stylesheet; both CSS entrypoints include them. Reduced motion disables these animations. Keep content mounted through Radix's closing state; do not conditionally remove the root before its exit completes.
+
 `AppHeader` `leading` is the menu button on mobile only. Use `density="compact"` with `Button variant="ghost" size="icon"`; compact header controls have a 44px minimum target.
 
 Header actions use a stable hand cursor and compact 12px `TooltipContent`. `Button`, `LinkButton`, `Toggle`, and `ToggleGroupItem` keep their full rectangular pointer target with a transparent `::before`, including rounded corners. Wrap the actual button or link in `TooltipTrigger asChild` so the trigger retains one focusable hit target. `Toggle` and `ToggleGroupItem` selection styling follows `aria-pressed` / `aria-checked`, independently of the tooltip's `data-state`. Icon-only links must include a screen-reader label inside the link as well as an accessible name.
@@ -681,7 +662,7 @@ export function AppFrame() {
           title={title}
           actions={<ThemeToggle aria-label={`Toggle theme (now ${theme})`} />}
         />
-        <div className="flex min-h-0 flex-1 flex-col px-2 pb-2 md:px-3 md:pb-3">
+        <div className="flex min-h-0 flex-1 flex-col px-basalt-space-lg pb-basalt-space-lg md:px-basalt-space-lg md:pb-basalt-space-lg">
           <ContentIsland>
             <Outlet />
           </ContentIsland>
@@ -701,7 +682,7 @@ export function AppFrame() {
 `AppHeader` inherits root `header` attributes (`HTMLAttributes<HTMLElement>`).
 
 - **`title?: string`**: Current page title rendered inside an `h1` (`truncate text-sm font-normal text-basalt-foreground`). (Source type intersection is `HTMLAttributes<HTMLElement> & { title?: ReactNode }`, which narrows valid `title` values to `string | undefined`). Do not also put the current page title in `breadcrumbs`.
-- **`breadcrumbs?: { href?: string; label: ReactNode }[]`**: Ancestor breadcrumb hierarchy displayed before the current page title (ancestors only). Separated by ChevronRight.
+- **`breadcrumbs?: { href?: string; label: ReactNode }[]`**: Breadcrumb hierarchy separated by ChevronRight. Supply ancestors with `title`, or a complete path ending in a nonlinked current item and omit `title`. No trailing separator is rendered without a title.
 - **`leading?: ReactNode`**: Optional slot before breadcrumbs, typically the mobile hamburger drawer trigger.
 - **`actions?: ReactNode`**: Top-right framework controls (`ThemeToggle`, account dropdown, etc.). This slot is reserved for framework controls, **not** the page-level create button.
 - **Native & Ref Boundary**: Inherits native `HTMLAttributes<HTMLElement>`, but does not forward ref.
@@ -714,56 +695,29 @@ Product title and version live in `SidebarHeader`, not in `AppHeader`. Read the
 
 Login is **not** inside `AppShell`. It is a centered badge on the full viewport.
 
-Shape: ISO ID card, `aspect-[54/86]`, `w-72`, `rounded-2xl`, `bg-basalt-card`, layered shadow, hairline ring. Primary strip on top, mark and actions in the body, status strip pinned to the bottom.
+Shape: a fixed badge width, `rounded-basalt-lg`, `bg-basalt-card` and a hairline ring. Three bands: the primary strip on top, the body holding the mark and actions, and the status footer at the bottom. The body grows with its content, so a sign-in form fits without a fixed aspect ratio.
 
 ```tsx excerpt:login-badge-page
 export function LoginPage() {
   return (
-    <div className="relative flex min-h-screen items-center justify-center overflow-hidden bg-basalt-background p-4">
-      <div className="flex flex-col items-center">
-        <div
-          data-basalt-surface-root=""
-          className="relative flex aspect-[54/86] w-72 flex-col overflow-hidden rounded-2xl bg-basalt-card ring-1 ring-black/[0.08] dark:ring-white/[0.06]"
-          style={{
-            boxShadow: [
-              "0 1px 2px rgba(0,0,0,0.06)",
-              "0 4px 8px rgba(0,0,0,0.04)",
-              "0 12px 24px rgba(0,0,0,0.06)",
-              "0 24px 48px rgba(0,0,0,0.04)",
-              "0 0 0 0.5px rgba(0,0,0,0.02)",
-              "0 0 60px rgba(0,0,0,0.03)",
-            ].join(", "),
-          }}
-        >
-          <div className="bg-basalt-primary px-5 py-4">
-            <div className="flex items-center justify-between">
-              <div className="h-4 w-8 rounded-full bg-basalt-background/80" />
-              <div className="flex items-center gap-2">
-                <BasaltMark className="h-4 w-4 text-basalt-primary-foreground" />
-                <span className="text-sm font-semibold text-basalt-primary-foreground">
-                  Acme
-                </span>
-              </div>
-              <span className="text-[10px] font-medium tracking-widest text-basalt-primary-foreground/60 uppercase">
-                Visitor
-              </span>
-            </div>
-          </div>
-          <div className="flex flex-1 flex-col items-center px-6 pt-6 pb-14">
-            <div className="flex h-24 w-24 items-center justify-center overflow-hidden rounded-full bg-basalt-secondary p-2.5 ring-1 ring-basalt-border">
-              <BasaltMark className="h-10 w-10 text-basalt-muted-foreground" />
-            </div>
-            <p className="mt-5 text-lg font-semibold text-basalt-foreground">Welcome</p>
-            <p className="mt-1 text-xs text-basalt-muted-foreground">Sign in to continue</p>
-            <div className="mt-5 h-px w-full bg-basalt-border" />
-            <div className="flex-1" />
-            <Button variant="secondary" className="w-full rounded-xl py-3">
-              Continue
-            </Button>
-          </div>
-          <div className="absolute right-0 bottom-0 left-0 flex items-center justify-center border-t border-basalt-border bg-basalt-secondary/50 py-2.5">
-            <span className="text-[10px] text-basalt-muted-foreground">Secure sign-in</span>
-          </div>
+    <div className="basalt-ui relative flex min-h-dvh items-center justify-center bg-basalt-background p-basalt-space-lg">
+      <div
+        data-basalt-surface-root=""
+        className="flex w-72 max-w-full flex-col overflow-hidden rounded-basalt-lg bg-basalt-card ring-1 ring-basalt-border"
+      >
+        <div className="flex items-center justify-between gap-basalt-space-lg bg-basalt-primary px-basalt-space-lg py-basalt-space-lg">
+          <span className="text-basalt-base font-semibold text-basalt-primary-foreground">Acme</span>
+          <span className="text-basalt-xs font-medium uppercase tracking-widest text-basalt-primary-foreground/80">
+            Visitor
+          </span>
+        </div>
+        <div className="flex flex-1 flex-col items-center gap-basalt-space-lg px-basalt-space-lg py-basalt-space-lg">
+          <p className="text-basalt-xl font-semibold text-basalt-foreground">Welcome</p>
+          <p className="text-basalt-sm text-basalt-muted-foreground">Sign in to continue</p>
+          <Button className="w-full">Continue</Button>
+        </div>
+        <div className="border-t border-basalt-border px-basalt-space-lg py-basalt-space-lg">
+          <p className="text-basalt-xs text-basalt-muted-foreground">Secure sign-in</p>
         </div>
       </div>
     </div>
@@ -797,13 +751,15 @@ Boot and route gates use `LoadingScreen` — a centered mark and a 6rem shimmer
 
 When skip link, rail (260 / 68, 300ms), header `h-14`, and island are in place, add routes as `Outlet` pages. Regular application pages inside the island start with `PageHeader`. Mobile immersive layouts may use a single `AppHeader` instead, with `PageHeader` shown only on desktop; see the root geometry contract. The shell file does not grow with page UI.
 
-Standalone login, loading, error, and landing pages use their own first-screen structure: `/login` preserves the visitor-badge composition, `/loading` is a named loading status, and `/404` and `/static-page` have independent headings. Library reference pages use their document heading and section navigation. These are deliberate layout exceptions, not alternate application-page templates.
+Standalone login, loading, error, and landing pages use their own first-screen structure: `/login` preserves the visitor-badge composition, `/loading` is a named loading status, and `/404` and `/static-page` have independent headings. These are deliberate layout exceptions, not alternate application-page templates. Library reference pages, category overviews and source viewers are normal island pages: they use the same heading template, with document sections below it.
+
+The showcase's routes under `DashboardLayout` use the app-local `ShowcasePage`: one PageHeader and a shared section gap, with no repeated island padding, painted shell or nested main/viewport. Every catalog route keeps that shared scale: 30px titles and 24px page and document-section separation, whether it is an application page, a library index, a category guide, documentation or a source viewer. Catalog pages do not override the shared scale or its document rhythm; `PageHeader` keeps its `size` choices for consumers, where dashboards select `size="lg"` for 30px titles and ordinary application pages keep the `md` default. Header height follows content, never a scenic banner or negative inset. The original logo remains in navigation; mountain artwork belongs only to the independent landing. See [DESIGN.md](DESIGN.md#page-composition).
 
-The showcase site's library index and dashboard examples use the app-local `ShowcaseHeader` with the landing page's paired day/night mountain imagery fading into the content island. Headings and actions align with the page's content grid; the landscape reaches the island's top edge and scrolls with it. The library has a more spacious opening, dashboards use the compact variant, and reference headings carry a quieter version. The original logo remains in the navigation. This site-specific treatment does not change the package's `PageHeader` or application layout recipe.
+The catalog's app-local `RouteScrollReset` wraps each leaf page inside its Suspense boundary. Once the route content is committed, a changed pathname resets ContentIsland and document scrolling immediately, including Back/Forward navigation. Valid URL fragments instead use the chapter anchor with the measured sticky-directory inset. Same-page query changes and local controls preserve scroll. The shared sidebar is not remounted or scrolled. Routing policy belongs to the app, never to the Basalt package.
 
 The `/forms`, `/settings`, `/data`, and `/chat` examples demonstrate local state and simulated requests, including failure/retry and cancellation. Their viewmodels own data and timers; Views own native FormData, focus, and responsive layout. Replace the local service adapter when integrating a backend. Theme selection uses the shared provider; local profile, uploads, and chat changes do not update a real account.
 
-`PageHeader` is flush on `ContentIsland`. Do not wrap it in another card. Do not put an icon row above the heading.
+`PageHeader` is flush on `ContentIsland`. The island owns 16px mobile insets, 24px tablet insets, and 32px horizontal / 24px vertical desktop insets. Do not wrap the header in another card or add page padding. `PageHeader.size` is `"md" | "lg" | "xl"` (default `"md"`); larger headings use 16/24px descriptions, all title/description pairs use an 8px gap. `SectionRule variant="heading"` gives reading sections a 20px sentence-case title without the compact dashed rule. Controls and card slots keep their compact geometry.
 
 ### Create and filters
 
@@ -824,7 +780,7 @@ import { PageHeader } from "@nocoo/basalt/components/page-header";
 
 export default function ProjectsPage() {
   return (
-    <div className="space-y-8">
+    <div className="space-y-basalt-layout-lg">
       <PageHeader
         title="Projects"
         description="Active work in this workspace."
@@ -854,7 +810,7 @@ import { SectionRule } from "@nocoo/basalt/components/section-rule";
 
 export default function ProjectsPage() {
   return (
-    <div className="space-y-8">
+    <div className="space-y-basalt-layout-lg">
       <PageHeader
         title="Projects"
         description="Active work in this workspace."
@@ -873,7 +829,7 @@ export default function ProjectsPage() {
         }
       />
       <SectionRule title="Overview" hint="Live totals for the current workspace.">
-        <div className="grid grid-cols-2 gap-4">
+        <div className="grid grid-cols-2 gap-basalt-layout">
           <LayerCard>
             <p className="text-xs text-basalt-muted-foreground">Projects</p>
             <p className="text-2xl font-semibold">24</p>
@@ -972,7 +928,9 @@ Place cards with Grid or flex. Those classes do not paint. A grid of `LayerCard`
 
 Input, Select, secondary / outline Button use `bg-basalt-control` (`--basalt-control-fill` from the current surface) plus border. Do not override with `bg-card`, `bg-basalt-card`, or `bg-basalt-background`.
 
-`Table` sets `data-basalt-table`. Zebra, hover, and selected paint on `td`, from `--basalt-zebra-fill` / `--basalt-control-fill`.
+`Table` sets `data-basalt-table`. Zebra, hover, and selected paint on `td`, from `--basalt-zebra-fill`, `--basalt-hover` and `--basalt-selected`. Selection adds no decorative side bar or frame; semantic add/remove diff tints are preserved.
+
+Neutral selected states use the brighter `--basalt-selected` surface, readable `--basalt-selected-foreground` and navigation font weight, without decorative side bars or selected borders. Never use `accent` or `muted` to signal selection. Existing semantic checkmarks and tab underlines remain; do not add a decorative frame at the white ceiling. A moving hover layer must not erase the selected row. Sidebar, navigation menus, editable navigation and ChatInbox share this behavior and inset keyboard focus; neutral Button variants also honor `aria-pressed` and `aria-current`. Segments and tabs retain their existing measured indicator motion. Primary/destructive actions, check/radio/switch glyphs and semantic diffs keep their semantic colors. See [DESIGN.md](DESIGN.md#selection-and-navigation-hierarchy).
 
 `DescriptionList` is layout and type only. It is not a surface.
 
@@ -1063,6 +1021,12 @@ Stack one `SectionRule` per region. Live recipe: `/layout`. Catalog: `/ui/page-h
 
 Basalt form controls participate in standard forms and controlled state pipelines.
 
+Keep the Field's label/control/hint gap at 8px. Compose related fields with
+`space-y-basalt-layout` or `gap-basalt-layout` (16px); separate sections with the
+24px `layout-lg` role. The form owns the group gap, not each Field's margin.
+Action buttons keep their 8px internal gap. DialogFooter owns 16px separation
+from preceding content, so callers do not need a repeated margin override.
+
 ### Working Native HTML Form & FormData Pattern
 
 Standard inputs (`Input`, `InputArea`, `Checkbox`, `Radio`, `Switch`) reliably supply their values via standard `FormData(event.currentTarget)`:
@@ -1081,7 +1045,7 @@ export function ProfileForm() {
   };
 
   return (
-    <form onSubmit={handleSubmit}>
+    <form onSubmit={handleSubmit} className="space-y-basalt-layout">
       <Field label="Email" hint="Your primary email address">
         <Input name="email" type="email" required />
       </Field>
@@ -1090,7 +1054,7 @@ export function ProfileForm() {
         <Switch name="notifications" defaultChecked />
       </Field>
 
-      <div className="flex gap-2 mt-4">
+      <div className="flex gap-basalt-space-lg">
         <Button type="reset" variant="secondary">Reset</Button>
         <Button type="submit" variant="default">Save Changes</Button>
       </div>
@@ -1179,7 +1143,7 @@ export function EmptyActionExample() {
   const [created, setCreated] = useState(false);
 
   return (
-    <LayerCard className="max-w-md p-6">
+    <LayerCard className="max-w-md">
       {created ? (
         <p className="text-sm text-basalt-foreground">Project created successfully.</p>
       ) : (
@@ -1245,7 +1209,7 @@ export function ProjectSettingsForm() {
   };
 
   return (
-    <form onSubmit={handleSubmit(onSubmit)} className="space-y-4">
+    <form onSubmit={handleSubmit(onSubmit)} className="space-y-basalt-layout">
       <Field
         label="Project Name"
         hint="Unique name for your project workspace"
@@ -1283,12 +1247,12 @@ export function ProjectSettingsForm() {
       />
 
       {submittedData && (
-        <div data-testid="submission-output" className="text-sm font-mono p-2 border rounded">
+        <div data-testid="submission-output" className="text-sm font-mono p-basalt-space-lg border rounded">
           Submitted: {JSON.stringify(submittedData)}
         </div>
       )}
 
-      <div className="flex gap-2">
+      <div className="flex gap-basalt-space-lg">
         <Button
           type="button"
           variant="secondary"
@@ -1487,6 +1451,7 @@ Basalt charts are composed of responsive frame, legend, and tooltip subsystem pr
 ### StatCard & StatGrid (`@nocoo/basalt/charts/stat-card`)
 
 - **`StatCard`**: High-level KPI and telemetry presentation card supporting incremental interactive slots and status state transitions.
+  - **Composition**: One `LayerCard` surface with shared card insets, an unboxed title icon, tabular display value, comparison text and supporting content in that order. It has no header divider or fixed content height. Long labels and values wrap; actions remain accessible. Use a compact `LineChart`/`BarChart` child with `className="h-basalt-16 w-full"` and a visible time-window caption for trend cards. Keep bar baselines at zero and disclose nonzero line scales. Do not stretch plots with `flex-1`, repeat card padding or recreate the header in application CSS.
   - **Props (`StatCardProps`)**:
     - `value: string | number` (required): Core metric value. Formatted via `toLocaleString()` if numeric. Overridden when `status` is provided.
     - `title?: string` / `label?: string` (optional): Heading text (`title` takes precedence over `label`).
@@ -1513,6 +1478,8 @@ Basalt charts are composed of responsive frame, legend, and tooltip subsystem pr
 
 Basalt cartesian charts (`LineChart`, `AreaChart`, `BarChart`, `StackedBarChart`, `GroupedBarChart`, `Charts`, `Timeseries`, `CustomChart`, `Sparkline`, and `SlotBarChart`) support arbitrary, type-safe data keys beyond the legacy `y`, `y2`, and `y3` series convention:
 
+`Sparkline` renders compact, rounded bars with alternating full/muted intensity (decorative, not another data dimension). A single series defaults to chart green; explicit series colors and multi-series palette order are preserved. Its default plot is 112 by 20px, without axes, legends, tooltips or entrance animation. Null values remain gaps and negative values retain their baseline. Pair it with `Meter` for table cells: Meter uses 17 slots, redistributes red/yellow/green across the filled portion, and shows the numeric value inline. Colors do not imply domain-specific risk thresholds. Values clamp to 0..100 and non-finite readings announce unavailable. `BatteryMeter` remains the separate device-charge control.
+
 - **Generic Data Binding**:
   - `data: TData[]`: Generic record where `TData extends { x: string | number }`. Caller datasets can contain any number of arbitrary metric keys (e.g., `edgeCache`, `p95US`, `workersCPU`), nullable numbers (`number | null`), and optional numeric properties (`number | undefined`).
   - `series?: Array<ChartSeriesDescriptor<K>>`: Strongly-typed array of series descriptors. Series keys `K` are automatically constrained to `LineChartNumericKeys<TData>` (excluding coordinate `x` and rejecting non-numeric fields such as strings, booleans, or typos). Arbitrary keys require explicit series; omitted or empty series retain each chart's legacy `y`, `y2`, and `y3` series fallback. Note that TypeScript type inference does not automatically enumerate object keys at runtime.
@@ -1545,7 +1512,7 @@ export function StandaloneViteApp() {
 
   return (
     <ThemeProvider>
-      <div className="min-h-screen bg-basalt-background text-basalt-foreground p-6 space-y-6">
+      <div className="min-h-screen bg-basalt-background text-basalt-foreground p-basalt-space-lg space-y-basalt-space-lg">
         <PageHeader
           title="Standalone Workspace"
           description="Rendered with @nocoo/basalt/styles/standalone without Tailwind preflight"
@@ -1556,7 +1523,7 @@ export function StandaloneViteApp() {
             <span className="font-semibold text-basalt-foreground">Project Search</span>
           </LayerCard.Header>
           <LayerCard.Body>
-            <div className="flex gap-3 max-w-md">
+            <div className="flex gap-basalt-space-lg max-w-md">
               <Input
                 value={query}
                 onChange={(e) => setQuery(e.target.value)}
@@ -1633,7 +1600,7 @@ export default function NextClientDashboardPage() {
 
   return (
     <ThemeProvider>
-      <div className="p-6 space-y-4">
+      <div className="p-basalt-space-lg space-y-basalt-space-lg">
         <div className="flex justify-between items-center">
           <h2 className="text-xl font-bold text-basalt-foreground">Next.js Client Dashboard</h2>
           <ThemeToggle aria-label="Toggle theme mode" />
@@ -1646,7 +1613,7 @@ export default function NextClientDashboardPage() {
               onChange={(e) => setMetricName(e.target.value)}
               aria-label="Metric Name"
             />
-            <div className="mt-4">
+            <div className="mt-basalt-space-lg">
               <Button variant="outline" onClick={() => setMetricName("Default Metric")}>
                 Reset Metric
               </Button>
@@ -1706,12 +1673,12 @@ export function RoutedNavigationSection() {
   return (
     <MemoryRouter initialEntries={["/dashboard"]}>
       <LinkProvider render={ReactRouterLinkAdapter}>
-        <nav className="flex gap-4 p-4 border-b border-basalt-border">
+        <nav className="flex gap-basalt-space-lg p-basalt-space-lg border-b border-basalt-border">
           <NavigationItem href="/dashboard">Dashboard</NavigationItem>
           <NavigationItem href="/settings">Settings</NavigationItem>
           <NavigationItem href="https://docs.hexly.ai">External Docs</NavigationItem>
         </nav>
-        <div className="p-4">
+        <div className="p-basalt-space-lg">
           <Routes>
             <Route path="/dashboard" element={<DashboardPage />} />
             <Route path="/settings" element={<SettingsPage />} />
@@ -1767,7 +1734,7 @@ export function UserPreferencesForm() {
   };
 
   return (
-    <form onSubmit={handleSubmit} onReset={handleReset} className="space-y-4 max-w-sm">
+    <form onSubmit={handleSubmit} onReset={handleReset} className="space-y-basalt-layout max-w-sm">
       <Field label="Username" hint="Public profile handle">
         <Input name="username" defaultValue="johndoe" required />
       </Field>
@@ -1782,7 +1749,7 @@ export function UserPreferencesForm() {
         </div>
       )}
 
-      <div className="flex gap-2">
+      <div className="flex gap-basalt-space-lg">
         <Button type="reset" variant="secondary">
           Reset
         </Button>
@@ -1812,3 +1779,162 @@ export function UserPreferencesForm() {
   }}
 />
 ```
+
+## Agent feedback
+
+`Thinking`, `ApprovalCard`, and `ToolChips` are granular component imports under `@nocoo/basalt/components/`. They use Basalt tokens, existing disclosures and controls, and reduced-motion-safe entrance/expand animations. The package's `models/agent-feedback.ts` defines data semantics; private `viewmodels/` own UI state, timers, answer validation and submission locking. Views import the ViewModels; ViewModels never import Views or DOM modules. Private model/ViewModel paths are not public package exports.
+
+- `Thinking` takes stable step IDs, caller-owned statuses (`pending`, `running`, `complete`, `error`), labels and optional plain-text details. `variant` is `steps`, `reasoning`, `search` or `coding`. Disclosure can be controlled or use `defaultOpen`. It never fabricates progress or exposes hidden model reasoning; display only trace data that the application intentionally supplies.
+- `ApprovalCard` takes questions with stable question/option IDs, `single`/`multiple` choice, optional custom text and `required` (true by default). Single choice may move forward after 240ms; the last question always requires explicit Submit. Optional questions may be skipped. `onSubmit` receives a sanitized answer snapshot and may return a promise; pending submission locks controls, failure keeps answers for retry, and no work is executed by the library. Remount with a new React key when replacing an approval request. Backend authorization and validation remain mandatory.
+- `ToolChips` takes caller-owned tool steps and optional file diffs. It summarizes completion, expands individual plain-text outputs, and opens file previews in accessible popovers. It does not execute commands or parse arbitrary HTML.
+- Catalog examples simulate progress in application ViewModels. Their copyable snippets include those demo ViewModels, rather than importing private catalog paths.
+
+### Dense controls and moving list highlights
+
+Button (including icon buttons), Input, SelectTrigger, InputGroup and their composing controls default to 34px high. Explicit `sm`/`lg` sizes remain available; InputArea remains multiline. Compact application headers retain their 44px minimum touch targets. ApprovalCard uses 16px horizontal / 12px vertical panel padding and compact option spacing; ToolChips uses 14px row text and 16px glyphs with 34px reference rows.
+
+Select, DropdownMenu, ContextMenuPanel, MenuBarContent, Combobox/Autocomplete, MultiSelect, ApprovalCard and ToolChips use one list-local hover layer. Its private DOM adapter batches reads in requestAnimationFrame, measures only when row/focus/selection/size changes, and updates CSS variables without a React state render. Position animates with transform, not top/left layout; reduced motion removes transitions. Disabled/hidden rows are excluded, keyboard focus takes priority, and observers/listeners are released with the mounted list. CommandPalette's list shrinks with its viewport so all rows remain reachable even inside short frames.
+
+Loader uses eight perimeter cells with an empty center, moving clockwise continuously. Label, shimmer and delayed elapsed-time controls are unchanged.
+
+## Dimension tokens
+
+Basalt geometry no longer depends on a host's Tailwind `--spacing`. Both CSS entrypoints expose the same `--basalt-space-*` and `--basalt-size-*` variables. Override semantic roles on a shared ancestor; portaled overlays inherit from their portal ancestor, so application-wide settings belong on `:root`. Theme switches do not reset dimensions.
+
+| Role | Token | Default |
+| --- | --- | --- |
+| Small / default / large control | `--basalt-size-control-sm`, `--basalt-size-control`, `--basalt-size-control-lg` | 28 / 34 / 40px |
+| Compact / standard / display icon | `--basalt-size-icon-sm`, `--basalt-size-icon`, `--basalt-size-icon-lg` | 12 / 14 / 16px |
+| Nested action | `--basalt-size-control-inset` | 28px |
+| Minimum touch target | `--basalt-size-touch` | 44px |
+| Menu option | `--basalt-size-menu-row`, `--basalt-space-menu-inset`, `--basalt-space-menu-x`, `--basalt-space-menu-y` | 34px / 8px / 8px / 6px |
+| Card padding | `--basalt-space-card-sm`, `--basalt-space-card`, `--basalt-space-card-lg`, `--basalt-space-card-xl` | 12 / 16 / 24 / 32px; default 16px |
+| Layout spacing | `--basalt-space-layout-sm`, `--basalt-space-layout`, `--basalt-space-layout-lg`, `--basalt-space-layout-xl` | 12 / 16 / 24 / 32px; grids 16px, page sections 24px |
+| Field label gap | `--basalt-space-field-gap` | 8px |
+| Textarea minimum height | `--basalt-size-textarea-sm`, `--basalt-size-textarea`, `--basalt-size-textarea-lg` | 64 / 80 / 96px |
+| Table row / horizontal / vertical inset | `--basalt-size-table-row`, `--basalt-space-table-x`, `--basalt-space-table-y` | 36 / 8 / 6px |
+| Attached table outer edge | `--basalt-space-table-edge` | Panel horizontal inset, 16px |
+
+Defaults use rem and unitless line-height, preserving browser font-size preferences. [DESIGN.md](DESIGN.md) defines compact 2/4/6/8px control spacing, separate 12/16/24/32px card and layout spacing, and natural 22/34/46px inline/action/banner categories. The size tokens describe reference geometry, not fixed text-control heights. Use the semantic spacing role for the boundary being laid out; numbered geometry tokens are not padding alternatives. LayerCard accepts `padding="sm|md|lg|xl"` for unstructured content; Grid accepts `gap="sm|md|lg|xl"`. Both default to `md`; 32px `xl` is opt-in. ContentIsland owns a 16px mobile, 24px tablet, and 32px horizontal / 24px vertical desktop inset. Examples must use component size props rather than fixed-height overrides. Textareas, avatars and panels retain content-specific geometry.
+
+### Compact record tables
+
+DataTable uses 13px single-line content, 36px minimum rows, tokenized horizontal/vertical insets and a native horizontally scrollable region. A column's `width` is also its minimum width; the browser must not squeeze names/dates into accidental multi-line rows. Use `column.wrap: true` for actual prose fields, or an explicitly sized inner `truncate` element with a title for long record names and URLs. `maxHeight` bounds the existing scroll region, with sticky opaque headers that stay inside it. Sorting uses a fixed 12px icon slot and retains `aria-sort`; row selection uses the shared Checkbox rather than an unstyled native checkbox. Rich `headerContent` composes icons and labels without changing the plain accessible sort name. Empty/loading/error content remains readable and wraps independently of data-cell defaults.
+
+Use `column.textAlign: "end"` for comparable numbers: the header and values share
+a logical end rail, with the sort glyph inward of the header label. `"start"` is
+the other explicit direction; omitted body-cell alignment remains inherited.
+The same `textAlign` prop is available on TableHead, TableCell and
+TableSortableHeader from `@nocoo/basalt/components/table`. It does not replace
+native HTML `align` attributes. Logical directions follow LTR/RTL consistently.
+
+TableSortableHeader is a flush, ref-forwarding button, not a generic Button with
+extra padding. Pass its `sorted` direction (`"asc"` / `"desc"`, or omitted) and
+sort callback; the enclosing TableHead owns `aria-sort`. Unsortable headers remain
+plain text, not disabled sort controls. DataTable handles those details for its
+own columns.
+
+For a DataTable directly attached to a LayerCard, set `edge="attached"`. It uses
+the 16px panel rail only at the outermost cells, including optional number/select
+columns and full-width state rows. Intercolumn spacing stays 8px per cell side.
+Built-in pagination shares that panel rail and its 12px bottom inset.
+The default `edge="inset"` keeps ordinary table spacing inside an already padded
+region; do not add a zero-padding Body around an attached table.
+
+```tsx compile:integration-attached-table
+import { DataTable, type DataTableColumn } from "@nocoo/basalt/components/data-table";
+import { LayerCard } from "@nocoo/basalt/components/layer-card";
+
+type Invoice = { id: string; amount: number };
+const columns: DataTableColumn<Invoice>[] = [
+  { id: "id", header: "Invoice", accessor: (row) => row.id },
+  { id: "amount", header: "Amount", accessor: (row) => row.amount, textAlign: "end" },
+];
+
+export function InvoicePanel() {
+  return (
+    <LayerCard>
+      <LayerCard.Header>Invoices</LayerCard.Header>
+      <DataTable
+        aria-label="Invoices"
+        edge="attached"
+        columns={columns}
+        data={[{ id: "INV-01", amount: 1240 }, { id: "INV-02", amount: 80 }]}
+        getRowId={(row) => row.id}
+      />
+    </LayerCard>
+  );
+}
+```
+
+Native Table does not infer a grid from its children. For an attached native
+composition, mark the true inline-start cells with `ps-basalt-table-edge`, the
+inline-end cells with `pe-basalt-table-edge`, and a full-width cell with both.
+Rows continuing a preceding `rowSpan` do not gain a new edge at their first DOM
+child. These token utilities keep cell backgrounds, sticky headers and separators
+full width without affecting nested tables. Use ordinary Table cells when no
+panel edge is being attached.
+
+TableCaption owns balanced `--basalt-space-panel-x` / `--basalt-space-panel-y`
+insets (16px horizontal / 12px vertical), not an outside top margin. Keep it
+inside the native table; do not pad the entire scroll region or compensate with
+an extra footer wrapper. This preserves full-width row paint and readable space
+above and below the description inside an enclosing frame.
+
+### Recommendations
+
+`RecommendationCard` (`components/recommendation-card`) accepts stable-ID options with a label, plain-text description, confidence (`high`, `review`, `none`) and optional action label/disabled state. Alternatives expand with the existing disclosure and shared hover layer; choosing one changes the recommendation, never executes it. `onAccept` runs only after the explicit action. Promise rejection preserves the selection and shows retry feedback; pending acceptance locks controls and successful acceptance cannot be repeated for the current option. Remount with a new key for a new recommendation request. The application must perform authorization and persist any real action. Private model/ViewModel modules own confidence metadata and state, without View or DOM imports.
+
+### Retrieved context
+
+`ContextCards` (`components/context-cards`) displays caller-owned chunks with stable IDs, title, text, character count and source metadata. The optional total count cannot be smaller than the displayed count; omitted character counts are computed from Unicode code points. Sources without a destination remain non-interactive labels. Only clean root-relative or HTTP(S) URLs without credentials become external links; other schemes and ambiguous URLs are shown as labels, never executed. Loading, empty and retryable error states are explicit. Entrance staggering is CSS-only, capped at 240ms and disabled for reduced motion; no timer delays access to the source links. Source retrieval and authorization belong to the app.
+
+### Proposed tabular changes
+
+`DiffTable` (`components/diff-table`) renders caller-owned text/number rows marked `add`, `remove` or `unchanged`. Changed rows start included and can be toggled by clicking the row or its keyboard-operable Checkbox. Add/remove labels and glyphs carry the meaning independently of tint. `onApply` receives a detached snapshot of only selected changed rows; no data is mutated internally. Pending actions lock selection and duplicate submission; rejection preserves selection with retry feedback. Remount with a new key for a new proposal. Real writes, access checks and validation stay in the application.
+
+### Record numbering and identity
+
+Set `DataTable.rowNumbers` to show an additional `#` column. Numbers follow current sorted/filtered display order and continue from the resolved page offset, including server pagination. They never replace stable row IDs or selection keys. `AvatarInitials` on `components/avatar` reuses the circular Avatar surface with deterministic semantic colors and the first two word initials; `colorKey` keeps color stable across renames and `initials` supports application abbreviations. `size="sm"` is 24px for compact records. Keep the full name as its accessible label.
+
+## AI conversation primitives
+
+`ChatComposer` now uses the his.fm native `field-sizing: content` pattern: one line initially, a maximum of five line-heights plus token padding, then internal vertical scrolling. No per-keystroke JS height measurement is used. Enter sends, Shift+Enter inserts a newline, and IME composition (including keyCode 229) never submits. Controlled `value`/`onValueChange` keep thread-specific drafts application-owned; async `onSend` errors preserve the draft. Attachment metadata and file selection callbacks never upload files themselves. `PromptBar` composes the same composer with application-owned model, reasoning and web-search controls. Stop remains an explicit callback; no microphone permission is requested.
+
+`ChatMessage` provides user/assistant layout, trace/result slots, copy, feedback, edit and regenerate actions. `ChatMarkdown` uses the maintained `marked` lexer but renders React nodes, never raw HTML. It supports prose, lists, code, GFM tables and validated links. HTML is plain text; Markdown images become links rather than making unprompted remote requests. Business conversations, persistence, generation and approvals stay outside these views. The `marked` dependency is imported only by granular chat-content entrypoints, not the root barrel. Entity references are decoded with `entities` before link validation; code and raw HTML remain literal. `ChatMarkdown.streaming` reveals newly appended prose words with a short CSS blur/opacity animation. Existing words keep stable keys, no per-word timers are allocated, and reduced motion removes the effect. Copy confirmations belong to the exact copied content, so updated messages and code do not retain a stale success state.
+
+### Conversation workspace example
+
+The catalog `/chat` route composes these public controls in a session-only workspace. `src/models/chat.ts` owns the pure conversation reducer and deterministic response fixtures; `useChatViewModel` owns the cancellable simulation clock. Views own only DOM scrolling, focus and overlay presentation. Threads keep independent drafts, models, reasoning/search settings and attachment names. Switching threads stops the current reply. Edit/resend and regeneration replace the downstream transcript rather than duplicating user messages. Approval pauses the clock until an explicit decision; decline produces a read-only explanation. Message history, feedback and draft data disappear on reload.
+
+All model names, progress summaries, searches and tool outputs on this route are local examples, not real AI or hidden chain-of-thought. File selection validates a maximum of three image/text/PDF files of 10 MB each and retains metadata only: it never reads or uploads file contents. Diff acceptance and recommendation actions only prepare a follow-up draft. The library does not supply authentication, conversation persistence, model transport, voice recording or server authorization. Connect those through application ViewModels and validate every real tool action on the server.
+
+### Composite alignment
+
+Use one padding owner per boundary: `--basalt-space-panel-x/y` (16/12px) for composite card/header/body/footer sections, `--basalt-space-row-x/y/gap` (8/6/8px) for selectable rows, and `--basalt-space-content-gap` (8px) between related controls inside a composite. Page section gaps instead use `--basalt-space-layout-lg` (24px). `--basalt-space-row-content` derives the detail inset from row padding + a 16px icon slot + the row gap. Selectable action rows use the 22px `--basalt-line-row`, producing 34px single-line rows and growing by full lines when content wraps. Status icons occupy a first-line-height slot, not an arbitrary top margin. Body prose and code keep the 20px body line-height. Ordinary controls use 34px; inline message actions use the 34px `--basalt-size-action` target and 14px glyphs. Align visible glyphs with prose without removing their pointer target.
+
+These are local alignment rails, not one universal left edge. Page headings align
+to the island; card slots align to their panel; columns align their own labels and
+values. A checkbox, row number or optional status glyph has a consistent semantic
+slot. Distinct boundaries may add spacing, but the same boundary has one owner.
+See [alignment hierarchy](DESIGN.md#alignment-hierarchy). Keep nested preview focus
+clearance and give wide table examples enough columns rather than shrinking all
+their padding to fit a thumbnail.
+
+Thinking and ToolChips share row padding; disclosures rotate only their own chevron, never content icons. Approval, recommendation, retrieved context and diff sections share panel insets rather than adding another padding layer. ChatComposer owns its field inset, not an outer painted/padded card; the application owns placement in the page. ChatMessage `sources` renders a compact disclosure beside actions and a flat source list, with the same validated URL policy as ContextCards. Use ContextCards only for actual retrieved text chunks, not as a citation footer. No additional remote images are loaded.
+
+The standalone build generates every Tailwind utility once in canonical order. Do not append handwritten copies of `.p-0`, `.bg-transparent` or other native utilities after generated axis/state rules: a later shorthand can silently erase semantic padding. Browser acceptance measures actual computed insets in both CSS entrypoints, under foreign host spacing and semantic overrides.
+
+Public Radio, Checkbox, Switch and SegmentControl group roots establish the scoped `.basalt-ui` reset. Fieldsets and legends have no browser-default padding/margin inside that boundary; standalone and Tailwind consumers must have identical group insets. Host form groups outside Basalt remain untouched.
+
+Native form legends do not participate in a fieldset's flex gap. Radio, Checkbox and Switch legends therefore own `margin-bottom: var(--basalt-space-field-gap)` (8px) independently of the group's row layout. Do not replace the semantic legend or add wrapper divs to simulate this spacing. Override the existing field-gap token when a different group density is required.
+
+### Code panels
+
+`CodeBlock` and `CodeHighlighted` share one compact code panel: optional `title`, a decorative `icon` (default file-code glyph, `null` to hide), `copyable` (true by default) and `lineNumbers` (false by default). Plain CodeBlock takes string children; CodeHighlighted takes `code` and reuses the lightweight built-in tokenizer. The root now forwards HTMLDivElement attributes and `className`; its inner named, keyboard-focusable pre owns scrolling. Do not pass rendered React children or assume the root is a pre. Use `copyable={false}` without a title for headerless output. Existing `max-h-*` classes constrain the panel while the source region scrolls; the header remains visible.
+
+For edge-attached content, use `attached` rather than overriding border, radius or padding classes. It removes the outer frame except the top separator and keeps code-owned insets. Do not wrap attached code in LayerCard.Body. The standard full-width disclosure is `Collapsible asChild` around a LayerCard, with `LayerCard.Header asChild` around CollapsibleTrigger and `CollapsibleContent unstyled` around a Body or self-inset code/table. Header owns the full hit target and aligned 16/12px insets; Collapsible owns only interaction and motion. See [container boundary ownership](DESIGN.md#container-boundary-ownership), also used by the catalog's navigation and example panels.
+
+Code panels contain horizontal overscroll only. Vertical wheel/touch scrolling chains to the page: natural-height examples do not trap it, and explicitly height-constrained panels hand it off at their top/bottom edge. No JavaScript wheel interception or axis conversion is used. Horizontal gestures and focused Left/Right arrow keys still scroll long source lines without moving the header.
+
+Panel insets use the shared 16/12px roles. Code content uses the shared small font token (.75rem, 12px reference) on a 20px line box; titles remain 13px and the copy target is 34px. Inline Code and Chat Markdown code spans use the same small font tier. Source lines retain empty and trailing lines, with horizontal scrolling rather than breaking tokens. The hidden, non-selectable line-number gutter uses CSS-generated text, so numbers never enter clipboard output or assistive reading. Copy uses the exact original source (including CRLF), prevents concurrent writes, reports permission/API failure and permits retry; feedback belongs to that source revision. No source text is interpreted as HTML or executed. Private model/ViewModel modules own tokenization and copy state; browser clipboard access remains in the View. Chat Markdown fences compose this same panel rather than maintaining a second toolbar implementation. This is not a language parser or a text-diff viewer.