@nocoo/basalt 3.0.0 → 3.2.0

package/ai/DESIGN.md

@@ -46,12 +46,22 @@ or content surface. Card and layout boundaries use their own four-step roles:
 | 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 header/footer insets are 16px horizontal
-and 12px vertical; Body/Well use 16px. `padding="sm|md|lg|xl"` selects unstructured
+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.
+`Header divided` uses 16px on all sides and a bottom rule. Disclosure headers
+(`Header asChild`) keep 16px horizontal / 12px vertical insets and show their
+bottom rule only when open. Footer keeps 16px horizontal / 12px vertical insets;
+Body/Well use 16px. `padding="sm|md|lg|xl"` selects unstructured
 card padding; structured cards keep their slot-owned insets. Compact composite
 card panels use the same 16/12px panel aliases. Their internal buttons and rows
 keep control spacing; do not stretch action rows to the card scale.
 
+Compact card/panel headers (`CodeBlock` header, `ContextCards` chunk header and
+`LayerCard.Header asChild`) share a 44px single-line reference height: a 20px line
+box plus 12px vertical panel inset on each side. Header action buttons use
+`size="sm"` and `-my-basalt-space-sm` so they never inflate the header bar.
+Wrapping and enlarged text may grow the header; do not impose a fixed height.
+
 Layout grids default to medium (16px). ContentIsland owns 16px insets on mobile,
 24px on tablets and 24px vertical / 32px horizontal from 1024px. The catalog shell
 keeps 8px outside the island on mobile and 12px from 768px. Ordinary application
@@ -64,24 +74,40 @@ Dialog and AlertDialog panels use 16px outer insets on mobile and 24px from
 640px. Their buttons and fields retain compact control spacing. Sheets and
 small floating menus have separate inset contracts.
 
+Form rhythm distinguishes a field from a group: label/control/hint spacing stays
+8px, related fields use 16px layout gaps, and separate sections use 24px. A form's
+stack owns those gaps; individual Field components do not add outer margins.
+DialogFooter, AlertDialogFooter and SheetFooter own 16px separation from content
+and keep 8px between actions. Do not add a matching margin at every caller or
+enlarge controls to open a form.
+
 Metric cards use the shared `StatCard`, not a hand-built Header/Body split. A single
 16px inset owns the title, value, comparison and supporting chart; 12px separates
 the heading, metric and content groups, and 4px separates value/supporting text.
 Keep the comparison next to the metric in reading order, before the chart. Icons
-are small unboxed heading cues, not a second painted surface. Values use tabular
-display numerals and wrap naturally. Compact trend plots use 4rem geometry, not
-`flex-1` to fill the card; analytical charts with axes remain separate surfaces.
+are small unboxed heading cues, not a second painted surface. `StatCard` titles
+use 14px (`text-basalt-base`); primary metric numerals in `StatCard`, `StatStrip`
+and dashboard KPIs use 24px (`text-basalt-3xl`), tabular alignment and natural
+wrapping. Compact trend plots use 4rem geometry, not `flex-1` to fill the card;
+analytical charts with axes remain separate surfaces.
 Show the time window and disclose a nonzero line-chart scale. Bar charts keep
 their zero baseline. Metric cards have no internal divider or decorative border.
 
+Action horizontal insets use `--basalt-space-control-x-sm` (10px),
+`--basalt-space-control-x` (12px) and `--basalt-space-control-x-lg` (16px).
+Vertical padding and icon gaps stay compact; Select uses the shared control gap.
+TagBadge uses 6px horizontal padding at `sm` and 8px at `md`.
 All nonzero padding, margin and gaps use the appropriate category scale or aliases.
 Zero, auto margins and hairline seams are structural exceptions, not new density
 levels. Negative margins may cancel an owned boundary, not invent a new gap.
 Use `p-basalt-card`, `gap-basalt-layout`, `gap-basalt-space-sm`, etc. Default nav
 insets and field gaps remain 8px. Selectable rows use 8px horizontal / 6px vertical
-insets and an 8px icon gap. One component owns each boundary: nested sections must
-not accidentally double outer padding. Indented detail content may derive its
-alignment from the row inset + icon width + gap; this is not another density tier.
+insets and an 8px icon gap. Sidebar destinations alone use 8px vertical padding;
+menus, editable navigation and chat rows retain their compact role. One component
+owns each boundary: nested sections must not accidentally double the same inset.
+Distinct surface, column and semantic-slot boundaries may compose their spacing.
+Indented detail content may derive its alignment from the row inset, icon width
+and gap; this is not another density tier.
 
 Existing numbered `--basalt-space-*` tokens are a geometry scale for icons,
 media and shell widths. They are not an alternative margin/padding scale.
@@ -131,8 +157,10 @@ The shared classes calculate natural size as follows:
   Descriptions, wrapping and actions can make a banner taller.
 - Action rows: 22px text line (`--basalt-line-row`) + 6px vertical padding each
   side = 34px. Body prose/code retain the 20px line box. Compound inputs own one
-  outer border; inset children do not add another. Segmented tracks keep 12px text
+  outer border; inset children do not add another. Segmented tracks keep 14px text
   on a 20px line box: 30px items + 2px track inset per side = 34px.
+- Sidebar destination and disclosure rows use the same 22px line box with 8px
+  vertical padding, yielding 38px reference rows without changing shared controls.
 - Cards, dialogs and layout containers have no mandatory height. Textareas and
   chat inputs grow with content (chat: up to five lines, then scroll).
 
@@ -154,12 +182,26 @@ interaction contracts; do not change their containment as a global workaround.
 - Radius choices: `--basalt-radius-sm` (.25rem), `-md` (.5rem), `-lg` (.75rem)
   and `-full` (pill/circle); `none` and `inherit` are structural choices. Widget,
   card and island aliases reference those choices; no per-component radii.
-- Typography uses `--basalt-text-*` and `--basalt-leading-*`. Ordinary text is
-  at least 11px reference, body/action 14px, code content 12px (`text-basalt-sm`),
-  code panel titles 13px (`text-basalt-code`). Display headings use
-  the shared larger scale. Do not shrink text to fit a fixed box.
-- Surfaces preserve the matte L0/L1/L2/L3 hierarchy. Controls use the
-  surface-relative control fill. Hover uses `--basalt-hover`,
+- Typography is positional, not component-specific. Use only the four font-size
+  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) |
+
+  The only independent display-scale exemptions are LandingPage
+  (`src/styles/landing.css`), LoginPage (`src/pages/LoginPage.tsx`) and the 404
+  display in NotFound (`src/pages/NotFound.tsx`, `text-basalt-10xl` only). Every
+  other `src/` font-size class must use one of the four canonical utilities.
+- Surfaces preserve the matte L0/L1/L2/L3 hierarchy. LayerCard adds a subtle
+  `ring-1 ring-basalt-border/50` perimeter; `outlined` strengthens it. Headers
+  use 14px medium-weight foreground text with tight tracking. Controls contrast
+  with their parent: document/surface roots use `--basalt-secondary`, while cards
+  and deeper surfaces use `--basalt-bright` for their control fill. Hover uses `--basalt-hover`,
   `--basalt-primary-hover` or `--basalt-destructive-hover`, not caller opacity.
 - Semantic states, tags, data series and brand imagery may choose semantic
   palettes; keep foreground/background pairs and verify both themes. Centralize
@@ -173,12 +215,13 @@ interaction contracts; do not change their containment as a global workaround.
   lightness in dark mode), never the darker decorative `accent` or `muted` fill.
   Do not add decorative side bars, selection outlines, shadows or pseudo-element
   frames. Navigation uses foreground contrast and medium weight alongside fill;
-  existing semantic checkmarks and tab underlines remain. Both primary and
-  secondary text retain at least 4.5:1 contrast.
-- Hover is transient and follows the configured primary. `--basalt-hover` and
-  `--basalt-hover-end` are complete CSS colors, mixed against the theme popover
-  surface at 9.6%/4.8% in light mode and 16%/9.6% in dark mode. Moving menu and command
-  highlights use a subtle gradient between them, without decorative borders.
+  existing semantic checkmarks and tab underlines remain. Underline tabs use
+  active foreground text and the bottom indicator only, without a rounded box
+  or selected background. Both primary and secondary text retain at least 4.5:1 contrast.
+- Hover is transient and follows the configured primary. `--basalt-hover` is
+  a complete CSS color, mixed against `--basalt-surface-elevated` at 18% primary
+  in both light and dark modes. Moving menu and command highlights use
+  this uniform matte fill, without gradients or decorative borders.
   SegmentControl and ToggleGroup selected items use `--basalt-primary` and its
   contrast-corrected foreground; they are accent controls, not neutral navigation.
   Neutral row selection retains its independent selected tokens.
@@ -196,13 +239,20 @@ interaction contracts; do not change their containment as a global workaround.
   so overflow and collapsed groups cannot clip it. Disabled controls retain
   subdued opacity and cannot become moving-hover targets; selection never lowers
   opacity or mutes its primary label.
-- SidebarPartition is a major section label (12px, semibold, uppercase, 16px top
-  spacing). SidebarGroup is a compact disclosure label (11px, semibold, uppercase,
-  8px inset, 12px group separation), not a destination or hover-highlight target.
-  Ordinary destinations use 14px text and the shared 8px/6px row insets. Groups
-  preserve keyboard expansion and chevron motion; collapsed rails omit labels.
+- SidebarPartition is a major section label (12px / `text-basalt-sm`, semibold,
+  uppercase, 16px top spacing). SidebarGroup is a compact disclosure label
+  (12px / `text-basalt-sm`, semibold, uppercase, 22px line box, 8px inset, 12px
+  group separation), not a destination or hover-highlight target. Ordinary sidebar
+  destinations use 14px (`text-basalt-base`) text and 8px row insets. Groups preserve
+  keyboard expansion and chevron motion; collapsed rails omit labels. Icons stay centered on the 68px collapsed rail, and the brand
+  mark keeps the same center when expanded. Do not trade that axis for a global
+  left-edge alignment.
 - 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.
+- The first eight numbered chart tokens resolve to distinct colors in both themes;
+  supplementary series use matte HSL values independently of the control accent.
+  Sparkline bars use uniform full opacity, never positional dimming.
 
 ## Motion and performance
 
@@ -219,6 +269,10 @@ use linear motion; decorative motion pauses off-screen/in background tabs.
   do not remeasure the same row for pointer movement, and write geometry without
   React rerenders. Nested lists are isolated. Disabled and hidden rows cannot
   become targets; keyboard selection/focus works independently of pointer hover.
+  Sidebar hover starts at the pointer's row and disappears there. It never uses
+  the current route or stale pointer focus as an entry/exit destination. Only
+  continuous movement between hovered rows animates; gaps and disclosure labels
+  end that sequence. Keyboard focus retains its independent focus indicator.
 - Selection indicators snap to the first valid measured selection before paint.
   Never animate from `(0, 0)`, including controlled initial values, non-first
   segments, remounts or initially hidden panels. Animate only between established
@@ -241,33 +295,38 @@ catalog states and source viewers. Do not add a second `main`, viewport height,
 page background, wrapper card or page padding inside the island. A bounded chat
 workspace can use `h-full min-h-0`; it must not create a nested viewport.
 
-Every catalog route uses the same ShowcasePage header: 30px display titles,
-16px descriptions on a 24px line box, 8px title separation and a 65ch maximum
-reading width. Page sections use 24px separation regardless of route category.
-The standalone PageHeader API retains its size choices for consumers, but catalog
-pages do not override the shared scale. ShowcasePage marks `variant="document"`
-for the library index, category guides, component documentation and source viewers.
+Every catalog route uses the same ShowcasePage header: 24px main titles
+(`text-basalt-3xl`), 14px descriptions (`text-basalt-base`) on a 20px line box,
+8px title separation and a 65ch maximum reading width. Page sections use 24px
+separation regardless of route category. PageHeader size choices must preserve
+the same positional font sizes; catalog pages do not override the shared scale.
+ShowcasePage marks `variant="document"` for the library index, category guides,
+component documentation and source viewers.
 The shell owns the complete breadcrumb trail from Dashboard through the library,
 category and component to the current route. Ancestors are links; the current
 route appears once as nonlinked text with aria-current. Source views include their
 component parent. Narrow headers keep every segment reachable by scrolling the
 breadcrumb region without overflowing the page.
-Document sections use `SectionRule variant="heading"`: 20px sentence-case
-headings without the compact dashed rule. Component previews retain their own
+Document sections use `SectionRule variant="heading"`: 18px (`text-basalt-xl`)
+sentence-case headings without the compact dashed rule. Component previews retain their own
 scope; document typography must not cascade into copied controls. Headers have
 natural height, no scenic wrappers, negative insets or fixed empty openings.
 
 Scrollable gallery previews reserve 8px of internal space on every edge for
 control rings, focus outlines and shadows. Padding outside the scroll viewport
 does not protect that paint. Center previews safely so oversized content keeps
-its leading edge reachable.
+its leading edge reachable. Multi-column Table, DataTable and DiffTable examples
+span the category grid; do not squeeze a working data surface into a half-width
+thumbnail. Compact examples such as TablePager retain their smaller grid cells.
 The component library uses one LayerCard per category, separated by 24px. Each
 category uses LayerCard.Header above its grid, not individual cards per component.
 Its light surface is white-toned; dark mode uses the same surface hierarchy rather
 than a fixed white fill.
 
-Cards with headings use `LayerCard.Header` and `LayerCard.Body`; use one Body for
-related content with a shared internal gap, not a padded Body for every line.
+Cards with distinct heading/body regions use `LayerCard.Header` and
+`LayerCard.Body`; use one Body for related content with a shared internal gap,
+not a padded Body for every line. Short overview prose blocks may keep their
+heading and text in one unstructured card inset without Header/Body slots.
 Structured roots and slots must not receive extra outer padding or margins.
 Unstructured cards select `padding` rather than overriding it with utilities.
 Do not paint a fixed surface onto LayerCard or recreate cards with rounded,
@@ -275,6 +334,62 @@ painted divs. Use library controls and tables instead of rebuilding their spacin
 focus, selection and motion in page CSS. Semantic color overrides and purposeful
 chart/canvas geometry remain separate from shared control geometry.
 
+### Island hierarchy
+
+The shell is L0 (`--basalt-background`). `ContentIsland` is the L1 gray canvas
+(`--basalt-card`); its first `LayerCard` islands are L2 (`--basalt-secondary`),
+white-toned in light mode and elevated in both themes.
+
+Inside `ShowcasePage` / `ContentIsland`, only structural chrome sits directly on
+L1: `PageHeader`, `SectionRule` headings, and top-level navigation tabs or filter
+bars that are not attached to a single card. All substantive content blocks MUST
+be encapsulated inside L2 `LayerCard` islands: rationales, guidelines, lists,
+forms, interactive demos, tables, and empty or loading states. A region heading
+does not make its content a surface. Revealed filter forms belong in a `LayerCard`,
+not directly on the L1 canvas. Keep page and region headings outside the content
+islands rather than wrapping the whole page in another card.
+
+### Alignment hierarchy
+
+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 |
+
+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
+label with a 4px gap rather than pushing it away from the values. Reserve the same glyph slot
+for Keep, Add and Remove instead of indenting only changed rows. Ordinary button
+padding is not a table-header inset. Preserve the focus target through a shared
+header control rather than compensating with negative page margins.
+
+Table cells keep 12px horizontal / 8px vertical insets and 40px reference rows.
+Headers use medium weight and 0.04em tracking. Body rows have a subtle bottom
+hairline except the last row; the native separate-border layout paints that
+hairline on cells as well. Striping is off by default; `Table striped` opts into
+alternating current-surface row fills, independently of hover and selection.
+An edge attached to a panel uses `--basalt-space-table-edge` (the panel's 16px
+horizontal inset), independently of the space between columns. DataTable owns
+this through `edge="attached"`; native Table compositions can use
+`ps-basalt-table-edge` and `pe-basalt-table-edge` on the corresponding edge cells.
+A full-width cell uses both. Simple tables without rowSpan or nested tables may
+instead opt into automatic first/last-cell alignment through a wrapper marked
+`data-basalt-table-container` and `data-edge="attached"`. The column owner must
+mark actual edge cells explicitly for rowSpan or nested tables. Row fills and
+header rules remain full width. An already inset table retains the default cell spacing.
+TableCaption owns its 16px horizontal and 12px vertical panel insets, without an
+outside margin. Its text must not touch an enclosing table frame's bottom edge.
+
+Purposeful nesting, such as a preview's focus clearance around a self-contained
+surface, remains valid. Increase the separation between groups before increasing
+every inner gap; breathing room comes from distinguishable groups and adequate
+content width, not uniformly loose controls or one global density multiplier.
+
 ### Container boundary ownership
 
 Choose the boundary before choosing a spacing token. A valid token on the wrong
@@ -287,7 +402,7 @@ owner is still a design error:
 | 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; no Body with `p-0` or compensating margins |
+| 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
@@ -323,7 +438,10 @@ to recreate ordinary actions, selects or inputs.
 `bun run design:check` scans library components/helpers and catalog examples,
 including CSS, for raw spacing/type/radius/motion values, fixed action overrides
 and inline design repairs. The landing route's own CSS is exempt from the spacing,
-radius and type rules and still keeps motion tokens. It derives dashboard page requirements from App routes
+radius and type rules and still keeps motion tokens. Noncanonical Basalt font-size
+classes are rejected, including responsive and important variants; only NotFound's
+`text-basalt-10xl` and LoginPage's independent scale are exempt from the source
+font-size check. It derives dashboard page requirements from App routes
 and checks template ownership, duplicate slot spacing, recreated card surfaces,
 ordinary native controls in pages and page-level control padding overrides.
 It rejects compact control padding on content panels, raw application disclosures,

package/ai/INTEGRATION.md

@@ -428,9 +428,9 @@ Do not wrap those regions in another full-viewport column. Do not set `h-screen`
 
 ### Shared navigation geometry
 
-`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. Top-level items, group items, editable/folder rows and horizontal navigation links reuse the existing row roles: 8px horizontal, 6px vertical, 8px icon gap, 22px line box and a 34px reference height. 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.
+`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.
 
-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, follows keyboard focus and returns to selection on pointer leave. 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.
+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.
 
 `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.
 
@@ -486,13 +486,13 @@ Use `SidebarNav` for vertical lists, including standalone lists of `EditableNavI
 </Sidebar>
 ```
 
-SidebarPartition marks a major section; SidebarGroup is a smaller uppercase, semibold disclosure label with additional group spacing. Group labels do not participate in the destination hover layer. Do not restyle them as ordinary SidebarItem rows or add per-page indentation repairs.
+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.
 
-The 68px rail uses `--basalt-size-rail`. Header and footer center their content automatically; SidebarIconItem uses the shared 34px control size. 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.
+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}>
@@ -1021,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)`:
@@ -1039,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>
@@ -1048,7 +1054,7 @@ export function ProfileForm() {
         <Switch name="notifications" defaultChecked />
       </Field>
 
-      <div className="flex gap-basalt-space-lg mt-basalt-space-lg">
+      <div className="flex gap-basalt-space-lg">
         <Button type="reset" variant="secondary">Reset</Button>
         <Button type="submit" variant="default">Save Changes</Button>
       </div>
@@ -1203,7 +1209,7 @@ export function ProjectSettingsForm() {
   };
 
   return (
-    <form onSubmit={handleSubmit(onSubmit)} className="space-y-basalt-space-lg">
+    <form onSubmit={handleSubmit(onSubmit)} className="space-y-basalt-layout">
       <Field
         label="Project Name"
         hint="Unique name for your project workspace"
@@ -1728,7 +1734,7 @@ export function UserPreferencesForm() {
   };
 
   return (
-    <form onSubmit={handleSubmit} onReset={handleReset} className="space-y-basalt-space-lg 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>
@@ -1807,6 +1813,7 @@ Basalt geometry no longer depends on a host's Tailwind `--spacing`. Both CSS ent
 | 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.
 
@@ -1814,6 +1821,66 @@ Defaults use rem and unitless line-height, preserving browser font-size preferen
 
 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.
@@ -1846,6 +1913,14 @@ All model names, progress summaries, searches and tool outputs on this route are
 
 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.

package/ai/USAGE.md

@@ -1,6 +1,6 @@
 # Basalt AI & Machine Usage Guide
 
-This document describes how AI code assistants, automated agents, and developers can consume `@nocoo/basalt` (v3.0.0).
+This document describes how AI code assistants, automated agents, and developers can consume `@nocoo/basalt` (v3.2.0).
 
 ---
 
@@ -14,7 +14,7 @@ Document anchors formatted as `ai/registry.json#<slug>` reference specific catal
 It contains:
 - **131 Exported Modules** (1 root barrel, components, charts, providers)
 - **120 Ready Catalog Entries** with full API definitions
-- **776 Public Symbols** (405 runtime values, 371 TypeScript types)
+- **781 Public Symbols** (406 runtime values, 375 TypeScript types)
 - **Detailed Component API**: Props, types, defaults, descriptions, and function callable signatures (including all `toast()` variants)
 - **Exact Peer Dependency Closures**: Identifies optional peers required per subpath (e.g., Recharts)