@sableui/react 0.17.0 → 0.19.0

package/llms-full.txt

@@ -1,6 +1,6 @@
 # Sable (@sableui/react)
 
-> An owned, themeable React component system. Default theme: **Sable** (dark-by-default, content-first, fluid product UI). Behavior from Base UI; styling via Tailwind v4 + semantic CSS-variable tokens; Reicon icons via a pluggable adapter. 122 components, 13 layout primitives, and a **patterns** tier of canonical page shells. The full, per-component contract is the generated `registry.json`.
+> An owned, themeable React component system. Default theme: **Sable** (dark-by-default, content-first, fluid product UI). Behavior from Base UI; styling via Tailwind v4 + semantic CSS-variable tokens; Reicon icons via a pluggable adapter. 123 components, 13 layout primitives, and a **patterns** tier of canonical page shells. The full, per-component contract is the generated `registry.json`.
 
 ## Start here — brief, composition, evidence
 
@@ -436,7 +436,10 @@ keyboard/focus behavior, semantic token roles and motion policy. Explain which
 behavior a replacement gains and what must remain. An unused page pattern is not
 drift; repeated overrides can indicate a missing system hook rather than app misuse.
 Run relevant `sable doctor`, `sable lint <paths> --json` and `sable grade <paths>
---json` checks. Lint is lexical; source grades and pattern similarity do not judge
+--json` checks. Grade's `rebuiltParts` lists elements whose class names stand in
+for a part (`.crumb` for Breadcrumbs, `.property` for PropertyRow) and app CSS
+that re-lays a component from outside; `modes` lists colours set for light with no
+dark value, and whether anything lets a user switch modes. Report each. Lint is lexical; source grades and pattern similarity do not judge
 taste. Deliberately static motion slots remain valid with appropriate feedback.
 Lint's `label-contrast` measures an app's overrides of the brand fills (`--primary`,
 `--sidebar-primary`, `--highlight`) and status fills (`--destructive`, `--success`,
@@ -445,6 +448,37 @@ names the nearest pair that reads. Report it with that pair as a recommendation.
 A reasoned `design-lint-disable-next-line label-contrast` is the app's recorded
 choice: list it as intentional, not as a defect.
 
+## Adoption: an app wired for Sable that barely uses it
+
+The commonest drift is not a wrong prop. It is an app where an agent never
+loaded this skill: the stylesheet and tokens are wired, and every control is the
+app's own (a `Modal`, a `PrimaryButton`, a `Tabs` written from scratch). Wiring
+checks pass, and lint only sees the raw elements. `sable check` (and `sable
+grade --json` → `adoption`) measures it: how many UI files compose Sable, which
+app-defined components are named for something Sable ships and do the behaviour
+by hand, and what the app's foundation is. `sable doctor` warns when adoption is
+`none` or `low`. It is never a failure: whether working screens move is the
+user's call.
+
+Put the choice to the user before changing anything. Ask, don't migrate silently
+and don't leave it unmentioned. Show the swaps, behaviour first (overlays,
+controls, tabs, menus, anything with focus or keyboard handling), with what each
+one gains ("your Modal has no focus trap or Esc; Sable's Dialog has both").
+Layout and look stay the app's. How strongly to recommend it depends on the
+`foundation` the report names:
+
+| Foundation | What to say |
+|---|---|
+| `ad-hoc`: no system besides Sable | Recommend the move plainly. There is nothing to preserve but one-off components, and every one is a behaviour bug waiting. Offer to do it a screen at a time. |
+| `own`: a folder of the app's own primitives | Offer the swaps and say what each gains. Keep the app's own where the user prefers them; suggest building them on Sable's behaviour (a `Button` wrapper around Sable's `Button`) instead. |
+| `library`: another component library (MUI, Radix, shadcn-style `components/ui`) | Ask whether Sable should replace it or only cover new work. Don't mix two control libraries on one screen. |
+| `sable`: Sable already carries the UI | Mention the few swaps listed when those screens are next touched. |
+
+Use the question tool the host offers when there is one. Record the answer in
+the project's instructions, so the next task doesn't ask again. On a yes, move
+one screen or component at a time with `fix`/`polish`, running `sable check` and
+looking at the rendered states after each.
+
 ## Deliver evidence-backed findings
 
 Save the audit under `design/<surface>/audit/` or the existing review location.
@@ -775,8 +809,9 @@ For the full screen (header, grouping, avatars, answer actions, the empty state)
 
 Marketing, docs, settings, a feed, a dashboard — anything whose primary
 interaction is reading and navigating. This is the default register; if you are
-building an editor or a canvas app, see
-[building-a-tool.md](./building-a-tool.md).
+building an editor, a canvas app, or a records workspace where people work
+through items with the selected one open beside the list (an issue tracker, a
+support queue), see [building-a-tool.md](./building-a-tool.md).
 
 ## Start from the brief, then choose composition
 
@@ -956,12 +991,16 @@ source checks alone says nothing about hierarchy, story, or the resulting polish
 
 # Task: building a tool (workspace register)
 
-An editor, a canvas app, a console — anything whose primary interaction is
-*operating on something* rather than reading and navigating.
+An editor, a canvas app, a console, or a records workspace (an issue tracker, a
+support queue, a pipeline): anything whose primary interaction is *operating on
+something* rather than reading and navigating.
 
 If the primary interaction is reading down a page, stop: you want
 [building-a-page.md](./building-a-page.md). A dashboard that scrolls is a page
-with dense content, not a workspace.
+with dense content, not a workspace. A tracker or inbox where people work
+through records one at a time, with the selected one open beside the list, is a
+workspace. Start that one from the `TrackerPage` pattern
+(`sable pattern TrackerPage --skeleton`) and read "A records workspace" below.
 
 ## The shell
 
@@ -985,12 +1024,88 @@ hierarchy do not automatically transfer to dense operating surfaces.
 </Workspace>
 ```
 
+Every slot is optional; the body is always the one growing row. A bar that
+belongs to one column (a list's breadcrumbs and view switch, with the inspector
+running the full height beside it, as in Linear) is a `WorkspaceBar` placed first
+inside that column, not the `toolbar` slot.
+
 `Workspace` sets the compact density scope for its whole subtree. Nothing
 hardcodes a height: every control reads `--control-*`, so the same
 `<Button size="md">` is 40px on a page and 32px here. A `Dialog` opened from
 inside resets to comfortable, because a modal is a page-register surface even
 when a tool launched it.
 
+## A records workspace
+
+The shape of an issue tracker, a support queue or a CRM pipeline. Every piece
+below exists, so the build is composition; `sable pattern TrackerPage
+--skeleton` has the whole tree.
+
+```tsx
+<Workspace statusBar={<StatusBar>…</StatusBar>} bottomNav={<BottomNav>…</BottomNav>}>
+  <PanelGroup>
+    <Panel label="Navigation" width={220} narrow="sheet" side="left"
+           open={narrow ? navOpen : true} onOpenChange={setNavOpen} scroll={false}>
+      <Sidebar variant="inline">
+        <SidebarHeader><SidebarBrand mark={…} label="Studio" />{search}</SidebarHeader>
+        <SidebarNav>
+          <SidebarItem icon={…} label="Inbox" badge={…} />
+          <SidebarGroup label="Workspace">{items}</SidebarGroup>
+        </SidebarNav>
+        <SidebarFooter>
+          <Menu>
+            <MenuTrigger render={<SidebarAccount avatar={<Avatar size="2xs" … />} label="Emma Lee" detail="Studio" />} />
+            <MenuContent side="top" align="start">{settings, appearance, sign out}</MenuContent>
+          </Menu>
+        </SidebarFooter>
+      </Sidebar>
+    </Panel>
+    <WorkspaceCanvas className="flex flex-col">
+      <WorkspaceBar><Breadcrumbs>…</Breadcrumbs></WorkspaceBar>
+      <WorkspaceBar><Tabs><TabsList variant="pill">…</TabsList></Tabs></WorkspaceBar>
+      {filters}
+      <DataTable groupBy={(r) => r.status} groups={…} isRowSelected={…} onRowClick={…} />
+    </WorkspaceCanvas>
+    <Panel label="Details" width={320} narrow="sheet" open={selected != null}
+           onOpenChange={(o) => !o && setSelected(null)} scroll={false}>
+      <PanelSection title="Properties"><PropertyRow label="Status">…</PropertyRow></PanelSection>
+    </Panel>
+  </PanelGroup>
+</Workspace>
+```
+
+The decisions that keep it one system:
+
+- **One grid down the rail.** SidebarBrand, SidebarItem, SidebarGroup and
+  SidebarAccount share the icon and label columns, and inside the compact scope
+  they take 32px rows on their own. Do not drop SideNav, an Entity or a stack of
+  ghost Buttons into the rail: each brings its own insets.
+- **The account is one row and a menu.** Settings, appearance (light, dark,
+  system) and sign-out go in the SidebarAccount's menu, not in a Settings button
+  above it or a badge beside it. Its detail line ("Studio · Demo") carries what a
+  badge would.
+- **One table, grouped.** Rows grouped by state are one `DataTable` with
+  `groupBy`: one header, columns that line up, a count and an add action per
+  group. Not one table per group inside Collapsibles.
+- **The inspector renders once.** `Panel narrow="sheet"` docks it on a desktop
+  and makes it a Sheet below `lg`. Not a media-query hook plus a second copy in a
+  Sheet. The nav rail does the same from the left, and fills its sheet.
+- **Reading inside the tool is page-sized.** An overview, a description, notes or
+  a docs tab goes in `<Density value="comfortable">`, or its prose renders at the
+  11px chrome tier.
+- **A view switch in chrome is a pill.** `TabsList variant="pill"`: its fill takes
+  the compact `--button-radius`, about 5px, so it reads as a segment. Underline
+  tabs are the page-section idiom.
+- **Ship both modes, and a way to switch.** The look is a preset with light and
+  dark; SableThemeProvider applies it, and the account menu or a Settings dialog
+  holds the mode switch. A tool asked to be compact and technical takes
+  `type-base` (13 or 14) in the preset, which rebuilds the whole type scale,
+  instead of per-tier overrides.
+- **State has a shape.** A status with more than on and off (partly done, in
+  review) can be an app-owned glyph, but give it a label (`role="img"`,
+  `aria-label`) and colour it from the palette (`var(--yellow-500)`) so it
+  follows the mode.
+
 ## What you will need, and what to avoid reaching for
 
 | you want | use | NOT |
@@ -1002,6 +1117,17 @@ when a tool launched it.
 | a colour property | `ColorField` | `<input type="color">` — OS dialog, ignores the theme, wrong size |
 | ambient document facts | `StatusBar` | a toolbar — status is glanced at, not operated |
 | chrome typography | `text-ui-md` / `-sm` / `-body` / `-section` / `-micro` / `-num` | `text-body-*` — page tiers, ~1/3 too large here |
+| a title in a panel | `text-title-lg` (14px `text-ui-title` in compact) | a heading tier, or a page-tier override on `:root` |
+| a top bar over one column | `WorkspaceBar` first in the column, with `Breadcrumbs` | a hand-built `<header>` with `/` spans |
+| nav groups in a rail | `SidebarGroup` | `SideNav` + `SideNavGroup` — another set of columns |
+| the account at the foot of a rail | `SidebarAccount` as a `MenuTrigger` | an Entity + a Settings Button + a Badge |
+| a view switch in a bar | `TabsList variant="pill"` | underline tabs (page idiom), a hand-built segmented row |
+| rows grouped by state | `DataTable groupBy` + `groups` | a DataTable per group in Collapsibles |
+| a date property | `DatePicker size="xs"` | `<input type="date">` — OS format, wrong size |
+| a person in a row | `Avatar size="2xs"` / `"xs"`, `AvatarGroup` for several | a class on Avatar to shrink it |
+| a project or workspace mark | `Avatar shape="square" tone="…"` | a tinted `<span>` |
+| an inspector on a phone | `Panel narrow="sheet"` | a media-query hook and a second render in a Sheet |
+| a reading tab | `<Density value="comfortable">` | prose in chrome tiers |
 
 ## Menus, selects and popovers adapt on their own
 
@@ -1060,9 +1186,12 @@ a modal is its own surface rather than part of the control that opened it.
   the nesting reads inverted. Use `treeIndent(depth)`; never hand-write an inset.
 - **No pills in chrome.** The compact scope flattens `--button-radius` to ~5px —
   one of two page-register rules the workspace register deliberately reverses.
+  `TabsList variant="pill"` takes that radius too, so in a bar it is a segment.
 - **Drag with window listeners, not `setPointerCapture`.** Capture throws for an
   inactive pointer id and the throw aborts the handler mid-gesture, silently.
-- **An unmapped `<Icon name>` renders nothing.** No error. Check the contract.
+- **An unmapped `<Icon name>` renders nothing.** A development build warns and
+  names the nearest names, and Lucide or Heroicons spellings resolve, but check
+  with `sable icon <name>` before you write one, through a wrapper too.
 
 ## Verify
 
@@ -1092,8 +1221,10 @@ and distinguish observed behavior from untested claims.
 ## Read next
 
 - `DESIGN.md → Registers` — doctrine, measured numbers, the two reversals
+- `sable pattern TrackerPage --skeleton` — the records workspace, whole
 - `llms/components/workspace.md`, `panel-group.md`, `panel-section.md`,
-  `tree.md`, `scrub-field.md`, `status-bar.md`, `color-field.md`
+  `sidebar.md`, `data-table.md`, `tree.md`, `scrub-field.md`, `status-bar.md`,
+  `color-field.md`
 - `llms/reference/token-intent.md` — which token to reach for
 
 ---
@@ -1259,7 +1390,13 @@ for each recognizable element with `sable search "<need>" --json`; inspect the
 matching `component <Name> --props` and `--examples` before implementation.
 Use Sable's composed anatomy and supported variants. A hand-built button, field,
 menu, dialog, table, or card that imitates a shipped component violates the contract.
-That binds behaviour and parts, not layouts. Results marked ◇ (patterns, blocks,
+That binds behaviour and parts, not layouts. Search a part by its plain name and
+its role before writing a class or component for it (`sable search breadcrumb`,
+`sable search "top bar"`); exported parts such as `PropertyRow` and `WorkspaceBar`
+are listed by name, and `sable component <Part>` answers with their entry. When a
+part's look or size disagrees with the design, use its variant or prop, or report
+the missing variant; never rebuild it. `sable icon <name>` says whether an icon
+exists. Results marked ◇ (patterns, blocks,
 and compositions such as MediaTile) are references: use one when its layout fits
 the brief, otherwise compose your own from Sable's parts. The brief's signature
 surfaces, where the product's identity lives, are designed from its direction.
@@ -1278,8 +1415,10 @@ implement genuinely app-specific structure without creating parallel controls.
 
 ## Finish the working product
 
-Run `sable doctor`, `sable lint <source paths> --json`, and the project's build/type
-checks. Inspect desktop/mobile layouts, operate the primary task and recovery
+Run `sable check <source paths>` (doctor, lint and grade) and the project's
+build/type checks. Answer each Rebuilt parts note in the reuse inventory, and fix
+a colour-modes warning: app colours live in a preset with both modes, and a
+`ThemeSwitcher` under `SableThemeProvider` lets the user review each. Inspect desktop/mobile layouts, operate the primary task and recovery
 path, and check keyboard focus, fonts, reduced motion, and meaningful states.
 Use [reviewing-a-design.md](./reviewing-a-design.md),
 [reviewing-a-journey.md](./reviewing-a-journey.md), and
@@ -1590,6 +1729,15 @@ are optional: set `page-inset` and the `region-*` caps (`form`, `feed`, `content
 `wide`, `full`) in `tokens.shared` only when the direction calls for a different
 page proportion, and keep each cap's role.
 
+Overall type size is one token. Sable's scale is built on a 16px base;
+`"type-base": "14"` (or 13) in `tokens.shared` rebuilds every page tier at that
+base, keeping their ratios, and spacing follows because the rhythm is derived
+from body size. Use it when the direction is denser or more technical than the
+bundled presets (a tracker, a console, "like Linear"). Don't rescale the root
+font-size, and don't override tiers one by one to the same end. Retune a single
+tier only when that tier's role changes. Inside a Workspace the chrome already
+uses its own compact `ui-*` tiers.
+
 ```bash
 pnpm exec sable preset --template
 pnpm exec sable preset --check .sable/presets/clay.json --json
@@ -2274,15 +2422,22 @@ In a monorepo where Sable belongs to one workspace package, run setup in that
 package with `--root` naming the repository root (for example
 `pnpm --filter web exec sable setup --agent --root ../..`); the entries go
 there and resolve Sable through the package.
+Setup also adds a short managed block to the project's `AGENTS.md` and
+`CLAUDE.md`, the instructions an agent reads on every task, so a UI request
+goes through the skill even when it doesn't mention Sable. Only the text between
+its `<!-- sable:begin -->` and `<!-- sable:end -->` markers is Sable's;
+`--no-instructions` skips it.
 Each entry resolves `skills/sable/SKILL.md` from the installed package, so package
 upgrades also update the workflow. Other agents can read that file directly.
 Use `$sable build <idea>`, `inspire <references>`, `audit <target>`, or
 `polish <target>` in Codex; use `/sable` with the same modes in Claude Code or
 Cursor. `create` is a build alias. These are agent modes, not shell commands.
 
-Upgrade with `pnpm update @sableui/react --latest`, then
-`pnpm exec sable setup --agent --update`. Setup only replaces managed files
-that have not been locally edited; `--dry-run` checks without writing. Keep
+Upgrade with `pnpm exec sable upgrade`: it updates the package, then runs the
+new version's `init`, which refreshes the skill entries and the instructions
+block and checks the wiring. From 0.17 or earlier, which has no `upgrade`, run
+`pnpm update @sableui/react --latest` and then `pnpm exec sable init` once.
+Setup only replaces managed files that have not been locally edited; `--dry-run` checks without writing. Keep
 project preferences in project instructions. Package installation alone does not
 change agent settings. See [building-with-sable.md](./building-with-sable.md),
 [creating-a-preset.md](./creating-a-preset.md), and
@@ -3382,8 +3537,7 @@ saved file. Replace, don't add beside:
 ## Upgrade the package and skill
 
 ```bash
-pnpm update @sableui/react --latest
-pnpm exec sable setup --agent --update
+pnpm exec sable upgrade
 pnpm exec sable preset --check .sable/presets/clay.json --json
 pnpm exec sable doctor
 ```
@@ -3542,7 +3696,9 @@ Every tier belongs to one family, and the family is the decision. Size follows f
 6. **Cap reading text at --measure-prose (65ch).** Past roughly 75 characters the eye loses the line return. A wide region can still hold a 65ch column.
 7. **Numbers that must align use a mono tier (tabular figures).** Proportional digits change width as values update, so totals and columns shimmy.
 8. **text-wrap: balance on headings, pretty on ledes, neither on long prose.** balance evens short headlines; pretty only refuses a one-word last line. Both cost layout work that long prose does not repay.
-9. **A mark attached to a line of type (a dot, a bullet, a timeline marker, a leading icon) sits in a box one line tall (h-[1lh] items-center) and is sized in em.** 1lh is the line-height of the text beside it, so the mark centres on that line in every tier, density and theme. A px size with a mt-[3px] nudge is right for one font at one size and wrong everywhere else.
+9. **To make all the type smaller or larger, set the base: --type-base: 14 (a unitless px number; 16 is the default). Never retune tiers one by one for it.** Every tier is authored on a 16px base and keeps its ratio to it, so one number rebuilds the whole scale, headings to captions, and the baseline step and spacing follow the body. Shrinking tiers individually breaks the ratios between them. Set it on :root, a theme scope or a preset (tokens.shared["type-base"]) so the rhythm follows too.
+10. **Inside a Workspace, a panel's title is text-ui-title (14px · 600); compact text-title-lg resolves to it. A reading view inside the tool (an overview, a document, a long form) is wrapped in <Density value="comfortable"> and gets the page tiers back.** The compact register remaps page tiers onto the 10-12px chrome ramp, which is right for chrome and wrong for prose: an issue overview set in a tool rendered its paragraphs at 11px. The remap stops at a comfortable boundary, so the wrapper is the whole fix.
+11. **A mark attached to a line of type (a dot, a bullet, a timeline marker, a leading icon) sits in a box one line tall (h-[1lh] items-center) and is sized in em.** 1lh is the line-height of the text beside it, so the mark centres on that line in every tier, density and theme. A px size with a mt-[3px] nudge is right for one font at one size and wrong everywhere else.
 
 ## Never
 
@@ -3551,6 +3707,7 @@ Every tier belongs to one family, and the family is the decision. Size follows f
 - **Never:** Uppercase in product chrome: nav and menu group labels, page eyebrows, table headers, section titles. **Instead:** Sentence-case text-caption or text-label-md in muted-foreground; hierarchy from size, weight and space. Tracked capitals spread across a UI read as shouting and slow word recognition. The eyebrow tier (label-xs / overline) is an editorial accent: at most one per marketing view.
 - **Never:** Display tiers inside product UI, or two display sizes in one view. **Instead:** heading-1 for a page title; mono-xl for a metric. Display is type as image. In chrome it competes with the content it is supposed to frame.
 - **Never:** Justified text, or reading copy below body-sm. **Instead:** Ragged-right at body-md; body-xs only for dense data. Justification opens rivers on the web, which has no hyphenation control; 12px prose fails people with low vision.
+- **Never:** Changing the root font-size (html { font-size: 14px }) to make a product denser. **Instead:** --type-base: 14, with Workspace or <Density value="compact"> for denser controls. The root also sizes every rem the app wrote: widths, insets, media queries. --type-base moves only the type and the rhythm built on it, and density moves the controls, so each can be chosen on its own.
 - **Never:** A new font family, or raw font-feature-settings / font-variation-settings. **Instead:** The theme's sans, mono and optional display; font-variant-numeric and font-weight. Raw axis tags silently do nothing on a fallback font, and every theme declares a fallback stack.
 
 ## Details
@@ -5113,7 +5270,7 @@ App-shell admin dashboard: a branded Sidebar with an account footer (AppHeader +
 ## Source
 
 ```tsx
-import { AppHeader, AppShell, Avatar, Badge, BottomNav, BottomNavItem, Button, Card, CardAction, CardContent, CardDescription, CardFooter, CardHeader, CardList, CardTitle, DataTable, Entity, Grid, Icon, MenuItem, MenuSeparator, Meter, NotificationBadge, OverflowMenu, Page, PageHeader, RelativeTime, Row, Sidebar, SidebarBrand, SidebarFooter, SidebarHeader, SidebarItem, SidebarNav, Stack } from "@sableui/react"
+import { AppHeader, AppShell, Avatar, Badge, BottomNav, BottomNavItem, Button, Card, CardAction, CardContent, CardDescription, CardFooter, CardHeader, CardList, CardTitle, DataTable, Entity, Grid, Icon, Menu, MenuContent, MenuItem, MenuSeparator, MenuTrigger, Meter, NotificationBadge, Page, PageHeader, RelativeTime, Row, Sidebar, SidebarAccount, SidebarBrand, SidebarFooter, SidebarHeader, SidebarItem, SidebarNav, Stack } from "@sableui/react"
 
 // Account status → Badge tone. Sable has no status vocabulary of its own;
 // an app maps ITS states onto tones once, here, and every badge follows.
@@ -5225,20 +5382,23 @@ export function DashboardPage() {
 						<SidebarItem icon={<Icon name="gear" />} label="Settings" render={<a href="/settings" />} />
 					</SidebarNav>
 					<SidebarFooter>
-						<Entity
-							className="[--entity-py:0]"
-							leading={<Avatar variant="art" size="sm" fallback="AL" alt="" />}
-							title="Ada Lovelace"
-							subtitle="@ada"
-							action={
-								<OverflowMenu label="Account" size="icon-sm">
-									<MenuItem render={<a href="/@ada" />}>View profile</MenuItem>
-									<MenuItem render={<a href="/settings" />}>Settings</MenuItem>
-									<MenuSeparator />
-									<MenuItem>Sign out</MenuItem>
-								</OverflowMenu>
-							}
-						/>
+						<Menu>
+							<MenuTrigger
+								render={
+									<SidebarAccount
+										avatar={<Avatar variant="art" size="xs" fallback="AL" alt="" />}
+										label="Ada Lovelace"
+										detail="@ada"
+									/>
+								}
+							/>
+							<MenuContent side="top" align="start">
+								<MenuItem render={<a href="/@ada" />}>View profile</MenuItem>
+								<MenuItem render={<a href="/settings" />}>Settings</MenuItem>
+								<MenuSeparator />
+								<MenuItem>Sign out</MenuItem>
+							</MenuContent>
+						</Menu>
 					</SidebarFooter>
 				</Sidebar>
 			}
@@ -7009,6 +7169,459 @@ export function SettingsPage() {
 
 ---
 
+# TrackerPage
+
+Records workspace in the tool register: a Sidebar rail of grouped views ending in an account menu, a WorkspaceBar of Breadcrumbs over pill Tabs, a filter row, one grouped DataTable, and a docked inspector of PanelSection property rows with a pinned comment form. Below lg the rail and the inspector become sheets and a BottomNav takes the last row.
+
+**Intent:** Reach for this when a team works through records in a dense tool — an issue tracker, a support queue, a pipeline: a grouped list, a docked inspector for the selected record, and a rail of views. For records a person reads and edits one at a time on a page, ListDetailPage is the page-register shape; for monitoring with headline numbers, DashboardPage.
+
+## Notes
+
+- Workspace sets the compact density for everything inside: 32px rail rows, 28px tables, 24px property fields. Nothing in the pattern sizes a control or a row by hand. The Overview tab is a reading view, so it sits in `<Density value="comfortable">` and its prose gets page type back.
+- The rail is Sable's own parts on one grid: SidebarBrand, SidebarGroup, SidebarItem and SidebarAccount share the icon and label columns. The account row is the trigger of the account Menu, which holds Settings, an Appearance submenu wired to useSableTheme (light, dark, system) and Sign out. No Settings button or badge sits in the footer.
+- There is no Workspace `toolbar`: the bars belong to the list column, so the inspector runs the full height beside them. The first WorkspaceBar carries Breadcrumbs; the second carries pill Tabs, a view switch in chrome, which sits beside the bar's other controls rather than drawing a rule.
+- One DataTable groups the rows (`groupBy`, `groups`): one header for every group, a StatusDot, a count and an add action per group header, and Done starting closed. The segmented ToggleGroup switches the grouping between status and assignee. Filtering to nothing swaps the table for an EmptyState with a Clear filters action.
+- Workflow states map onto StatusDot tones once (`STATUSES`), so group headers and the status Select read from one place. A product with a richer status glyph keeps that one mapping and swaps the icon.
+- The inspector is a Panel with `narrow="sheet"`: docked at 320px from lg, a right sheet below it, its content rendered once. Below lg it opens only when a row is picked (`inspecting`), so a phone never loads with a sheet over the list. Properties are PanelSection + PropertyRow with xs Select triggers and an xs DatePicker; Activity uses RelativeTime; the comment Form is pinned under the scrolling body.
+- The rail is a Panel with `narrow="sheet" side="left"`, opened from a `lg:hidden` menu button in the first bar; in the sheet the Sidebar fills its width. Workspace `bottomNav` reserves the BottomNav's row below lg, so the status bar ends above it.
+
+## Accessibility
+
+- Workspace renders a skip link to the canvas (`Skip to issues`) and WorkspaceCanvas is the main landmark; the rail and the inspector are labelled complementary regions (`Workspace navigation`, `Issue details`), and as sheets they keep those labels as their dialog titles.
+- The page has one level-1 heading (visually hidden; the breadcrumb shows the place) and the inspector's title is a level-2 heading.
+- Group header rows are real buttons with aria-expanded; rows open the inspector from the keyboard (DataTable's row activation). Every icon-only action has an accessible name and a tooltip.
+- Each SidebarGroup is a named group; the account row names the person, and its menu is a standard Menu with a radio group for the colour mode.
+
+## Source
+
+```tsx
+import { useState } from "react"
+import { Avatar, Badge, BottomNav, BottomNavItem, BreadcrumbItem, BreadcrumbLink, BreadcrumbPage, Breadcrumbs, BreadcrumbSeparator, Button, DataTable, DatePicker, Density, EmptyState, Form, Icon, Kbd, Menu, MenuContent, MenuItem, MenuRadioGroup, MenuRadioItem, MenuSeparator, MenuSubmenu, MenuSubmenuTrigger, MenuTrigger, Panel, PanelGroup, PanelSection, PropertyRow, RelativeTime, SearchInput, Select, SelectContent, SelectItem, SelectTrigger, Sidebar, SidebarAccount, SidebarBrand, SidebarFooter, SidebarGroup, SidebarHeader, SidebarItem, SidebarNav, SimpleTooltip, StatusBar, StatusBarGroup, StatusDot, Tabs, TabsList, TabsPanel, TabsTrigger, Textarea, Toggle, ToggleGroup, useBelowBreakpoint, useSableTheme, Workspace, WorkspaceBar, WorkspaceCanvas, type DataTableColumn } from "@sableui/react"
+
+// Workflow states → StatusDot tones, mapped once here so every group header,
+// row and select follows. Sable has no status vocabulary of its own.
+const STATUSES = [
+	{ key: "progress", label: "In progress", tone: "warning" },
+	{ key: "review", label: "In review", tone: "2" },
+	{ key: "todo", label: "Todo", tone: "neutral" },
+	{ key: "done", label: "Done", tone: "success" },
+] as const
+type Status = (typeof STATUSES)[number]["key"]
+
+const PRIORITIES = ["Urgent", "High", "Medium", "Low"] as const
+type Priority = (typeof PRIORITIES)[number]
+
+const people: Record<string, string> = {
+	AK: "Ama Kusi",
+	JR: "Jonas Reiter",
+	LM: "Lena Moreau",
+	TO: "Tomás Ortega",
+}
+
+const MIN = 60 * 1000
+const HOUR = 60 * MIN
+const DAY = 24 * HOUR
+const isoDay = (offset: number) => {
+	const d = new Date(Date.now() + offset)
+	return new Date(d.getFullYear(), d.getMonth(), d.getDate())
+}
+
+type Note = { id: string; who: string; text: string; at: number }
+type Issue = {
+	id: string
+	title: string
+	detail: string
+	status: Status
+	priority: Priority
+	assignee: string
+	label: string
+	due: Date
+	notes: Note[]
+}
+
+const initialIssues: Issue[] = [
+	{ id: "FW-104", title: "Sync offline edits when the app reconnects", detail: "Edits made offline are queued but replayed out of order after a reconnect. Replay them by timestamp and surface conflicts.", status: "progress", priority: "Urgent", assignee: "AK", label: "Sync", due: isoDay(2 * DAY), notes: [{ id: "n1", who: "JR", text: "Repro steps are in the test plan. It only happens after a cold start.", at: -3 * HOUR }] },
+	{ id: "FW-105", title: "Onboarding checklist on first launch", detail: "Three steps: connect a calendar, invite a teammate, create a first project.", status: "progress", priority: "Medium", assignee: "LM", label: "Onboarding", due: isoDay(5 * DAY), notes: [] },
+	{ id: "FW-108", title: "Push notification settings per project", detail: "Let people mute a project without muting the workspace.", status: "review", priority: "High", assignee: "TO", label: "Notifications", due: isoDay(1 * DAY), notes: [] },
+	{ id: "FW-110", title: "Crash when attaching a large photo", detail: "Photos over 20 MB crash the uploader on older devices.", status: "review", priority: "Urgent", assignee: "JR", label: "Bug", due: isoDay(-1 * DAY), notes: [] },
+	{ id: "FW-112", title: "Search across archived projects", detail: "Archived projects are left out of search today.", status: "todo", priority: "Low", assignee: "AK", label: "Search", due: isoDay(9 * DAY), notes: [] },
+	{ id: "FW-113", title: "Keyboard shortcuts for the board view", detail: "J and K move between cards; C creates an issue in the focused column.", status: "todo", priority: "Medium", assignee: "LM", label: "Board", due: isoDay(12 * DAY), notes: [] },
+	{ id: "FW-114", title: "Export a project as CSV", detail: "One row per issue, with status, assignee and dates.", status: "todo", priority: "Low", assignee: "TO", label: "Export", due: isoDay(14 * DAY), notes: [] },
+	{ id: "FW-101", title: "Dark mode for the widget", detail: "The home-screen widget ignores the system appearance.", status: "done", priority: "Medium", assignee: "JR", label: "Widget", due: isoDay(-4 * DAY), notes: [] },
+]
+
+const MODE_LABEL = { light: "Light", dark: "Dark", system: "System" } as const
+
+/** One icon-only action with a visible name on hover and focus. */
+export function TrackerPage() {
+	const [issues, setIssues] = useState(initialIssues)
+	const [selectedId, setSelectedId] = useState<string | null>("FW-104")
+	// Below lg the inspector is a sheet; it opens only when someone picks a row,
+	// so a phone does not load with a sheet over the list.
+	const [inspecting, setInspecting] = useState(false)
+	const [navOpen, setNavOpen] = useState(false)
+	const [query, setQuery] = useState("")
+	const [priority, setPriority] = useState<"all" | Priority>("all")
+	const [groupBy, setGroupBy] = useState<"status" | "assignee">("status")
+	const [tab, setTab] = useState("issues")
+	const [draft, setDraft] = useState("")
+	const narrow = useBelowBreakpoint("lg")
+	const { preference, setPreference } = useSableTheme()
+
+	const needle = query.trim().toLowerCase()
+	const visible = issues.filter(
+		(i) =>
+			(priority === "all" || i.priority === priority) &&
+			`${i.id} ${i.title} ${i.label}`.toLowerCase().includes(needle),
+	)
+	const selected = issues.find((i) => i.id === selectedId) ?? null
+	const done = issues.filter((i) => i.status === "done").length
+
+	function update(id: string, patch: Partial<Issue>) {
+		setIssues((all) => all.map((i) => (i.id === id ? { ...i, ...patch } : i)))
+	}
+	function open(id: string) {
+		setSelectedId(id)
+		setInspecting(true)
+	}
+	function close() {
+		setInspecting(false)
+		if (!narrow) setSelectedId(null)
+	}
+	function addIssue(status: Status = "todo") {
+		const id = `FW-${115 + issues.length}`
+		setIssues((all) => [
+			...all,
+			{ id, title: "New issue", detail: "", status, priority: "Medium", assignee: "AK", label: "Triage", due: isoDay(7 * DAY), notes: [] },
+		])
+		open(id)
+	}
+	function addNote() {
+		if (!selected || !draft.trim()) return
+		update(selected.id, { notes: [...selected.notes, { id: `n${Date.now()}`, who: "AK", text: draft.trim(), at: 0 }] })
+		setDraft("")
+	}
+
+	const columns: DataTableColumn<Issue>[] = [
+		{ key: "id", header: "ID", className: "w-20 whitespace-nowrap", cell: (i) => <span className="text-ui-num text-muted-foreground">{i.id}</span> },
+		{ key: "title", header: "Issue", className: "w-full max-w-0", cell: (i) => <span className="block truncate">{i.title}</span> },
+		{ key: "label", header: "Label", className: "w-28 max-sm:hidden", cell: (i) => <Badge appearance="outline" size="sm">{i.label}</Badge> },
+		{ key: "due", header: "Due", className: "w-20 whitespace-nowrap max-sm:hidden", sortValue: (i) => i.due.getTime(), cell: (i) => <span className="text-muted-foreground">{i.due.toLocaleDateString("en-US", { month: "short", day: "numeric" })}</span> },
+		{ key: "assignee", header: <span className="sr-only">Assignee</span>, className: "w-10", cell: (i) => <Avatar size="2xs" fallback={i.assignee} alt={people[i.assignee]} /> },
+	]
+
+	const groups =
+		groupBy === "status"
+			? STATUSES.map((s) => ({
+					key: s.key,
+					label: s.label,
+					icon: <StatusDot tone={s.tone} />,
+					action: <SimpleTooltip content={`Add to ${s.label}`}><Button size="icon-xs" variant="ghost" aria-label={`Add to ${s.label}`} onClick={() => addIssue(s.key)}><Icon name="plus" /></Button></SimpleTooltip>,
+					defaultExpanded: s.key !== "done",
+				}))
+			: Object.entries(people).map(([key, name]) => ({
+					key,
+					label: name,
+					icon: <Avatar size="2xs" fallback={key} alt="" />,
+				}))
+
+	const sidebar = (
+		<Sidebar variant="inline" className="h-full w-full">
+			<SidebarHeader>
+				<SidebarBrand mark={<Avatar shape="square" size="2xs" tone="teal" fallback="F" alt="" />} label="Fieldwork" />
+				<Button variant="outline" size="sm" className="basis-full justify-between">
+					<span className="flex items-center gap-2">
+						<Icon name="search" />
+						Search
+					</span>
+					<Kbd>Ctrl K</Kbd>
+				</Button>
+			</SidebarHeader>
+			<SidebarNav aria-label="Workspace">
+				<SidebarItem icon={<Icon name="inbox" />} label="Inbox" badge={<span className="text-ui-num text-muted-foreground">3</span>} />
+				<SidebarItem icon={<Icon name="circle-check" />} label="My issues" />
+				<SidebarGroup label="Mobile app">
+					<SidebarItem icon={<Icon name="layers" />} label="Issues" active />
+					<SidebarItem icon={<Icon name="refresh" />} label="Cycles" />
+					<SidebarItem icon={<Icon name="archive" />} label="Backlog" />
+				</SidebarGroup>
+				<SidebarGroup label="Workspace">
+					<SidebarItem icon={<Icon name="folder" />} label="Projects" />
+					<SidebarItem icon={<Icon name="users" />} label="Members" />
+				</SidebarGroup>
+			</SidebarNav>
+			<SidebarFooter>
+				<Menu>
+					<MenuTrigger
+						render={<SidebarAccount avatar={<Avatar size="2xs" fallback="AK" alt="" />} label="Ama Kusi" detail="Fieldwork · Admin" />}
+					/>
+					<MenuContent side="top" align="start">
+						<MenuItem icon={<Icon name="gear" />}>Settings</MenuItem>
+						<MenuSubmenu>
+							<MenuSubmenuTrigger
+								icon={<Icon name={preference === "dark" ? "moon" : preference === "light" ? "sun" : "desktop"} />}
+								value={MODE_LABEL[preference]}
+							>
+								Appearance
+							</MenuSubmenuTrigger>
+							<MenuContent side="inline-end">
+								<MenuRadioGroup value={preference} onValueChange={(v) => setPreference(v as typeof preference)}>
+									<MenuRadioItem value="light">Light</MenuRadioItem>
+									<MenuRadioItem value="dark">Dark</MenuRadioItem>
+									<MenuRadioItem value="system">System</MenuRadioItem>
+								</MenuRadioGroup>
+							</MenuContent>
+						</MenuSubmenu>
+						<MenuSeparator />
+						<MenuItem icon={<Icon name="logout" />}>Sign out</MenuItem>
+					</MenuContent>
+				</Menu>
+			</SidebarFooter>
+		</Sidebar>
+	)
+
+	const list =
+		visible.length === 0 ? (
+			<EmptyState
+				icon={<Icon name="search" />}
+				title="No issues match"
+				description="Try another search, or clear the priority filter."
+				action={
+					<Button
+						variant="secondary"
+						size="sm"
+						onClick={() => {
+							setQuery("")
+							setPriority("all")
+						}}
+					>
+						Clear filters
+					</Button>
+				}
+			/>
+		) : (
+			<DataTable
+				columns={columns}
+				data={visible}
+				rowKey={(i) => i.id}
+				groupBy={(i) => (groupBy === "status" ? i.status : i.assignee)}
+				groups={groups}
+				onRowClick={(i) => open(i.id)}
+				// A phone shows the selection only while its sheet is open.
+				isRowSelected={(i) => i.id === selectedId && (!narrow || inspecting)}
+			/>
+		)
+
+	const inspector = selected ? (
+		<div className="flex h-full min-h-0 flex-col">
+			<WorkspaceBar className="justify-between">
+				<span className="text-ui-num text-muted-foreground">{selected.id}</span>
+				<SimpleTooltip content="Close issue"><Button size="icon-xs" variant="ghost" aria-label="Close issue" onClick={close}><Icon name="xmark" /></Button></SimpleTooltip>
+			</WorkspaceBar>
+			<div className="min-h-0 flex-1 overflow-y-auto scrollbar-quiet">
+				<div className="flex flex-col gap-2 px-2 pt-4 pb-3">
+					<h2 className="text-title-lg">{selected.title}</h2>
+					<p className="text-ui-body text-muted-foreground">{selected.detail || "Add the details the team needs."}</p>
+				</div>
+				<PanelSection title="Properties">
+					<PropertyRow label="Status">
+						<Select value={selected.status} items={STATUSES.map((s) => ({ value: s.key, label: s.label }))} onValueChange={(v) => v && update(selected.id, { status: v as Status })}>
+							<SelectTrigger size="xs" aria-label="Status" />
+							<SelectContent>
+								{STATUSES.map((s) => (
+									<SelectItem key={s.key} value={s.key}>{s.label}</SelectItem>
+								))}
+							</SelectContent>
+						</Select>
+					</PropertyRow>
+					<PropertyRow label="Priority">
+						<Select value={selected.priority} onValueChange={(v) => v && update(selected.id, { priority: v as Priority })}>
+							<SelectTrigger size="xs" aria-label="Priority" />
+							<SelectContent>
+								{PRIORITIES.map((p) => (
+									<SelectItem key={p} value={p}>{p}</SelectItem>
+								))}
+							</SelectContent>
+						</Select>
+					</PropertyRow>
+					<PropertyRow label="Assignee">
+						<Select value={selected.assignee} items={people} onValueChange={(v) => v && update(selected.id, { assignee: v })}>
+							<SelectTrigger size="xs" aria-label="Assignee" />
+							<SelectContent>
+								{Object.entries(people).map(([key, name]) => (
+									<SelectItem key={key} value={key}>{name}</SelectItem>
+								))}
+							</SelectContent>
+						</Select>
+					</PropertyRow>
+					<PropertyRow label="Due date">
+						<DatePicker
+							size="xs"
+							aria-label="Due date"
+							value={selected.due}
+							formatOptions={{ month: "short", day: "numeric", year: "numeric" }}
+							onValueChange={(d) => d && update(selected.id, { due: d })}
+						/>
+					</PropertyRow>
+				</PanelSection>
+				<PanelSection title="Activity">
+					<div className="flex flex-col gap-3 pb-4">
+						<div className="flex items-center gap-2 text-ui-sm text-muted-foreground">
+							<Icon name="plus" />
+							<span>Created in Mobile app</span>
+						</div>
+						{selected.notes.map((n) => (
+							<div key={n.id} className="flex items-start gap-2">
+								<Avatar size="2xs" fallback={n.who} alt="" />
+								<div className="min-w-0">
+									<div className="flex items-center gap-2">
+										<span className="text-ui-md">{people[n.who]}</span>
+										<RelativeTime date={new Date(Date.now() + n.at)} className="text-ui-sm text-muted-foreground" />
+									</div>
+									<p className="mt-1 text-ui-body">{n.text}</p>
+								</div>
+							</div>
+						))}
+					</div>
+				</PanelSection>
+			</div>
+			<Form
+				className="flex shrink-0 flex-col gap-2 border-t border-hairline p-2"
+				onSubmit={(e) => {
+					e.preventDefault()
+					addNote()
+				}}
+			>
+				<Textarea aria-label="Add a comment" placeholder="Leave a comment…" rows={2} value={draft} onChange={(e) => setDraft(e.target.value)} />
+				<Button size="xs" variant="secondary" type="submit" className="self-end" disabled={!draft.trim()} iconStart={<Icon name="arrow-up" />}>
+					Comment
+				</Button>
+			</Form>
+		</div>
+	) : null
+
+	return (
+		<Workspace
+			skipLinkLabel="Skip to issues"
+			statusBar={
+				<StatusBar>
+					<span className="flex items-center gap-2">
+						<StatusDot tone="success" size="sm" />
+						Saved
+					</span>
+					<span className="max-sm:hidden">
+						{issues.length} issues · {done} done
+					</span>
+					<StatusBarGroup align="end">
+						<span className="max-sm:hidden">Ctrl K to search</span>
+					</StatusBarGroup>
+				</StatusBar>
+			}
+			bottomNav={
+				<BottomNav aria-label="Primary">
+					<BottomNavItem icon={<Icon name="inbox" />} label="Inbox" showLabel />
+					<BottomNavItem icon={<Icon name="layers" />} label="Issues" showLabel active />
+					<BottomNavItem icon={<Icon name="folder" />} label="Projects" showLabel />
+					<BottomNavItem icon={<Icon name="users" />} label="Members" showLabel />
+				</BottomNav>
+			}
+		>
+			<PanelGroup>
+				{/* Docked from lg; below it the same rail is a left sheet. */}
+				<Panel label="Workspace navigation" width={232} narrow="sheet" side="left" open={narrow ? navOpen : true} onOpenChange={setNavOpen} scroll={false}>
+					{sidebar}
+				</Panel>
+				<WorkspaceCanvas className="flex flex-col">
+					<WorkspaceBar className="gap-2 px-3">
+						<span className="lg:hidden">
+							<SimpleTooltip content="Open navigation"><Button size="icon-xs" variant="ghost" aria-label="Open navigation" onClick={() => setNavOpen(true)}><Icon name="bars" /></Button></SimpleTooltip>
+						</span>
+						<h1 className="sr-only">Mobile app issues</h1>
+						<Breadcrumbs className="min-w-0">
+							<BreadcrumbItem className="max-sm:hidden">
+								<BreadcrumbLink href="#">Fieldwork</BreadcrumbLink>
+							</BreadcrumbItem>
+							<BreadcrumbSeparator className="max-sm:hidden" />
+							<BreadcrumbItem>
+								<BreadcrumbPage>Mobile app</BreadcrumbPage>
+							</BreadcrumbItem>
+						</Breadcrumbs>
+					</WorkspaceBar>
+					<Tabs value={tab} onValueChange={(v) => setTab(String(v))} className="flex min-h-0 flex-1 flex-col">
+						{/* A view switch in tool chrome: pill, beside the bar's other controls. */}
+						<WorkspaceBar className="px-3">
+							<TabsList variant="pill">
+								<TabsTrigger value="issues">
+									Issues <span className="text-ui-num text-muted-foreground">{issues.length}</span>
+								</TabsTrigger>
+								<TabsTrigger value="overview">Overview</TabsTrigger>
+							</TabsList>
+						</WorkspaceBar>
+						<TabsPanel value="issues" className="flex min-h-0 flex-1 flex-col">
+							<div className="flex flex-wrap items-center gap-2 border-b border-hairline px-3 py-2">
+								<Menu>
+									<MenuTrigger render={<Button variant="ghost" size="xs" iconStart={<Icon name="filter" />}>{priority === "all" ? "Filter" : priority}</Button>} />
+									<MenuContent>
+										<MenuRadioGroup value={priority} onValueChange={(v) => setPriority(v as typeof priority)}>
+											<MenuRadioItem value="all">All priorities</MenuRadioItem>
+											{PRIORITIES.map((p) => (
+												<MenuRadioItem key={p} value={p}>{p}</MenuRadioItem>
+											))}
+										</MenuRadioGroup>
+									</MenuContent>
+								</Menu>
+								<SearchInput size="xs" value={query} onValueChange={setQuery} placeholder="Find issue…" aria-label="Find issue" className="w-40" />
+								<ToggleGroup appearance="segmented" value={[groupBy]} onValueChange={(v) => v[0] && setGroupBy(v[0] as typeof groupBy)} aria-label="Group by" className="ms-auto">
+									<Toggle value="status">Status</Toggle>
+									<Toggle value="assignee">Assignee</Toggle>
+								</ToggleGroup>
+								<Button size="xs" iconStart={<Icon name="plus" />} onClick={() => addIssue()}>
+									New issue
+								</Button>
+							</div>
+							<div className="min-h-0 flex-1 overflow-y-auto scrollbar-quiet">{list}</div>
+						</TabsPanel>
+						<TabsPanel value="overview" className="flex min-h-0 flex-1 flex-col">
+							{/* A reading view: page type comes back inside the compact workspace. */}
+							<Density value="comfortable" className="min-h-0 flex-1 overflow-y-auto scrollbar-quiet">
+								<article className="flex max-w-prose flex-col gap-4 p-8 max-sm:p-5">
+									<h2 className="text-heading-3">Mobile app</h2>
+									<p className="text-body-md text-muted-foreground">
+										The phone app for field teams: capture work on site, sync it when the signal comes back, and hand it to the office without retyping anything.
+									</p>
+									<dl className="sable-list-dl">
+										<dt>Lead</dt>
+										<dd>{people.AK}</dd>
+										<dt>Open issues</dt>
+										<dd>{issues.length - done}</dd>
+										<dt>Target</dt>
+										<dd>{isoDay(30 * DAY).toLocaleDateString("en-US", { month: "long", day: "numeric" })}</dd>
+									</dl>
+								</article>
+							</Density>
+						</TabsPanel>
+					</Tabs>
+				</WorkspaceCanvas>
+				{/* Docked beside the list from lg; a sheet below it. Its content renders once. */}
+				<Panel
+					label="Issue details"
+					width={320}
+					narrow="sheet"
+					open={narrow ? inspecting && selected !== null : selected !== null}
+					onOpenChange={(next) => !next && close()}
+					scroll={false}
+					className="border-s border-hairline"
+				>
+					{inspector}
+				</Panel>
+			</PanelGroup>
+		</Workspace>
+	)
+}
+```
+
+---
+
 # ApiKeysBlock
 
 An API keys card: each key's name with its masked hint in Code, when it was created and last used, and an OverflowMenu to rename, roll or revoke.
@@ -10317,7 +10930,7 @@ export function WalletBlock({ className, framed = true, onSend, onReceive }: Wal
 
 **Status:** stable
 
-The page region: fluid, edge-to-edge with the fluid page inset (--page-inset). Opt-in centered max cap picked by ROLE (prose/form/feed/content/wide/full), never a global page max-width. The root of nearly every route.
+The page region: fluid, edge-to-edge with the fluid page inset (--page-inset). Opt-in centered max cap picked by ROLE (prose/form/feed/content/wide/full), never a global page max-width. The root of nearly every route. The inset and cap are classes (px-(--page-inset), max-w-…), so className overrides them at a breakpoint (max-sm:px-0); only safeArea padding is inline.
 
 **Keywords:** region, page width, container, layout
 
@@ -10424,7 +11037,7 @@ import { Card, CardContent, Page, PageHeader } from "@sableui/react"
 
 **Status:** stable
 
-CSS Grid within a region. Two modes: fixed/responsive cols count, or minItemWidth so cells breathe with NO breakpoints (the default choice for card grids). A minItemWidth grid keeps its empty columns (track="fill"), so one result stays one cell wide; track="fit" stretches a fixed set across the row.
+CSS Grid within a region. Two modes: fixed/responsive cols count, or minItemWidth so cells breathe with NO breakpoints (the default choice for card grids). A minItemWidth grid keeps its empty columns (track="fill"), so one result stays one cell wide; track="fit" stretches a fixed set across the row. display is the grid class and the gap a CSS variable, so className utilities win at any breakpoint (hidden md:grid, md:gap-6, lg:grid-cols-3).
 
 **Keywords:** grid, card grid, auto fit, layout
 
@@ -10495,7 +11108,7 @@ import { Badge, Grid } from "@sableui/react"
 
 **Status:** stable
 
-An explicit N-column track (default 12) for proportioned layouts — pair with Col spans (list-detail, asymmetric editorial layouts). For uniform card grids prefer Grid minItemWidth.
+An explicit N-column track (default 12) for proportioned layouts — pair with Col spans (list-detail, asymmetric editorial layouts). For uniform card grids prefer Grid minItemWidth. display is the grid class, so hidden md:grid works; a gap-* utility replaces both gaps and the column-gap cap.
 
 **Keywords:** columns, 12 column, span, layout
 
@@ -10549,7 +11162,7 @@ import { Card, CardHeader, CardTitle, Col, Columns } from "@sableui/react"
 
 **Status:** stable
 
-Vertical flow on the 8px rhythm — the default container for stacked content. Gap by role: tight within a group (1.5–2), looser between groups (3–4), generous between sections (6+).
+Vertical flow on the 8px rhythm — the default container for stacked content. Gap by role: tight within a group (1.5–2), looser between groups (3–4), generous between sections (6+). Layout lives in classes (flex flex-col items-* justify-*) and the gap in a CSS variable, never inline style, so className utilities override any prop at a breakpoint (max-lg:hidden, md:flex-row, md:gap-8).
 
 **Keywords:** stack, vertical rhythm, layout, spacing
 
@@ -10591,7 +11204,7 @@ import { Field, Input, Stack, Textarea } from "@sableui/react"
 
 **Status:** stable
 
-Horizontal flex flow — inline rows of controls, toolbars, action clusters. Defaults to center-aligned, no wrap.
+Horizontal flex flow — inline rows of controls, toolbars, action clusters. Defaults to center-aligned, no wrap. Layout lives in classes (flex flex-row items-* justify-*) and the gap in a CSS variable, never inline style, so className utilities override any prop at a breakpoint (hidden md:flex, max-md:flex-col, md:gap-6).
 
 **Keywords:** row, toolbar, horizontal, layout
 
@@ -10628,13 +11241,21 @@ import { Button, Row } from "@sableui/react"
 <Row gap={2} justify="end"><Button variant="ghost">Cancel</Button><Button>Save changes</Button></Row>
 ```
 
+### Responsive through className
+
+```tsx
+import { Button, Row } from "@sableui/react"
+
+<Row justify="between"><span className="text-title-sm">Acme</span><Row gap={1} className="max-md:hidden"><Button variant="ghost" size="sm">Docs</Button><Button variant="ghost" size="sm">Pricing</Button></Row></Row>
+```
+
 ---
 
 # Spacer
 
 **Status:** stable
 
-Explicit space on the rhythm, or a flexible grow pusher between siblings (e.g. pushing a footer item to the end of a Row).
+Explicit space on the rhythm, or a flexible grow pusher between siblings (e.g. pushing a footer item to the end of a Row). The size is a class reading a CSS variable, so className resizes or hides it at a breakpoint.
 
 **Keywords:** spacer, spacing, grow, layout
 
@@ -10676,7 +11297,7 @@ import { Button, Row, Spacer } from "@sableui/react"
 
 **Status:** stable
 
-Horizontally center a block, optionally capping its width (commonly "prose" for a reading column inside a wider layout).
+Horizontally center a block, optionally capping its width (commonly "prose" for a reading column inside a wider layout). Centering and cap are classes, so className overrides them at a breakpoint.
 
 **Keywords:** center, measure, reading width, layout
 
@@ -10716,7 +11337,7 @@ import { Center } from "@sableui/react"
 
 **Status:** stable
 
-Reserves space via aspect-ratio so async media loads with zero layout shift. Wrap images, video, embeds.
+Reserves space via aspect-ratio so async media loads with zero layout shift. Wrap images, video, embeds. The ratio is a class reading a CSS variable, so className reshapes it at a breakpoint (md:aspect-video).
 
 **Keywords:** aspect box, aspect ratio, media, layout shift
 
@@ -10756,7 +11377,7 @@ import { AspectBox } from "@sableui/react"
 
 **Status:** stable
 
-Escape a width-capped or inset ancestor to span the full CONTENT area (container-query units, so it stops at a fixed Sidebar instead of bleeding under it). Hero bands, profile covers, full-bleed media inside a capped Page.
+Escape a width-capped or inset ancestor to span the full CONTENT area (container-query units, so it stops at a fixed Sidebar instead of bleeding under it). Hero bands, profile covers, full-bleed media inside a capped Page. Width and margins are classes, so a breakpoint can turn the bleed off (lg:mx-0 lg:w-auto).
 
 **Keywords:** bleed, full bleed, media band, layout
 
@@ -10790,7 +11411,7 @@ import { AspectBox, Bleed, Page, PageHeader } from "@sableui/react"
 
 **Status:** stable
 
-Responsive two-pane layout: side-by-side at/above a breakpoint, stacked (primary first) below. List-detail, media + metadata.
+Responsive two-pane layout: side-by-side at/above a breakpoint, stacked (primary first) below. List-detail, media + metadata. display is the grid class and the breakpoint rules are layered, so className utilities (hidden lg:grid, gap-8) win.
 
 **Keywords:** split pane, two pane, list detail, responsive
 
@@ -11010,6 +11631,142 @@ import { Accordion, AccordionItem, AccordionPanel, AccordionTrigger, Icon } from
 
 ---
 
+# ActivityHeatmap
+
+**Status:** stable
+
+A calendar heatmap: one value per day as a grid of weeks by weekdays — the GitHub contribution graph, for any daily measure. Levels by quartile, categories by source, a real ARIA grid with one tab stop, and a sideways scroll on narrow screens that opens on the latest week.
+
+**Keywords:** heatmap, calendar heatmap, contribution graph, contributions, activity, github, streak, habit, daily, commits, uptime
+
+## Usage
+
+Use ActivityHeatmap to show how often something happened day by day over weeks or months: commits, habits kept, orders, uptime. Pass days as ISO dates with a value; levels, colours, labels, keyboard and tooltips work with no further props. Put it inside a Card and compose any totals beside it (NumberTicker, StatRowBlock). For a value over time that a reader needs to compare precisely, use AreaChart or BarChart; for a month calendar with marked days (a streak calendar), use Calendar.
+
+### Best practices
+
+- Do: Pass dates as "YYYY-MM-DD" strings. The grid reads them as calendar days, so no time zone can shift a day — never build them with `new Date(...).toISOString()` from a local date.
+- Do: Give it a `unit` ("contribution" / "contributions") so the tooltip and every cell's name say what the number counts.
+- Do: Let the default quantile scale pick levels — one exceptional day then does not wash every other day out. Pass a day's own `level` when the source already has one (GitHub's API).
+- Don't: Use it for a handful of values or for values a reader must compare exactly; a heatmap shows rhythm, not amounts. Use BarChart. → use **BarChart**, **AreaChart**
+- Don't: Use it for a single month of marked days with a streak; that is Calendar with modifiers. → use **Calendar**
+- Don't: Fetch inside the component or call GitHub from the browser with a token. Fetch on your server and pass days in; `@sableui/react/adapters/github` converts GitHub's response.
+
+### Anatomy
+
+| Part | Required | Description |
+| --- | --- | --- |
+| Weekday labels | no | Short weekday names beside the rows, outside the scroller so the weeks never slide under them. |
+| Month labels | no | Short month names over each month's first week; they scroll with their weeks. |
+| Cell grid | yes | A role=grid table, one gridcell per day, inside a horizontal Scroller that opens on the latest week. |
+| Tooltip | no | The chart tooltip card, anchored to the hovered, focused or tapped day. |
+| Legend | no | A Less–More ramp for intensity, or swatches for categories. |
+
+## Props
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| label | string | — | What the grid shows ("Contributions in 2026") — its caption and accessible name. |
+| data | ActivityDay[] \| Record<string, number> | — | The days: `{ date: "YYYY-MM-DD", value, level?, category? }[]`, or a map of date to value. Sparse is fine — a missing day is 0; duplicates sum. |
+| start | string | 53 weeks before end | First day drawn, "YYYY-MM-DD". The default starts at the beginning of that week, as GitHub's does. |
+| end | string | today | Last day drawn. Days after today inside the range are drawn hollow and skipped by the keyboard. |
+| year | number | — | Draw Jan 1 – Dec 31 of this year. Wins over start / end. |
+| weekStart | 0 \| 1 | the locale's | 0 puts Sunday on the top row, 1 Monday. |
+| levels | number | 5 | How many levels, including the empty level 0. |
+| levelScale | "quantile" \| "linear" \| number[] \| ((value, stats) => number) | "quantile" | How a value becomes a level. Quantile splits the positive values evenly, as GitHub does; an array gives each level's lower bound from 1 up; a function decides. A day's own `level` always wins. |
+| tone | ChartTone | "1" | The hue of the intensity ramp. Decorative tones lead, as on every chart; "success" gives the GitHub look. |
+| categories | ChartCategories | — | Colour days by `day.category` (label, tone or colour per key). Pair with `levels={2}` for flat category colours. |
+| unit | string \| { one: string; other: string } | — | Names the value in the tooltip and each cell's accessible name, pluralised with Intl.PluralRules. |
+| formatValue | (value: number) => string | full to 9,999, compact past | Formats a value wherever it is shown or read. |
+| tooltip | boolean \| ((day: ActivityHeatmapDay) => ReactNode) | true | Show the tooltip on hover, focus and tap; a function replaces its content on the same card. |
+| legend | boolean | true | The Less–More ramp for intensity, swatches for categories. |
+| legendLabels | [string, string] | ["Less", "More"] | The ramp's end words. |
+| monthLabels | boolean | true | Short month names over each month's first week. |
+| weekdayLabels | "alternate" \| "all" \| "none" | "alternate" | Which weekday names to show beside the rows; alternate is Mon, Wed, Fri. |
+| size | "sm" \| "md" \| "lg" | "md" | The smallest a cell may get (10, 12, 14 px) before the grid scrolls instead of shrinking. |
+| stretch | boolean | true | Grow cells to fill the width, up to 20 px. false keeps them at `size`. |
+| activeDate | string \| null | — | The hovered or focused day, controlled. Pair with defaultActiveDate / onActiveDateChange. |
+| selectedDate | string \| null | — | The selected day, controlled. Selection is on only when onSelectDate is set. |
+| onSelectDate | (date: string) => void | — | Called when a day is clicked or chosen with Enter / Space — to filter a feed below, as GitHub does. |
+| renderCell | (day, cell) => ReactNode | — | Draw something over a cell's fill — an icon for a milestone, a reward, an outage. |
+| loading | boolean | false | Draw the empty grid, shimmering, while data loads. |
+| motion | "full" \| "subtle" \| "off" | "full" | Turns the arrival down; `subtle` shows the finished grid at once. |
+| locale | string | runtime locale | Month and weekday names, numbers and plurals. |
+
+## Tokens used
+
+`foreground`, `muted-foreground`, `border-strong`, `ring`, `tone-1-mark`, `tone-2-mark`, `tone-3-mark`, `success-mark`, `tone-info-mark`
+
+## Motion
+
+- **arrival** · Cell grid · _custom (outside the recipe layer)_ — Weeks fade in left to right as the grid first scrolls into view, staggered on the chart motion helpers; expressive, so subtle shows the finished grid.
+- **response** · Cell · _custom (outside the recipe layer)_ — The active day takes a ring outline at once and the tooltip glides to it; the other cells stay still — dimming hundreds of cells reads as a flash.
+- **transition** · Cell · _custom (outside the recipe layer)_ — When data or the range changes, each cell's fill cross-fades on the base duration token, so the reader sees which days changed.
+- **activity** · Cell grid · `motion-shimmer` — `loading` shimmers the empty grid until days arrive.
+
+## Accessibility
+
+- The grid is a role=grid table, as GitHub's is: weekday row headers and month column headers carry full names for screen readers, and the caption is `label`.
+- One tab stop. Arrows move a day or a week; Home / End go to the ends of the row, Page Up / Page Down to the ends of the column, Ctrl+Home / Ctrl+End to the first and last day. Enter or Space selects when onSelectDate is set; Escape hides the tooltip.
+- Each cell is named with its date and value ("Tuesday, October 14, 2026: 12 contributions") and described by its level's words, which the legend repeats visually.
+- Levels rise in lightness, so they read without colour; under forced colours each level draws as a larger inner square.
+
+## Related
+
+- Components: Card, NumberTicker, BarChart, Calendar, Scroller
+
+## Examples
+
+### Contributions, last year
+
+```tsx
+import { ActivityHeatmap } from "@sableui/react"
+
+const days = [
+	{ date: "2026-10-12", value: 4 },
+	{ date: "2026-10-13", value: 11 },
+	{ date: "2026-10-14", value: 2 },
+]
+
+<ActivityHeatmap label="Contributions in the last year" data={days} tone="success" unit={{ one: "contribution", other: "contributions" }} />
+```
+
+### Two sources, in a card
+
+```tsx
+import { ActivityHeatmap, Card, CardContent, CardHeader, CardTitle, mergeActivity } from "@sableui/react"
+
+const github = [{ date: "2026-10-13", value: 6 }]
+const codex = [{ date: "2026-10-13", value: 1 }, { date: "2026-10-14", value: 3 }]
+
+<Card>
+	<CardHeader>
+		<CardTitle>Building, day by day</CardTitle>
+	</CardHeader>
+	<CardContent>
+		<ActivityHeatmap
+			label="GitHub and Codex activity in 2026"
+			year={2026}
+			levels={2}
+			data={mergeActivity({ github, codex })}
+			categories={{ github: { label: "GitHub", tone: "success" }, codex: { label: "Codex", tone: "info" }, both: { label: "Both", tone: "2" } }}
+		/>
+	</CardContent>
+</Card>
+```
+
+### Selecting a day
+
+```tsx
+import { ActivityHeatmap } from "@sableui/react"
+
+const [day, setDay] = useState<string | null>(null)
+
+<ActivityHeatmap label="Orders per day" data={{ "2026-10-13": 18, "2026-10-14": 25 }} unit="orders" selectedDate={day} onSelectDate={setDay} />
+```
+
+---
+
 # AppHeader
 
 **Status:** stable
@@ -11536,9 +12293,9 @@ import { Attachment, Message, RelativeTime } from "@sableui/react"
 
 **Status:** stable
 
-Circular profile image over Base UI Avatar — automatic image-load tracking with an initials/glyph fallback. Ergonomic Avatar plus low-level AvatarRoot/AvatarImage/AvatarFallback parts, and AvatarGroup for an overlapping stack with a "+N" overflow count.
+Circular (or square) profile image over Base UI Avatar — automatic image-load tracking with an initials/glyph fallback. Ergonomic Avatar plus low-level AvatarRoot/AvatarImage/AvatarFallback parts, and AvatarGroup for an overlapping stack with a "+N" overflow count.
 
-**Keywords:** avatar, profile, user, identity, initials, fallback, group, team, stack, overflow, collaborators, facepile
+**Keywords:** avatar, profile, user, identity, initials, fallback, group, team, stack, overflow, collaborators, facepile, monogram, project mark, workspace icon, org logo, assignee
 
 ## Usage
 
@@ -11549,12 +12306,13 @@ Use Avatar to represent a person, team, or account with a compact visual identit
 - Do: Use `variant="art"` where people without photos sit side by side — a member list, an activity feed, a chat. Seeded by the person, each gets their own colour, so faces stay tellable apart at a glance; the neutral fallback makes everyone the same grey circle.
 - Do: Provide meaningful alt text for profile images, or an empty alt when the adjacent text already names the person.
 - Do: Use initials or a simple glyph fallback so missing images still communicate identity.
-- Do: Pick the size by the job: sm in dense rows and tables, md (the default) beside one line of text, lg in a row with a title and subtitle, xl (96px) for a profile header beside the person's name, 2xl (160px) for an artist or profile hero and roster portraits. Keep one size within a list or group.
+- Do: Pick the size by the job: 2xs (20px) or xs (24px) in a compact workspace row (an assignee in an issue list, a project mark in a nav item), sm in dense rows and tables, md (the default) beside one line of text, lg in a row with a title and subtitle, xl (96px) for a profile header beside the person's name, 2xl (160px) for an artist or profile hero and roster portraits. Keep one size within a list or group.
 - Do: Use AvatarGroup for a stack of people, and give it an aria-label with the real count ("12 collaborators"). Set `surface` (or `--avatar-group-ring`) to whatever the group sits on, so the separating ring matches a card or popover, not the page. When it shares a row with actions, set `fit` so it gives up avatars to the "+N" count before the row has to wrap.
+- Do: Use `shape="square"` for what is not a person (a workspace, a project, an org, a team), with `tone` set to a palette family so each one keeps its own colour: `<Avatar shape="square" tone="teal" fallback="N" alt="Northwind storefront" size="xs" />`. Circles mean people; keep that distinction across the app.
 - Don't: Hand-build a stack with negative margins and per-avatar ring classes, or fake the overflow as an Avatar with "+4" initials — screen readers hear "plus 4" with no context. Use AvatarGroup's `max`/`total`, or AvatarGroupCount.
 - Don't: Use avatars as decoration without nearby identity context. They should help users recognize a person or account.
 - Don't: Overload a dense table with large avatars; use sm or omit images when scanning data is more important.
-- Don't: Build a portrait by stretching an Avatar with size classes (`className="size-40"`) — the initials, the status indicator and the image fade stay at row scale. Use size="xl" or "2xl", which scale all three. Past 160px, or for a non-circular cover, it is media: an AspectBox, not an avatar.
+- Don't: Resize an Avatar with size classes (`className="size-5"`, `className="size-40"`) — the initials, the status indicator and the image fade stay at the size they were drawn for. Use size="2xs"/"xs" for dense rows and size="xl"/"2xl" for portraits, which scale all three. Don't hand-build a tinted initials tile for a project or workspace mark either: that is Avatar shape="square" with a tone. Past 160px, or for a cover, it is media: an AspectBox, not an avatar.
 
 ### Anatomy
 
@@ -11570,11 +12328,11 @@ Use Avatar to represent a person, team, or account with a compact visual identit
 
 | Name | Type | Description |
 | --- | --- | --- |
-| AvatarRoot | Base UI Avatar.Root props + size + className | Low-level circular frame for full composition control — clips the image and holds the `size` axis. Wraps AvatarImage and AvatarFallback. |
+| AvatarRoot | Base UI Avatar.Root props + size + shape + tone + className | Low-level circular frame for full composition control — clips the image and holds the `size` axis. Wraps AvatarImage and AvatarFallback. |
 | AvatarImage | Base UI Avatar.Image props + className | The profile image. Fills and crops the frame; hidden by Base UI until it loads. |
 | AvatarFallback | Base UI Avatar.Fallback props (delay) + className | Shown when no image is available — typically initials or a glyph. Accepts a delay prop. |
-| AvatarGroup | { size?: "sm" \| "md" \| "lg"; surface?: "background" \| "card" \| "popover" \| "muted"; max?: number; fit?: boolean; total?: number; countLabel?: (count: number) => string; "aria-label"?: string; className?: string; children: ReactNode } | Overlapping stack (role=group) — name it with aria-label ("12 collaborators"). `size` applies to every avatar inside. `max` shows that many and collapses the rest into a "+N" count; `total` is the real head-count when you only pass some people. `fit` shows only as many avatars as fit the width the group is given (it fills the space left in a flex row) and folds the rest into the count, so a tight row reads "MO SR +5" instead of wrapping. The separating ring reads the inherited `--avatar-group-ring` (default: the page background); `surface` sets it to card, popover, or muted. |
-| AvatarGroupCount | { count: number; label?: string; size?: "sm" \| "md" \| "lg"; className?: string } | The "+N" avatar. Shows "+4" and reads "and 4 more" (override with label). AvatarGroup renders it for you from max/total; use it directly only when composing the stack yourself. |
+| AvatarGroup | { size?: "2xs" \| "xs" \| "sm" \| "md" \| "lg"; surface?: "background" \| "card" \| "popover" \| "muted"; max?: number; fit?: boolean; total?: number; countLabel?: (count: number) => string; "aria-label"?: string; className?: string; children: ReactNode } | Overlapping stack (role=group) — name it with aria-label ("12 collaborators"). `size` applies to every avatar inside. `max` shows that many and collapses the rest into a "+N" count; `total` is the real head-count when you only pass some people. `fit` shows only as many avatars as fit the width the group is given (it fills the space left in a flex row) and folds the rest into the count, so a tight row reads "MO SR +5" instead of wrapping. The separating ring reads the inherited `--avatar-group-ring` (default: the page background); `surface` sets it to card, popover, or muted. |
+| AvatarGroupCount | { count: number; label?: string; size?: "2xs" \| "xs" \| "sm" \| "md" \| "lg"; className?: string } | The "+N" avatar. Shows "+4" and reads "and 4 more" (override with label). AvatarGroup renders it for you from max/total; use it directly only when composing the stack yourself. |
 
 ## Props
 
@@ -11585,13 +12343,16 @@ Use Avatar to represent a person, team, or account with a compact visual identit
 | fallback | ReactNode | — | Initials or a glyph rendered when no image is displayed. |
 | fallbackDelay | number | — | Delay before showing the fallback, in ms — avoids a flash on fast loads. |
 | status | ReactNode | — | A presence indicator pinned to the bottom-end edge, usually <StatusDot tone="success" />. It sits outside the clipped circle and wears a ring in the surface colour (--avatar-group-ring, else the page background). Use this instead of absolutely positioning a dot over an Avatar. |
-| size | "sm" \| "md" \| "lg" \| "xl" \| "2xl" | "md" | Square footprint: 32px / 40px / 48px for rows; 96px / 160px for portraits (a profile header, an artist hero, a roster tile). The initials, a status indicator and its cut-out ring scale with it, and at the portrait sizes the photo fades in over the resting surface. |
+| size | "2xs" \| "xs" \| "sm" \| "md" \| "lg" \| "xl" \| "2xl" | "md" | Square footprint: 20px / 24px for compact workspace rows; 32px / 40px / 48px for rows; 96px / 160px for portraits (a profile header, an artist hero, a roster tile). The initials, a status indicator and its cut-out ring scale with it, and at the portrait sizes the photo fades in over the resting surface. |
+| shape | "circle" \| "square" | "circle" | The frame's corner. circle is a person. square is what is not a face — a workspace, a project, an org, a team — with a radius from the theme's steps that grows with the size (4px at 20–24px to 20px at 160px), so a square theme stays square. A status indicator sits on the square's corner. |
+| tone | "neutral" \| "red" \| "orange" \| "yellow" \| "green" \| "teal" \| "blue" \| "purple" \| "pink" | "neutral" | The fallback's colour. neutral is the muted surface; a palette family paints its wash behind the initials and its deep ink on them (a soft Badge's pair, held to contrast in every theme), for a category colour such as one per project. Ignored by variant="art", which colours by seed. |
 | variant | "neutral" \| "art" | "neutral" | What the fallback looks like. neutral: initials on the muted surface. art: initials over GradientArt seeded by the person, so each person without a photo gets their own stable colour from the theme. |
 | seed | string \| number | — | The art variant's seed. Defaults to the fallback text, then `alt`, so a person keeps one colour wherever they appear; pass a user id to tell apart two people who share initials. |
 
 ## Variants
 
-- **size**: sm, md, lg, xl, 2xl
+- **size**: 2xs, xs, sm, md, lg, xl, 2xl
+- **shape**: circle, square
 - **variant**: neutral, art
 
 ## Tokens used
@@ -11668,6 +12429,25 @@ import { Avatar, StatusDot } from "@sableui/react"
 </div>
 ```
 
+### Dense row sizes
+
+```tsx
+import { Avatar } from "@sableui/react"
+
+<Avatar fallback="EL" alt="Emma Lee" size="2xs" />
+<Avatar fallback="EL" alt="Emma Lee" size="xs" />
+```
+
+### Project marks
+
+```tsx
+import { Avatar } from "@sableui/react"
+
+<Avatar shape="square" tone="teal" size="xs" fallback="N" alt="Northwind storefront" />
+<Avatar shape="square" tone="orange" size="xs" fallback="H" alt="Harbor brand refresh" />
+<Avatar shape="square" tone="purple" size="xs" fallback="L" alt="Lumen editorial" />
+```
+
 ### Low-level parts
 
 ```tsx
@@ -13674,6 +14454,7 @@ Use CodeBlock for multiline code samples that users may read, inspect, or copy.
 | showCopy | boolean | true | Show the copy affordance — in the header bar with a filename, floating in the corner without one. |
 | highlight | ((code: string) => ReactNode) \| false | — | Highlighter for this block; overrides CodeHighlightProvider. false renders plain text inside a provider. |
 | prompt | string | — | A shell prompt ("$", ">"). Makes it a one-line command: the prompt is dimmed and unselectable, the line truncates, and copy takes only code. |
+| wrap | boolean | false | Wrap long lines instead of scrolling them. For prose in a code face (a prompt to paste into an agent, a log line); code keeps scrolling, since wrapping breaks its indentation. |
 
 ## Tokens used
 
@@ -13730,7 +14511,7 @@ import { CodeBlock } from "@sableui/react"
 
 Show/hide a panel of content over Base UI Collapsible — open/close state, ARIA expanded wiring, and the animated height transition. The minimal primitive behind Accordion: a trigger that toggles an overflow-clipped panel.
 
-**Keywords:** collapsible, disclosure, expand, collapse
+**Keywords:** collapsible, disclosure, expand, collapse, chevron, caret, rotate, group header, section toggle
 
 ## Usage
 
@@ -13757,7 +14538,7 @@ Use Collapsible for a single piece of optional content that can expand in place.
 | --- | --- | --- |
 | CollapsibleTrigger | Base UI Collapsible.Trigger props + render | The button that toggles the panel. Compose with render={<Button variant="ghost" … />}. |
 | CollapsiblePanel | Base UI Collapsible.Panel props + className (keepMounted, hiddenUntilFound) | The collapsible contents. Overflow-hidden; animates height via the --collapsible-panel-height var Base UI sets. |
-| CollapsibleIndicator | { className? } | Auto-rotating disclosure chevron. Place it inside the trigger content and add the `group/collapsible` class to the trigger so it flips 180° on open. |
+| CollapsibleIndicator | { direction?: "down" \| "end"; className? } | Auto-rotating disclosure chevron. Place it anywhere inside the trigger content; it reads the trigger's open state itself, no class to add. direction="down" (default) flips 180° on open; direction="end" points to the inline end while closed and turns down on open — the caret for a grouped list's section header or a tree row. Use it instead of rotating your own chevron with CSS, which snaps with no transition. |
 
 ## Props
 
@@ -13776,7 +14557,7 @@ Use Collapsible for a single piece of optional content that can expand in place.
 - **arrival** · Root · _no motion_ — A collapsible is part of the page it sits in, present from first paint. Its trigger is what the reader notices, not an entrance.
 - **response** · CollapsibleTrigger · _no motion_ — The trigger is whatever the consumer renders (usually a Button), and that control brings its own response. Adding one here would double it.
 - **transition** · CollapsiblePanel · `motion-disclosure` — The height change ties the content that appears to the trigger that was pressed; snapped open, everything below jumps with nothing linking cause to effect.
-- **transition** · CollapsibleIndicator · `motion-interactive` — The chevron turns with the panel rather than flipping in one frame: motion-interactive lists `rotate`, the property rotate-180 writes.
+- **transition** · CollapsibleIndicator · `motion-interactive` — The chevron turns with the panel rather than flipping in one frame: motion-interactive lists `rotate`, the property rotate-180 and rotate-0 write.
 - **activity** · Root · _no motion_ — Nothing here is indeterminate; content that loads on open should put its own loader inside the panel.
 
 ## Accessibility
@@ -13813,7 +14594,15 @@ import { Button, Collapsible, CollapsiblePanel, CollapsibleTrigger } from "@sabl
 ```tsx
 import { Button, Collapsible, CollapsibleIndicator, CollapsiblePanel, CollapsibleTrigger } from "@sableui/react"
 
-<Collapsible><CollapsibleTrigger className="group/collapsible" render={<Button variant="ghost">Details <CollapsibleIndicator /></Button>} /><CollapsiblePanel><p className="pt-3">Revealed on toggle.</p></CollapsiblePanel></Collapsible>
+<Collapsible><CollapsibleTrigger render={<Button variant="ghost">Details <CollapsibleIndicator /></Button>} /><CollapsiblePanel><p className="pt-3">Revealed on toggle.</p></CollapsiblePanel></Collapsible>
+```
+
+### Group header with a side caret
+
+```tsx
+import { Button, Collapsible, CollapsibleIndicator, CollapsiblePanel, CollapsibleTrigger } from "@sableui/react"
+
+<Collapsible defaultOpen><CollapsibleTrigger render={<Button variant="ghost" size="xs"><CollapsibleIndicator direction="end" />In progress <span className="text-ui-num text-muted-foreground">5</span></Button>} /><CollapsiblePanel><ul className="text-ui-body"><li>Refine product detail page</li><li>Build the ingredient library</li></ul></CollapsiblePanel></Collapsible>
 ```
 
 ---
@@ -14501,9 +15290,9 @@ import { ContextMenu, ContextMenuContent, ContextMenuGroup, ContextMenuGroupLabe
 
 **Status:** stable
 
-A data-driven table over the Table primitives — a columns def + data array with built-in client-side sorting (click a sortable header to cycle asc → desc → none), optional row click / selection, and an empty state. For server data or paging, sort/page the data and pair with Pagination.
+A data-driven table over the Table primitives — a columns def + data array with built-in client-side sorting (click a sortable header to cycle asc → desc → none), optional row click / selection, rows grouped under collapsible header rows (groupBy), and an empty state. For server data or paging, sort/page the data and pair with Pagination.
 
-**Keywords:** data table, table, sortable, columns, rows, empty state, pagination, list
+**Keywords:** data table, table, sortable, columns, rows, empty state, pagination, list, grouped, group by, sections, issue list, issue tracker, status groups, collapsible groups
 
 ## Usage
 
@@ -14515,7 +15304,8 @@ Use DataTable when a data array and column definition should render a sortable,
 - Do: Provide stable rowKey values for dynamic data so selection and sorting do not jump.
 - Do: Use sortable only on columns where ordering is obvious and useful.
 - Do: Pair server-side datasets with Pagination and pass already-sorted/paged rows.
-- Do: Move to TanStack Table, rendered with Sable's Table parts, once the table needs server-side sorting or filtering, column visibility or resizing, grouping, or virtualised rows. DataTable stays dependency-free and does not grow into a data grid; `sable docs tables-with-tanstack` maps one onto the other.
+- Do: Group rows by status for an issue tracker (or by owner, by day) with groupBy + groups on ONE DataTable: every group shares the header and the column widths, each header row carries the group's count and an add action, and sorting applies within each group. Do not stack one DataTable per group inside Collapsibles; the header repeats and the columns stop lining up.
+- Do: Move to TanStack Table, rendered with Sable's Table parts, once the table needs server-side sorting or filtering, column visibility or resizing, nested or aggregated grouping, or virtualised rows. DataTable stays dependency-free and does not grow into a data grid; `sable docs tables-with-tanstack` maps one onto the other.
 - Don't: Make every row clickable and also fill it with competing buttons. Choose a clear row interaction model.
 - Don't: Use DataTable for heterogeneous cards or timeline content. A list or card layout will scan better.
 
@@ -14526,6 +15316,7 @@ Use DataTable when a data array and column definition should render a sortable,
 | Columns | yes | Definitions for headers, cell renderers, sorting, alignment, and classes. |
 | Rows | yes | The data array rendered through the column definitions. |
 | Empty state | no | Content spanning all columns when the row array is empty. |
+| Group header row | no | With groupBy: one row per group heading its own tbody (a th with scope=rowgroup across every column) holding the disclosure toggle, the group's icon, label and count, and an optional trailing action. |
 | Caption | no | Accessible table caption rendered by the underlying Table. |
 
 ## Props
@@ -14544,6 +15335,11 @@ Use DataTable when a data array and column definition should render a sortable,
 | defaultSort | { key: string; direction: "asc" \| "desc" } | — | Initial sort column + direction. |
 | empty | ReactNode | "No results." | Rendered spanning all columns when data is empty. Pass an EmptyState for the full treatment (icon, title, next step). |
 | caption | ReactNode | — | Bottom table caption. |
+| groupBy | (row) => string | — | Group the rows under header rows by the key this returns (a status, an owner, a day). One header serves every group, so the columns line up across them; sorting applies within each group. |
+| groups | { key: string; label?: ReactNode; icon?: ReactNode; action?: ReactNode; defaultExpanded?: boolean }[] | — | Order and presentation of the groups, by key: the header row's label (defaults to the key), a leading icon such as a status mark, a trailing action such as an icon Button that adds a row to the group, and whether it starts open (default true). Groups groupBy returns that are not listed follow, in the order their first row appears in data. A listed group with no rows is not shown. |
+| collapsible | boolean | true | Whether each group's header row is a toggle that opens and closes the group. A closed group keeps its header row and count; its rows are hidden and select-all skips them. |
+| expandedGroups | ReadonlySet<string> | — | The open groups, by key (controlled). Without it each group starts at its defaultExpanded and the table holds the state. |
+| onExpandedGroupsChange | (keys: Set<string>) => void | — | Called with the new set of open group keys when a group header is toggled. |
 
 ## Tokens used
 
@@ -14552,9 +15348,11 @@ Use DataTable when a data array and column definition should render a sortable,
 ## Motion
 
 - **arrival** · Root · _no motion_ — Rows render with the page or the query that produced them. Staggering rows in delays reading a table someone opened to scan.
+- **arrival** · Group rows · _no motion_ — Opening a group shows its rows at once: table rows cannot animate their height without leaving the table layout, and the rows are the content the reader asked for.
 - **response** · Row · `motion-interactive` — Body rows ease to a muted wash under the pointer (TableRow's recipe), which keeps the eye on the right line across a wide row of numbers. Sortable headers are ghost Buttons and answer on Button's recipe.
 - **transition** · Sort chevron · `motion-interactive` — One chevron turns to show direction instead of two glyphs swapping, so ascending to descending reads as the same column reversing. Its opacity rises from the resting 60% as the column becomes the sort.
 - **transition** · Row · `motion-interactive` — A checked row's fill eases in across its cells, so selecting by checkbox reads as the row being picked rather than a band stamped over it.
+- **transition** · Group chevron · `motion-interactive` — A group's chevron turns from pointing along the reading direction (closed) to down (open), so the group reads as folding rather than a glyph being swapped.
 - **activity** · Root · _no motion_ — DataTable has no loading state. While data is fetched, render Skeleton rows (motion-shimmer) in its place — only the caller knows a fetch is in flight.
 
 ## Accessibility
@@ -14562,6 +15360,7 @@ Use DataTable when a data array and column definition should render a sortable,
 - Sorted columns set aria-sort=ascending/descending on the header cell.
 - Sortable headers are real <button>s with a focus-visible ring, keyboard-operable.
 - Inherits the Table's scrollable frame and semantic <table>/<th>/<td> structure.
+- Grouped, each group is its own <tbody> (a rowgroup) headed by a <th scope="rowgroup"> spanning the columns, so group headers are never read as data rows; the toggle is a real button with aria-expanded and aria-controls naming that tbody.
 
 ## Related
 
@@ -14630,6 +15429,33 @@ import { Card, CardContent, CardHeader, CardTitle, DataTable } from "@sableui/re
 <Card><CardHeader><CardTitle>Deployments</CardTitle></CardHeader><CardContent flush><DataTable data={deployments} rowKey={(row) => row.id} columns={[{ key: "project", header: "Project", sortable: true }, { key: "duration", header: "Duration", align: "end" }]} /></CardContent></Card>
 ```
 
+### Issues grouped by status
+
+```tsx
+import { Button, DataTable, Icon, StatusDot } from "@sableui/react"
+
+const STATUSES = [
+	{ key: "in-progress", label: "In progress", icon: <StatusDot tone="warning" /> },
+	{ key: "in-review", label: "In review", icon: <StatusDot tone="purple" /> },
+	{ key: "todo", label: "Todo", icon: <StatusDot /> },
+	{ key: "done", label: "Done", icon: <StatusDot tone="success" />, defaultExpanded: false },
+]
+
+<DataTable
+	data={issues}
+	rowKey={(t) => t.id}
+	groupBy={(t) => t.status}
+	groups={STATUSES.map((s) => ({ ...s, action: <Button variant="ghost" size="icon-xs" aria-label={`Add issue to ${s.label}`} onClick={() => create(s.key)}><Icon name="plus" /></Button> }))}
+	onRowClick={(t) => setSelectedId(t.id)}
+	isRowSelected={(t) => t.id === selectedId}
+	columns={[
+		{ key: "id", header: "ID", className: "w-20", cell: (t) => <span className="text-mono-caption text-muted-foreground">{t.id}</span> },
+		{ key: "title", header: "Issue", sortable: true },
+		{ key: "due", header: "Due", sortable: true, sortValue: (t) => t.due.getTime(), cell: (t) => formatDate(t.due) },
+	]}
+/>
+```
+
 ### Empty state
 
 ```tsx
@@ -14646,7 +15472,7 @@ import { Button, DataTable, EmptyState, Icon } from "@sableui/react"
 
 Date (and optionally time) picker: a field-shaped trigger (the Input / SelectTrigger shell) opens a Popover holding Sable's Calendar. With granularity="day" selecting a day fires onValueChange and closes; granularity="minute" adds an hour + minute row of Selects and keeps the time-of-day when the day changes.
 
-**Keywords:** date picker, calendar, date input, date time picker, time, schedule, form
+**Keywords:** date picker, due date, property row, inspector, calendar, date input, date time picker, time, schedule, form
 
 ## Usage
 
@@ -14675,6 +15501,8 @@ Use DatePicker when users need to choose one date — or, with granularity="minu
 | disabled | boolean | — | Disable the trigger and block selection. |
 | minDate | Date | — | Earliest selectable day (inclusive). Earlier days are disabled and navigation is bounded. |
 | maxDate | Date | — | Latest selectable day (inclusive). Later days are disabled and navigation is bounded. |
+| size | "md" \| "xs" | "md" | The trigger's rung. md is the form field beside Input and Select. xs is the property-grid rung (24px in a workspace): an inset panel-field well with no border, the same shape as SelectTrigger size="xs" and ScrubField on the neighbouring rows of an inspector — use it for a due date in a PropertyRow instead of a native date input. |
+| formatOptions | Intl.DateTimeFormatOptions | — | How the trigger writes the chosen date, as Intl.DateTimeFormat options in the reader's locale — { month: "short", day: "numeric" } for "Oct 23" where the rest of a list writes dates that way. Omitted: "Oct 23, 2026" (with "at 14:30" under granularity="minute"). |
 | className | string | — | Extra classes merged onto the trigger. |
 | id / aria-label / aria-labelledby / aria-describedby / aria-invalid / aria-required | button attributes | — | Forwarded to the trigger, so a wrapping Field ties its label to the picker and announces its description and error. Pass them yourself only when labelling the picker without a Field. |
 
@@ -14696,6 +15524,18 @@ Use DatePicker when users need to choose one date — or, with granularity="minu
 
 ## Examples
 
+### In an inspector row
+
+```tsx
+import { DatePicker, PanelSection, PropertyRow } from "@sableui/react"
+
+<PanelSection title="Properties">
+	<PropertyRow label="Due date">
+		<DatePicker size="xs" aria-label="Due date" value={due} onValueChange={setDue} formatOptions={{ month: "short", day: "numeric" }} />
+	</PropertyRow>
+</PanelSection>
+```
+
 ### Controlled
 
 ```tsx
@@ -14920,11 +15760,14 @@ Use Dialog for focused decisions, short modal forms, confirmations, and content
 - Do: Use showCloseButton for dismissible informational dialogs; keep destructive confirmations action-led.
 - Do: In a destructive confirmation, state the consequence in DialogDescription ("This is permanent.") and reserve the destructive button variant for actions that cannot be undone.
 - Do: Use size="fullscreen" when an image, video, or gallery needs a larger view than the layout can give it. Give the popup an accessible name (aria-label on DialogContent, or a visually hidden DialogTitle) and alt text on the media.
+- Do: Open a dialog from your own button with controlled open/onOpenChange when the trigger is not a DialogTrigger (a menu item, a row action, a keyboard shortcut). Focus returns on close to whatever held it when the dialog opened, with no finalFocus wiring; pass finalFocus only to send it somewhere else.
+- Do: Set keepMounted on DialogContent for a draft the user may come back to (a compose form, a long comment, a half-filled request). Closing by Esc or a stray click then hides the dialog instead of unmounting it, so the fields are still filled when it reopens. Clear the draft yourself on submit or discard.
 - Do: Use the AlertDialog family for a confirmation that must be answered (discard changes, leave without saving). It looks identical but is role="alertdialog" and a backdrop click does not dismiss it — only Cancel, Esc, or the action. For irreversible deletes, use DestructiveActionModal, which is built on it.
 - Don't: Put large multipage workflows in a centered dialog. Use Sheet or a page route when the task needs space. → use **Sheet**
 - Don't: Use size="fullscreen" for forms, confirmations, or anything that isn't media. A dialog that happens to need room is a Sheet or a page; the fullscreen affordances (dark scrim, corner close, centred content) all assume something to look at. → use **Sheet**
 - Don't: Hide the close button at size="fullscreen" without another visible way out. A full-bleed viewer that only Esc dismisses is a dead end for anyone who doesn't know the key.
 - Don't: Open a dialog for passive status updates. Use Toast, Banner, or InlineStatus instead. → use **Toast**, **Banner**, **InlineStatus**
+- Don't: Set keepMounted by default. A dialog that should open fresh (a confirmation, a create form after a successful save) would show stale input, and live content (polling, video) keeps running while hidden.
 
 ### Anatomy
 
@@ -14940,7 +15783,7 @@ Use Dialog for focused decisions, short modal forms, confirmations, and content
 
 | Name | Type | Description |
 | --- | --- | --- |
-| DialogContent | Base UI Popup props + size?: "default" \| "fullscreen" + showCloseButton?: boolean + scroll?: boolean + className | Backdrop + popup; portals to <body>. Composes DialogOverlay by default. size="fullscreen" is the media viewer: a near-opaque scrim (bg-overlay/95), an edge-to-edge popup that centres its children with no card chrome, motion-fade instead of motion-pop, and a safe-area-aware floating close button (Button variant="floating"); at that size showCloseButton defaults to true and scroll to false, and the media fits itself with max-h-full max-w-full object-contain. At the default size, showCloseButton (defaults to false) renders a built-in close (X) button in the top-end corner, and the header leaves room for it (Icon name="xmark"). The popup caps at the viewport height less a 1rem margin and wraps its children in a scrolling region, so a tall dialog scrolls instead of overflowing a viewport whose own scroll is locked; pass scroll={false} when the dialog owns its internal layout (a pinned header over a scrolling body) and supplies its own min-h-0 scroll region. |
+| DialogContent | Base UI Popup props (initialFocus, finalFocus) + size?: "default" \| "fullscreen" + showCloseButton?: boolean + scroll?: boolean + keepMounted?: boolean + className | Backdrop + popup; portals to <body>. Composes DialogOverlay by default. size="fullscreen" is the media viewer: a near-opaque scrim (bg-overlay/95), an edge-to-edge popup that centres its children with no card chrome, motion-fade instead of motion-pop, and a safe-area-aware floating close button (Button variant="floating"); at that size showCloseButton defaults to true and scroll to false, and the media fits itself with max-h-full max-w-full object-contain. At the default size, showCloseButton (defaults to false) renders a built-in close (X) button in the top-end corner, and the header leaves room for it (Icon name="xmark"). The popup caps at the viewport height less a 1rem margin and wraps its children in a scrolling region, so a tall dialog scrolls instead of overflowing a viewport whose own scroll is locked; pass scroll={false} when the dialog owns its internal layout (a pinned header over a scrolling body) and supplies its own min-h-0 scroll region. keepMounted (default false) keeps the content mounted and hidden while closed, so a draft survives close and reopen. finalFocus defaults to the element focused when the dialog opened, trigger or not; an explicit finalFocus (a ref, a function, or false) wins. |
 | DialogOverlay | Base UI Backdrop props + size?: "default" \| "fullscreen" + className | The styleable scrim/backdrop — bg-overlay/(--scrim-alpha) by default (50% light, 72% dark, so it dims a near-black page as visibly as a white one), near-opaque bg-overlay/95 at size="fullscreen". Composed into DialogContent (at the matching size) by default; exported for manual styling. |
 | DialogTrigger | Base UI Dialog.Trigger props (render) | Element that opens the dialog. Compose via render prop. |
 | DialogClose | Base UI Dialog.Close props (render) | Element that dismisses the dialog. Compose via render prop. |
@@ -14948,7 +15791,7 @@ Use Dialog for focused decisions, short modal forms, confirmations, and content
 | DialogTitle | Base UI Dialog.Title props + className | The dialog's accessible name — wires aria-labelledby on the popup. |
 | DialogDescription | Base UI Dialog.Description props + className | Muted supporting line; wires aria-describedby. |
 | DialogFooter | ComponentProps<"div"> | Bottom action row (right-aligned buttons). |
-| AlertDialog (Root) | Base UI AlertDialog.Root props (open, defaultOpen, onOpenChange) | Root for a confirmation that needs an answer. Always modal; the popup is role="alertdialog" and a click outside does not dismiss — only an AlertDialogClose, an action that sets open to false, or Esc. |
+| AlertDialog (Root) | Base UI AlertDialog.Root props (open, defaultOpen, onOpenChange) | Root for a confirmation that needs an answer. Always modal; the popup is role="alertdialog" and a click outside does not dismiss — only an AlertDialogClose, an action that sets open to false, or Esc. Returns focus on close to the element focused when it opened, exactly as Dialog does. |
 | AlertDialogTrigger | Base UI AlertDialog.Trigger props (render) | Opens the alert dialog. |
 | AlertDialogContent / AlertDialogOverlay / AlertDialogTitle / AlertDialogDescription / AlertDialogHeader / AlertDialogFooter / AlertDialogClose | Same props as the matching Dialog part | The Dialog parts under AlertDialog names — Base UI shares the popup, backdrop, title, description and close parts between the two, so the surface is identical. Pass initialFocus to AlertDialogContent (a ref to the Cancel button) to open focus on the safe action. |
 
@@ -14956,7 +15799,10 @@ Use Dialog for focused decisions, short modal forms, confirmations, and content
 
 | Name | Type | Default | Description |
 | --- | --- | --- | --- |
-| Dialog (Root) | Base UI Dialog.Root props (open, defaultOpen, onOpenChange, modal) | — | Controls open state. Uncontrolled by default. |
+| Dialog (Root) | Base UI Dialog.Root props (open, defaultOpen, onOpenChange, modal) | — | Controls open state. Uncontrolled by default. Records the element that holds focus when the dialog opens (through a DialogTrigger, or your own button flipping a controlled open) and returns focus there on close. |
+| open | boolean | — | Controlled open state. Pair with onOpenChange — for a dialog opened from your own button instead of a DialogTrigger. |
+| defaultOpen | boolean | false | Initial open state when uncontrolled. |
+| onOpenChange | (open: boolean, eventDetails) => void | — | Called when the dialog asks to open or close (a trigger, Esc, an outside click, DialogClose). |
 
 ## Variants
 
@@ -14978,6 +15824,8 @@ Use Dialog for focused decisions, short modal forms, confirmations, and content
 
 - Base UI provides focus trapping, scroll lock, aria-modal, and labelled-by wiring (DialogTitle).
 - Content taller than the viewport scrolls inside the dialog (thin scrollbar, contained overscroll) rather than overflowing off screen — the page behind is scroll-locked, so anything past the edge would be unreachable.
+- On close, focus returns to the element that held it when the dialog opened, whether a DialogTrigger opened it or your own button set a controlled open. It is captured before the content mounts, so an autoFocus field inside cannot displace it. If that element has left the page, Base UI's default (the trigger, if any) applies; an explicit finalFocus on the content always wins. AlertDialog and Sheet behave the same.
+- keepMounted hides closed content with the hidden attribute, so a kept draft is out of the accessibility tree and the tab order until the dialog reopens.
 - Esc and click-outside dismiss by default. AlertDialog keeps Esc but ignores click-outside, and its popup is role="alertdialog".
 - Animate via data-[starting-style]/data-[ending-style] attributes.
 - size="fullscreen" has no title chrome, so name the popup yourself: aria-label on DialogContent (or a visually hidden DialogTitle), plus alt text on the media — the zoomed image is a separate image to assistive technology. Its built-in close button carries aria-label="Close" and clears the safe-area insets (notch, home indicator).
@@ -15021,6 +15869,29 @@ import { Button, Dialog, DialogClose, DialogContent, DialogDescription, DialogFo
 <Dialog><DialogTrigger render={<Button variant="secondary">Rename collection</Button>} /><DialogContent showCloseButton><DialogHeader><DialogTitle>Rename collection</DialogTitle><DialogDescription>Update the display name shown to collectors.</DialogDescription></DialogHeader><Form><Field label="Collection name"><Input defaultValue="Midnight Archive" /></Field><DialogFooter><DialogClose render={<Button variant="secondary">Cancel</Button>} /><Button type="submit">Save changes</Button></DialogFooter></Form></DialogContent></Dialog>
 ```
 
+### Opened from your own button, keeping a draft
+
+```tsx
+import { Button, Dialog, DialogClose, DialogContent, DialogDescription, DialogFooter, DialogHeader, DialogTitle, Field, Textarea } from "@sableui/react"
+
+const [open, setOpen] = useState(false)
+
+<Button variant="secondary" onClick={() => setOpen(true)}>New message</Button>
+<Dialog open={open} onOpenChange={setOpen}>
+	<DialogContent keepMounted showCloseButton>
+		<DialogHeader>
+			<DialogTitle>New message</DialogTitle>
+			<DialogDescription>Close it any time. Your draft is here when you come back.</DialogDescription>
+		</DialogHeader>
+		<Field label="Message"><Textarea /></Field>
+		<DialogFooter>
+			<DialogClose render={<Button variant="secondary">Close</Button>} />
+			<Button onClick={() => setOpen(false)}>Send</Button>
+		</DialogFooter>
+	</DialogContent>
+</Dialog>
+```
+
 ### Destructive confirmation
 
 ```tsx
@@ -16983,6 +17854,7 @@ Use MediaImage wherever content imagery may be missing or broken: a cover in a g
 - Do: Give the box the shape: `<AspectBox ratio={1} className="rounded-md"><MediaImage … /></AspectBox>`, or `size-14 rounded-md` on MediaImage itself for a thumbnail. It clips to whatever radius the box has.
 - Do: Pass `seed` (the title or an id) when `alt` is empty, so the fallback art is the item's own and stays the same in every list it appears in.
 - Do: Leave `alt` empty when a visible title sits next to the image — a tile, a row — and describe it when the image stands alone. A set `alt` also names the fallback, so the description survives a broken URL.
+- Do: Set `position` when a cover crop would cut off the subject — a face high in a portrait, a product at one edge. Store the focus with the image (`"35% 50%"`) rather than re-cropping the file.
 - Don't: Do not hand-write `<img onError={() => setBroken(true)}>`. An image that fails before hydration never fires the handler on a prerendered page; MediaImage preloads off the DOM and catches it.
 - Don't: Do not use it for profile pictures. A person is a circle with initials — Avatar, whose `variant="art"` is the same fallback with the person's initials over it.
 
@@ -16995,6 +17867,7 @@ Use MediaImage wherever content imagery may be missing or broken: a cover in a g
 | seed | string \| number | — | Seeds the fallback art. Defaults to `alt`; pass the title or an id when `alt` is empty. |
 | fallback | ReactNode | — | Replaces the GradientArt fallback — a glyph or monogram. Fills the frame under the same clipping. |
 | fit | "cover" \| "contain" | "cover" | `cover` crops to fill (artwork, photos); `contain` letterboxes on the muted surface (a logo, a product that must not be cropped). |
+| position | CSSProperties["objectPosition"] | "center" | Where the image sits in its frame — CSS `object-position`, the sibling of `fit`. Under `cover` it is the part the crop keeps (`"50% 30%"` for a face, `"bottom"` for a horizon); under `contain` it is the side the letterbox gives way to. |
 | srcSet | string | — | Responsive sources, passed to the `<img>`. |
 | sizes | string | — | The `sizes` attribute for `srcSet`. |
 | loading | "lazy" \| "eager" | "lazy" | Native lazy loading. Use `eager` for the first row of a grid above the fold. |
@@ -17065,6 +17938,16 @@ import { AspectBox, MediaImage } from "@sableui/react"
 </AspectBox>
 ```
 
+### Crop focus per image
+
+```tsx
+import { AspectBox, MediaImage } from "@sableui/react"
+
+<AspectBox ratio={1} className="rounded-md">
+	<MediaImage src={project.thumbnail} seed={project.title} position={project.focus ?? "center"} />
+</AspectBox>
+```
+
 ---
 
 # MediaTile
@@ -17111,6 +17994,7 @@ The item in a media grid or shelf: an album, a playlist, a video, a podcast, a f
 | sizes | string | — | The cover's layout width for `srcSet`, e.g. `"(min-width: 64rem) 25vw, 50vw"`. |
 | alt | string | "" | Cover alt text. Empty by default: the title below already names the item. |
 | seed | string \| number | — | Seeds the fallback art. Defaults to `title` when it is a string. |
+| position | CSSProperties["objectPosition"] | "center" | Which part of the cover the crop keeps — CSS `object-position`, forwarded to the cover's MediaImage: `"50% 30%"` for a face, `"top"` for a poster's title. Store it with the image when each one frames differently. |
 | aspect | "square" \| "video" \| "poster" \| number | "square" | The cover's shape: square (albums, podcasts), video (16:9), poster (2:3 — films, books), or any width / height ratio. |
 | size | "sm" \| "md" \| "lg" | "md" | Moves the type tier, the cover-to-text gap, the corner and the overlay inset together. |
 | href | string | — | Where the tile goes. The title becomes the link, stretched over the whole tile. |
@@ -17235,6 +18119,26 @@ import { Grid, MediaTile } from "@sableui/react"
 </Grid>
 ```
 
+### Portfolio grid with crop focus
+
+```tsx
+import { Grid, MediaTile } from "@sableui/react"
+
+<Grid minItemWidth="16rem" gap={4}>
+	{projects.map((project) => (
+		<MediaTile
+			key={project.slug}
+			aspect="video"
+			title={project.title}
+			subtitle={project.client}
+			src={project.thumbnail}
+			position={project.focus}
+			href={`/work/${project.slug}`}
+		/>
+	))}
+</Grid>
+```
+
 ### Poster shelf
 
 ```tsx
@@ -17286,7 +18190,7 @@ Use Menu for a compact list of actions opened from a visible trigger.
 | MenuLinkItem | Base UI Menu.LinkItem props (href, target, closeOnClick) + className + icon?: ReactNode + description?: ReactNode | A row that navigates: a real <a>, so it opens in a new tab, middle-clicks and copies as a link. With target="_blank" it adds rel="noopener noreferrer" and a trailing ↗. Takes icon and description like MenuItem. |
 | MenuSeparator | Base UI Separator props + className | Hairline rule between item runs. |
 | MenuSubmenu | Base UI Menu.SubmenuRoot props | A nested menu. Wraps a MenuSubmenuTrigger and its own MenuContent — pass side="inline-end" to that content so the submenu opens away from its parent in RTL as well as LTR. |
-| MenuSubmenuTrigger | Base UI Menu.SubmenuTrigger props + value: ReactNode + className | The row that opens a submenu: item styling, a trailing chevron, and an optional `value` showing the current choice so the row reads "Effort  High ›" rather than making the reader open it to find out. |
+| MenuSubmenuTrigger | Base UI Menu.SubmenuTrigger props + value: ReactNode + icon: ReactNode + className | The row that opens a submenu: item styling, a trailing chevron, and an optional `value` showing the current choice so the row reads "Effort  High ›" rather than making the reader open it to find out. `icon` leads the row as MenuItem's does; give it one whenever the items around it have icons, or its label starts a column to their left. |
 | MenuRadioGroup | Base UI Menu.RadioGroup props (value, defaultValue, onValueChange) | A single-choice group inside a menu. Controlled via value/onValueChange, uncontrolled via defaultValue. |
 | MenuRadioItem | Base UI Menu.RadioItem props + className (value, disabled) | One option in a MenuRadioGroup, rendered as menuitemradio with a real checked state. The check sits in a reserved leading column so labels never shift sideways as the highlight moves. |
 | MenuCheckboxItem | Base UI Menu.CheckboxItem props + className + { checked?: boolean; defaultChecked?: boolean; onCheckedChange?: (checked: boolean) => void; disabled?: boolean } | A toggling row, with the same reserved leading column as MenuRadioItem so a menu mixing the two keeps one text margin. |
@@ -18614,7 +19518,7 @@ import { Button, Icon, MenuItem, OverflowMenu, Row } from "@sableui/react"
 
 In-flow page heading block: a title row (optional back control + actions) over an optional description, with room for children (filters, tabs) below.
 
-**Keywords:** page header, title, lede, page actions
+**Keywords:** page header, title, lede, page actions, page title size, display title, editorial header, hero title
 
 ## Usage
 
@@ -18624,6 +19528,8 @@ Use PageHeader to establish a page's title, supporting description, and primary
 
 - Do: Use one PageHeader per major page or route.
 - Do: Keep the title literal and put explanation in the lede or nearby content.
+- Do: Use size="lg" for an editorial page (a personal site, a marketing page, an article index): a display-tier title over a body-lg lede. Pair it with SectionHeader size="lg" for the sections below, so the steps stay display → heading-2 → body.
+- Don't: Use size="lg" on product routes (settings, lists, dashboards). Display type is never product chrome: there it competes with the content it frames. Keep md, and do not restyle the title with a display class through className either.
 - Don't: Do not use PageHeader inside repeated cards, dialogs, or compact panels.
 - Don't: Do not use a second PageHeader for a section of the page. It is the route's one h1; each section below it takes a SectionHeader (an h2 with the same title row, description and actions).
 - Don't: Do not put it outside the Region that holds the page content. It then sits at a different measure from what it introduces, and the page reads as two documents.
@@ -18637,6 +19543,11 @@ Use PageHeader to establish a page's title, supporting description, and primary
 | back | ReactNode | — | Leading element before the title — typically a back control on drill-in routes. Keep it a ghost icon Button (size="icon", variant="ghost", aria-label="Back") so it stays quieter than the title. A ghost back control bleeds by its inset at the start, so its glyph lines up with the content edge below (Button bleed="none" opts out). |
 | actions | ReactNode | — | Trailing actions aligned to the title row's end. They drop under the title when the title would have less than 20rem beside them (on a phone, nearly always), and the title wraps rather than truncating. A ghost or link Button at either end of the group bleeds by its own padding, so its label meets the content edge (the end on the title row, the start once wrapped); filled buttons keep their edge on the line. Direct children only. |
 | titleAs | "h1" \| "h2" | "h1" | The title's heading element. Keep h1 — the route's one h1. Use h2 only when something above already owns the h1: a shell that renders the route title, or a page showing a PageHeader as an example. |
+| size | "md" \| "lg" | "md" | The title's scale. md: text-heading-2 over a text-body-sm description, for product pages. lg: text-display-lg over a text-body-lg lede capped at the prose measure, with more space between and below, for an editorial page (personal site, marketing page, article index). Beside actions or a back control, a title line taller than the controls lifts by half the difference, so its first line stays centred on them. |
+
+## Variants
+
+- **size**: md, lg
 
 ## Tokens used
 
@@ -18661,6 +19572,14 @@ import { Button, PageHeader } from "@sableui/react"
 <PageHeader title="Storage credits" description="Fund permanent storage." actions={<Button>Top up</Button>} />
 ```
 
+### Editorial page title (size lg)
+
+```tsx
+import { Button, PageHeader } from "@sableui/react"
+
+<PageHeader size="lg" title="Field notes" description="Essays on making things slowly, from a studio by the sea." actions={<Button variant="outline">Subscribe</Button>} />
+```
+
 ### One per page, inside the region
 
 ```tsx
@@ -18871,7 +19790,7 @@ const [page, setPage] = useState(searchParams.page ?? 1)
 
 A row of docked chrome panels around a flexible centre, with draggable and keyboard-resizable edges and optional persisted widths.
 
-**Keywords:** panel, panels, resize, resizable, splitter, docked, workspace, tool, chrome, inspector, layout
+**Keywords:** panel, panels, resize, resizable, splitter, docked, workspace, tool, chrome, inspector, layout, mobile, responsive, sheet, drawer, narrow, detail pane
 
 ## Usage
 
@@ -18882,6 +19801,8 @@ Use PanelGroup for the body of a tool workspace: fixed-width Panels docked left
 - Do: Give every docked Panel a fixed width and leave the centre Panel width-less so it absorbs the remaining space.
 - Do: Drive the width with usePanelWidth and pass a storageKey, so a user's layout survives a reload. Spread its bounds onto the PanelResizer rather than repeating min and max by hand.
 - Do: Label every Panel — they are landmarks, and 'Layers' or 'Properties' is what a screen-reader user navigates by.
+- Do: Decide what each docked Panel becomes on a phone with `narrow`: "sheet" for an inspector or a navigation rail the user opens on demand, "hidden" for chrome a phone does without. Drive a sheet's `open` from the same state that selects the record, so selecting a row opens the inspector at every width.
+- Don't: Render the same inspector twice, once in a Panel and once in a Sheet behind a hand-rolled viewport check. `narrow="sheet"` renders the content once, in whichever place applies.
 - Don't: Let the group scroll. Only panels and the canvas scroll; a scrolling group means the shell lost its height constraint.
 - Don't: Use it for page content columns — that's Grid or Columns. PanelGroup is chrome, and it sits outside the content grid.
 - Don't: Omit PanelResizer to save effort and then let users live with a fixed panel. If a panel holds a tree or a property grid, its width is a preference.
@@ -18898,7 +19819,7 @@ Use PanelGroup for the body of a tool workspace: fixed-width Panels docked left
 
 | Name | Type | Description |
 | --- | --- | --- |
-| Panel | { label: string; width?: number; scroll?: boolean } | A docked or flexible column. `label` names the landmark; omit `width` for the flexible centre. `scroll` defaults to true — set it false for a header + scrolling body + pinned footer, so the footer doesn't scroll away with the list. When you own the layout, give the header and footer shrink-0 and the middle min-h-0 flex-1 overflow-y-auto. overflow-y-auto only activates if every flex ancestor can shrink: a single missing min-h-0 anywhere up the chain makes the panel grow instead of scroll, and nothing reports it. |
+| Panel | { label: string; width?: number; scroll?: boolean; narrow?: "dock" \| "sheet" \| "hidden"; open?: boolean; onOpenChange?: (open: boolean) => void; side?: "left" \| "right"; below?: "sm" \| "md" \| "lg" \| "xl" \| "2xl" } | A docked or flexible column. Below `below` (default lg, where Sidebar and BottomNav swap), `narrow` decides what it becomes: "dock" (default) stays docked, "sheet" renders the same content once inside a Sheet from `side` (default "right"; a panel before the canvas is "left"), titled by `label`, open while `open` is true and closed through `onOpenChange` (Esc, scrim, swipe), and "hidden" drops it. `open` defaults to true docked (false removes the column, so the canvas takes its width) and false as a sheet. Crossing the breakpoint remounts the content, so keep state that must survive it in the app. `label` names the landmark; omit `width` for the flexible centre. `scroll` defaults to true — set it false for a header + scrolling body + pinned footer, so the footer doesn't scroll away with the list. When you own the layout, give the header and footer shrink-0 and the middle min-h-0 flex-1 overflow-y-auto. overflow-y-auto only activates if every flex ancestor can shrink: a single missing min-h-0 anywhere up the chain makes the panel grow instead of scroll, and nothing reports it. |
 | PanelResizer | { side: 'left' \| 'right'; width: number; onWidthChange: (n: number) => void; label: string; min?: number; max?: number; step?: number } | The draggable edge. `side` says which side the resized panel is on, so the drag delta's sign is right. |
 | usePanelWidth | (defaultWidth: number, options?: { storageKey?: string; min?: number; max?: number }) => readonly [number, (n: number) => void, { min: number; max: number }] | Controlled width for a Panel, clamped and optionally persisted to localStorage (only when `storageKey` is passed). Read through useSyncExternalStore, so there is no server/client hydration mismatch and no setState in an effect; do not hand-roll a localStorage read during render or a write from an effect. Without `storageKey` the width is kept in memory per hook instance. The third element is the `{ min, max }` it clamps to: spread it onto the paired PanelResizer so the separator's aria-valuemin/max and Home/End match the real clamp. |
 
@@ -18977,6 +19898,36 @@ function Body() {
 }
 ```
 
+### Inspector that becomes a sheet on phones
+
+```tsx
+import { Button, Input, Panel, PanelGroup, PanelSection, PropertyRow } from "@sableui/react"
+
+function Body() {
+  const [selected, setSelected] = useState<string | null>(null)
+  return (
+    <PanelGroup>
+      <Panel label="Issues">
+        <div className="p-2">
+          <Button size="xs" variant="ghost" onClick={() => setSelected("AES-104")}>AES-104 Refine product page</Button>
+        </div>
+      </Panel>
+      <Panel
+        label="Issue details"
+        width={320}
+        narrow="sheet"
+        open={selected !== null}
+        onOpenChange={(open) => !open && setSelected(null)}
+      >
+        <PanelSection title={selected ?? ""}>
+          <PropertyRow label="Status"><Input defaultValue="In progress" /></PropertyRow>
+        </PanelSection>
+      </Panel>
+    </PanelGroup>
+  )
+}
+```
+
 ### Fixed panel, no resizer
 
 ```tsx
@@ -19341,7 +20292,7 @@ import { PieChart } from "@sableui/react"
 
 **Status:** stable
 
-A chip someone clicks: a filter, a tag choice, an option in a row. Always a button with aria-pressed. appearance="solid" (filters; selected lifts onto the primary surface) or "outline" (quiet chips that annotate content, like reactions); size md or sm. A static label is a Badge.
+A chip someone clicks: a filter, a tag choice, an option in a row. Always a button with aria-pressed. appearance="solid" (filters; selected lifts onto the primary surface) or "outline" (quiet chips that annotate content, like reactions); size lg, md or sm. A static label is a Badge.
 
 **Keywords:** pill, chip, filter, tag, toggle chip, category
 
@@ -19353,9 +20304,10 @@ Use Pill for a row of filters or choices a person clicks to narrow or toggle wha
 
 - Do: Use short text that names the filter or choice.
 - Do: Reflect the current choice with selected, so the active filter reads at a glance.
+- Do: In a toolbar where filter chips share a row with a search field ("All 8 · Products 5 · Open source 2 … [Find a project]"), pair Pill size="lg" with SearchInput size="sm", and Button size="sm" for any action beside them. All three stand on --control-sm (32px, 28 compact), the rung the spacing doctrine gives toolbar controls, so the row is one height in either density. Pill md (28px) has no text field of its height in the page register, so md beside a field always reads as a mismatch.
 - Don't: Do not use Pill as a static label. A pressable-looking chip that does nothing is the most common cause of dead clicks in a filter row — that is a Badge. → use **Badge**
 - Don't: Do not use Pill for primary actions or important system status.
-- Don't: Do not restyle a Pill with border or background classes to get a quieter chip. That is appearance="outline" (and size="sm" for a small one); an override is a look that exists nowhere else in the system.
+- Don't: Do not restyle a Pill with border or background classes to get a quieter chip. That is appearance="outline" (and size="sm" for a small one); an override is a look that exists nowhere else in the system. Likewise never set h-* on a Pill to match a neighbour: pick the size that shares its rung.
 
 ## Props
 
@@ -19363,14 +20315,14 @@ Use Pill for a row of filters or choices a person clicks to narrow or toggle wha
 | --- | --- | --- | --- |
 | selected | boolean | false | Marks the pill as chosen. Solid lifts onto the primary surface; outline takes a primary tint and soft primary edge. Sets aria-pressed. |
 | appearance | "solid" \| "outline" | "solid" | solid for a filter row; outline for quiet chips that annotate other content (a reaction under a message, a tag on a card), where a filled chip would compete with what it annotates. |
-| size | "md" \| "sm" | "md" | md sits on the density ladder's xs control height (28px); sm is 24px, for chips under or inside other content. |
+| size | "lg" \| "md" \| "sm" | "md" | lg sits on --control-sm (32px, 28 compact), the toolbar rung it shares with SearchInput sm and Button sm, for a filter row beside a search field. md sits on --control-xs (28px, 24 compact), the chip in a row of its own or among content. sm is a fixed 24px (the target floor, which density does not shrink), for chips under or inside other content. |
 | tone | "neutral" \| "red" \| "orange" \| "yellow" \| "green" \| "teal" \| "blue" \| "purple" \| "pink" | "neutral" | neutral is the chip as described. A palette family colours it as a category, like the choices in a tag picker: a wash at rest, the solid family colour when selected. Painted from the theme's generated palette. |
 | icon | ReactNode | — | Optional leading glyph (e.g. <Icon name="lock" />), rendered before the children with the base gap. |
 
 ## Variants
 
 - **appearance**: solid, outline
-- **size**: md, sm
+- **size**: lg, md, sm
 - **selected**: true, false
 - **tone**: neutral, red, orange, yellow, green, teal, blue, purple, pink
 
@@ -19393,7 +20345,7 @@ Use Pill for a row of filters or choices a person clicks to narrow or toggle wha
 
 ## Related
 
-- Components: Badge, ToggleGroup
+- Components: Badge, ToggleGroup, SearchInput
 
 ## Examples
 
@@ -19413,6 +20365,24 @@ import { Pill, Row } from "@sableui/react"
 <Row gap={1}><Pill selected onClick={() => {}}>All</Pill><Pill onClick={() => {}}>Projects</Pill><Pill onClick={() => {}}>Reports</Pill></Row>
 ```
 
+### Filters with search
+
+```tsx
+import { Pill, Row, SearchInput } from "@sableui/react"
+
+const [filter, setFilter] = useState("all")
+const [q, setQ] = useState("")
+
+<Row gap={2} align="center" justify="between" wrap>
+	<Row gap={1}>
+		<Pill size="lg" selected={filter === "all"} onClick={() => setFilter("all")}>All 8</Pill>
+		<Pill size="lg" selected={filter === "products"} onClick={() => setFilter("products")}>Products 5</Pill>
+		<Pill size="lg" selected={filter === "oss"} onClick={() => setFilter("oss")}>Open source 2</Pill>
+	</Row>
+	<SearchInput size="sm" value={q} onValueChange={setQ} placeholder="Find a project…" aria-label="Find a project" className="max-w-64" />
+</Row>
+```
+
 ### Outline, small (reactions)
 
 ```tsx
@@ -20431,7 +21401,7 @@ import { PropertyRow, ScrubField, Slider } from "@sableui/react"
 
 **Status:** stable
 
-Styled search field with a leading magnifier and a clearable X. Soft-square (rounded-sm), the theme's field surface, 2px focus ring; the clear button appears only when there is a value.
+Styled search field with a leading magnifier and a clearable X. Soft-square (rounded-sm), the theme's field surface, 2px focus ring; the clear button appears only when there is a value. size md (form), sm (toolbar, matching Pill lg and Button sm) or xs (inset tool-panel field).
 
 **Keywords:** search, input, filter, query
 
@@ -20445,6 +21415,8 @@ Use SearchInput for text queries that filter or search a known content set.
 - Do: Provide a visible clear affordance when query state persists.
 - Do: When a button stands in for search (a header trigger that opens CommandMenu with ⌘K), use CommandMenuTrigger. It wears this field's shell from the same source, so the two cannot drift; a hand-styled button already did once, into a borderless chip that matched neither the field nor a button.
 - Do: Light the query in the results it filters with `useMatchHighlight(query)` — a callback ref for the results container, with `selector` to keep it to titles. It paints on the `highlight` pair without wrapping matches in `<mark>`, the same paint Combobox and CommandMenu use for their rows.
+- Do: In a toolbar beside filter chips, use size="sm" with Pill size="lg" (and Button size="sm" for actions). All three stand on --control-sm (32px, 28 compact), the rung the spacing doctrine gives toolbar controls, so the row is one height in either density. Keep md for a search field in a form or a page header beside md buttons, and xs for a filter inside a workspace panel, where it matches Input xs's inset surface.
+- Don't: Do not match a neighbour's height with h-* on className or inputClassName. The magnifier, padding and clear button would stay sized for the old rung; pick the size that shares the neighbour's rung.
 - Don't: Do not use SearchInput as a command palette; use CommandMenu for global commands, opened from the header by CommandMenuTrigger. A SearchInput that opens a dialog on focus is a text box you cannot type in.
 - Don't: Do not search on every keystroke against an expensive backend without debouncing. The user sees results flicker and reorder under them, and you send a request per character.
 
@@ -20452,6 +21424,7 @@ Use SearchInput for text queries that filter or search a known content set.
 
 | Name | Type | Default | Description |
 | --- | --- | --- | --- |
+| size | "md" \| "sm" \| "xs" | "md" | The rung of the control ladder, named as on Input, Select and Combobox. md is the form field (--control-md, 40px / 32 compact). sm is the toolbar field (--control-sm, 32px / 28 compact), the rung Pill lg and Button sm share, so filters + search + actions in one row are one height. xs is the tool-panel field (--control-xs, 28px / 24 compact) on Input xs's inset panel-field surface. The magnifier, inline padding and clear button scale with the rung and stay vertically centred. |
 | value | string | — | Controlled value of the search field. |
 | defaultValue | string | — | Uncontrolled initial value. The field tracks its own text, so the clear button still appears and empties it. |
 | className | string | — | Sizes and places the whole field — magnifier, input and clear button together (e.g. max-w-80). A width cap here keeps the clear button inside the field. |
@@ -20460,11 +21433,11 @@ Use SearchInput for text queries that filter or search a known content set.
 | onClear | () => void | — | Called when the clear button is pressed. The component also fires onValueChange('') so a controlled value resets. |
 | placeholder | string | "Search" | Placeholder text shown when the field is empty. |
 | disabled | boolean | false | Dims the control and blocks pointer interaction. |
-| ...props | ComponentPropsWithRef<"input"> | — | All native input attributes (name, autoFocus, ref, aria-invalid, …) pass through to the <input> except value/onChange, which are owned by value/onValueChange, and className, which sizes the whole field. |
+| ...props | ComponentPropsWithRef<"input"> | — | All native input attributes (name, autoFocus, ref, aria-invalid, …) pass through to the <input> except value/onChange, which are owned by value/onValueChange, className, which sizes the whole field, and the native numeric size attribute, which the size prop replaces. |
 
 ## Tokens used
 
-`field-border`, `field`, `foreground`, `muted-foreground`, `ring`, `destructive`
+`field-border`, `field`, `foreground`, `muted-foreground`, `ring`, `destructive`, `panel-field`, `panel-field-hover`
 
 ## Motion
 
@@ -20483,7 +21456,7 @@ Use SearchInput for text queries that filter or search a known content set.
 
 ## Related
 
-- Components: Input, CommandMenu, Combobox
+- Components: Input, CommandMenu, Combobox, Pill
 
 ## Examples
 
@@ -20529,6 +21502,36 @@ const shown = posts.filter((post) => post.title.toLowerCase().includes(q.trim().
 </ul>
 ```
 
+### Filters with search
+
+```tsx
+import { Pill, Row, SearchInput } from "@sableui/react"
+
+const [filter, setFilter] = useState("all")
+const [q, setQ] = useState("")
+
+<Row gap={2} align="center" justify="between" wrap>
+	<Row gap={1}>
+		<Pill size="lg" selected={filter === "all"} onClick={() => setFilter("all")}>All 8</Pill>
+		<Pill size="lg" selected={filter === "products"} onClick={() => setFilter("products")}>Products 5</Pill>
+		<Pill size="lg" selected={filter === "oss"} onClick={() => setFilter("oss")}>Open source 2</Pill>
+	</Row>
+	<SearchInput size="sm" value={q} onValueChange={setQ} placeholder="Find a project…" aria-label="Find a project" className="max-w-64" />
+</Row>
+```
+
+### Sizes
+
+```tsx
+import { SearchInput, Stack } from "@sableui/react"
+
+<Stack gap={1}>
+	<SearchInput size="md" placeholder="Search posts" aria-label="Search posts" />
+	<SearchInput size="sm" placeholder="Find a project…" aria-label="Find a project" />
+	<SearchInput size="xs" placeholder="Filter layers" aria-label="Filter layers" />
+</Stack>
+```
+
 ### Disabled
 
 ```tsx
@@ -20545,7 +21548,7 @@ import { SearchInput } from "@sableui/react"
 
 The heading block for one section of a page: a title (h2 by default), an optional line of description, and actions on the title row — a "View all" link or a couple of buttons — that drop beneath the title only when the row runs out of room.
 
-**Keywords:** section header, section heading, section title, shelf, view all, see all, show all, h2, subsection, optical alignment, bleed
+**Keywords:** section header, section heading, section title, shelf, view all, see all, show all, h2, subsection, optical alignment, bleed, editorial section, large section title
 
 ## Usage
 
@@ -20554,7 +21557,7 @@ Use SectionHeader to head each section below the page title — a home-page shel
 ### Best practices
 
 - Do: Wrap the header and its content in a `<section aria-labelledby={titleId}>` (a flex column with a gap, or a Stack inside it) so the section is a named region and the header's title is its name.
-- Do: Pick titleAs by the document outline (h2 under the page h1, h3 inside an h2 section) and size by visual weight: md for a page's sections and shelves, sm for denser groups like settings.
+- Do: Pick titleAs by the document outline (h2 under the page h1, h3 inside an h2 section) and size by visual weight: lg for an editorial page's sections under a PageHeader size="lg", md for a page's sections and shelves, sm for denser groups like settings.
 - Do: Keep actions to one or two `size="sm"` buttons — the title is centred on that height. A shelf's "View all" is a ghost Button rendered as a link (`render={<a href=… />}`), named for what it opens when the label alone is ambiguous (aria-label="View all new releases").
 - Do: Pass a ghost or link action as a plain Button and let the header align it: the last direct child bleeds by its own padding at the end, so "View all" sits on the edge of the grid below, and the first bleeds at the start, which is the edge once the actions wrap beneath the title. Filled buttons keep their edge on the line. Set bleed="none" on the Button to opt one out.
 - Don't: Nudge a View all onto the edge with -me-3, or wrap the actions in your own div: the header aligns direct children only, and only by each button's real padding. If you must wrap them, set bleed on the Button inside instead.
@@ -20579,11 +21582,11 @@ Use SectionHeader to head each section below the page title — a home-page shel
 | actions | ReactNode | — | Trailing actions on the title row — a View all link or a couple of buttons, size="sm". They stay on the title's row and drop beneath it only when the row runs out of room; the title wraps rather than truncating. A ghost or link Button that ends the group bleeds by its padding at the end (and one that starts it, at the start — the edge once wrapped), so its label lines up with the content below; Button bleed="none" opts out. Direct children only. |
 | titleAs | "h2" \| "h3" \| "h4" | "h2" | The heading element, chosen by the document outline: h2 for a section under the page's h1, h3 for a subsection inside one. |
 | titleId | string | — | The title's id, so the section it heads can point at it: <section aria-labelledby={titleId}>. Generated when omitted. |
-| size | "md" \| "sm" | "md" | Visual weight, independent of the heading level: md (text-heading-3) for a page's sections and shelves; sm (text-heading-4) for denser sets — settings groups, subsections. |
+| size | "lg" \| "md" \| "sm" | "md" | Visual weight, independent of the heading level: lg (text-heading-2 over a text-body-md description) for an editorial page's sections, under a PageHeader size="lg"; md (text-heading-3) for a page's sections and shelves; sm (text-heading-4) for denser sets — settings groups, subsections. lg stops at heading-2: heading-1 is the page title's, one per route. The actions stay centred on the title's first line at every size. |
 
 ## Variants
 
-- **size**: md, sm
+- **size**: lg, md, sm
 
 ## Tokens used
 
@@ -20676,6 +21679,30 @@ import { Button, Entity, Icon, SectionHeader, Stack } from "@sableui/react"
 </section>
 ```
 
+### An editorial section (size lg)
+
+```tsx
+import { Button, Card, CardDescription, CardHeader, CardTitle, Grid, SectionHeader } from "@sableui/react"
+
+<section aria-labelledby="selected-work" className="flex flex-col gap-6">
+	<SectionHeader
+		titleId="selected-work"
+		size="lg"
+		title="Selected work"
+		description="Five projects from the last two years."
+		actions={
+			<Button variant="ghost" size="sm" render={<a href="/work" />} aria-label="View all work">
+				View all
+			</Button>
+		}
+	/>
+	<Grid minItemWidth="16rem" gap={3}>
+		<Card><CardHeader><CardTitle>Tidewater</CardTitle><CardDescription>Brand identity</CardDescription></CardHeader></Card>
+		<Card><CardHeader><CardTitle>Northlight</CardTitle><CardDescription>Product design</CardDescription></CardHeader></Card>
+	</Grid>
+</section>
+```
+
 ### A subsection inside a section
 
 ```tsx
@@ -21269,7 +22296,7 @@ Use Sheet for secondary workflows that slide in while preserving context from th
 
 | Name | Type | Default | Description |
 | --- | --- | --- | --- |
-| Sheet (Root) | Base UI Drawer.Root props (open, defaultOpen, onOpenChange, onOpenChangeComplete, modal, disablePointerDismissal, actionsRef, handle, snapPoints, snapPoint, defaultSnapPoint, onSnapPointChange, snapToSequentialPoints) — minus swipeDirection | — | Controls open state. Uncontrolled by default. The dismiss swipe direction is not a prop: it follows SheetContent's side. onOpenChange reports reason "swipe" when a swipe closed it. |
+| Sheet (Root) | Base UI Drawer.Root props (open, defaultOpen, onOpenChange, onOpenChangeComplete, modal, disablePointerDismissal, actionsRef, handle, snapPoints, snapPoint, defaultSnapPoint, onSnapPointChange, snapToSequentialPoints) — minus swipeDirection | — | Controls open state. Uncontrolled by default. The dismiss swipe direction is not a prop: it follows SheetContent's side. onOpenChange reports reason "swipe" when a swipe closed it. Records the element focused when the sheet opens, trigger or not, and returns focus there on close. |
 | snapPoints | (number \| string)[] | — | Stops a bottom sheet rests at, smallest first: a fraction of the viewport (0.4), pixels (320), or a px/rem string ("20rem"). The panel is the full stop's height and opens at the first stop; a swipe moves between stops and a swipe below the first closes it. side="bottom" only: other sides ignore them, with a development warning. |
 | snapPoint | number \| string \| null | — | The active stop, controlled. Pair with onSnapPointChange; use defaultSnapPoint to open at a different stop uncontrolled. |
 | onSnapPointChange | (snapPoint: number \| string \| null, eventDetails) => void | — | Fires when a swipe (or your code) moves the sheet to another stop. |
@@ -21289,7 +22316,7 @@ Use Sheet for secondary workflows that slide in while preserving context from th
 - The panel scrolls its own content (thin scrollbar, contained overscroll) when it outgrows its bound — the full height on left/right, 80vh on top/bottom.
 - Esc and click-outside dismiss by default; on touch, a swipe toward the sheet's own edge dismisses too. A short or slow drag springs back.
 - Swipe is an extra path, never the only one: Esc, click-outside and SheetClose all still work.
-- Focus matches Dialog: the first tabbable on mouse/keyboard open, the panel itself on touch (so the virtual keyboard stays down); focus returns to the trigger on close.
+- Focus matches Dialog: the first tabbable on mouse/keyboard open, the panel itself on touch (so the virtual keyboard stays down). On close, focus returns to the element that held it when the sheet opened: the SheetTrigger, or your own button when it drives a controlled open. It is captured before the content mounts, so an autoFocus field inside cannot displace it; an explicit finalFocus on SheetContent wins.
 - Render a SheetClose inside SheetContent so screen-reader users can escape the popup.
 - Slide animation runs via data-[starting-style]/data-[ending-style] attributes on the motion-duration token; while swiping the panel tracks the finger directly, and a released swipe finishes on the same token (scaled by flick speed), so reduced motion makes it instant.
 - A mouse drag that starts on sheet content selects text rather than dragging the panel; mouse dragging only starts from the padding edge.
@@ -21419,9 +22446,9 @@ import { ShowMore } from "@sableui/react"
 
 **Status:** stable
 
-Desktop side-navigation rail (in-flow sticky, hidden below lg) with SidebarHeader / SidebarBrand / SidebarNav / SidebarItem / SidebarFooter parts. Items are router-agnostic via the `render` prop; an optional collapsed icon-rail mode reveals labels in tooltips.
+Desktop side-navigation rail (in-flow sticky, hidden below lg) with SidebarHeader / SidebarBrand / SidebarNav / SidebarGroup / SidebarItem / SidebarFooter / SidebarAccount parts, all on one set of columns. Items are router-agnostic via the `render` prop; an optional collapsed icon-rail mode reveals labels in tooltips.
 
-**Keywords:** sidebar, navigation, app chrome, rail
+**Keywords:** sidebar, navigation, app chrome, rail, nav group, section label, account, user menu, profile, account switcher, workspace switcher, sidebar footer
 
 ## Usage
 
@@ -21433,6 +22460,9 @@ Use Sidebar for persistent desktop navigation or application chrome outside the
 - Do: Keep item labels predictable and active state obvious.
 - Do: Set surface="page" when a full-width top bar sits above the rail. A theme's tinted or dark rail is for a full-height rail that frames the app.
 - Do: Keep surface="rail" inside AppShell frame="inset": the rail's tint becomes the ground the main panel floats on. Do not add a border-r class back — the gap is the divider.
+- Do: Group items with SidebarGroup and end the rail with one SidebarAccount that opens the account menu (settings, appearance, sign out). Every part sits on the same icon and label columns, at either density.
+- Don't: Do not put SideNav, an Entity or a stack of ghost Buttons in the rail. Each brings its own insets, so the icons and labels land on four different columns. SideNav is the in-page section list; the rail has its own parts.
+- Don't: Do not put a Badge or pill in the account row. Its one quiet detail line carries the plan, role or 'Demo'.
 - Don't: Do not use Sidebar for page-local settings, filters, or temporary action groups.
 - Don't: Do not put page content in it. It is fixed-width chrome OUTSIDE the content grid, so anything in it is exempt from the page's measure and rhythm.
 
@@ -21447,9 +22477,11 @@ Use Sidebar for persistent desktop navigation or application chrome outside the
 
 | Name | Type | Description |
 | --- | --- | --- |
-| SidebarHeader | div props | The top of the rail, at least 64px tall. It holds SidebarBrand and may take a second row under it, such as a search field or a notifications button: give that row basis-full and the header grows to hold it instead of clipping. |
+| SidebarHeader | div props | The top of the rail, at least 64px tall (the chrome bar's height inside a compact Workspace, so it lines up with the WorkspaceBar beside it). It holds SidebarBrand and may take a second row under it, such as a search field or a notifications button: give that row basis-full and the header grows to hold it instead of clipping. |
 | SidebarBrand | { mark: ReactNode; label: ReactNode; render?: useRender.RenderProp } + div props | The brand row, inside SidebarHeader, on the same grid as SidebarItem: mark in the icons' 24px slot, label on the labels' column, so a logo lines up with the nav below it without copying the rail's inset numbers. Collapsed, it shows the mark alone (named by a string label). render={<Link to="/" />} makes it the home link. |
-| SidebarItem | { label: ReactNode; icon?: ReactNode; active?: boolean; badge?: ReactNode; render?: useRender.RenderProp } + button props | A single nav row. label is the row text (inline when expanded, in a hover tooltip when collapsed); icon is the leading icon node (the consumer swaps fill weight for the active state); active marks the current route (accent fill + aria-current="page"); badge is a trailing node (e.g. a count) pushed to the row end and hidden when collapsed; render composes another element, e.g. render={<Link to="/x" />}. |
+| SidebarItem | { label: ReactNode; icon?: ReactNode; active?: boolean; badge?: ReactNode; render?: useRender.RenderProp } + button props | A single nav row, 44px on a page and 32px inside a compact scope such as a Workspace (the rail reads the density; nothing to set). label is the row text (inline when expanded, in a hover tooltip when collapsed); icon is the leading icon node (the consumer swaps fill weight for the active state); active marks the current route (accent fill + aria-current="page"); badge is a trailing node (e.g. a count) pushed to the row end and hidden when collapsed; render composes another element, e.g. render={<Link to="/x" />}. |
+| SidebarGroup | { label?: ReactNode } + div props | A labelled run of SidebarItems inside SidebarNav ("Workspace", "Favorites"). The label starts on the items' icon column; collapsed, a hairline stands in for it and the label stays as the group's accessible name. |
+| SidebarAccount | { avatar: ReactNode; label: ReactNode; detail?: ReactNode; indicator?: ReactNode \| false; render?: useRender.RenderProp } + button props | The account row at the foot of the rail, inside SidebarFooter: the avatar in the icon slot (Avatar xs on a page rail, 2xs in a compact one), the label on the label column, one muted detail line, and an up-down chevron. Make it the trigger of the account Menu (render it through MenuTrigger render) and put Settings, appearance and sign-out there; it holds its fill while the menu is open. Collapsed, the avatar alone, with the label in a tooltip. |
 
 ## Props
 
@@ -21509,6 +22541,14 @@ const [collapsed, setCollapsed] = useState(false)
 <Sidebar collapsed={collapsed}><SidebarNav><SidebarItem icon={<Icon name="home" />} label="Home" active render={<Link to="/" />} /></SidebarNav><SidebarFooter><Button variant="ghost" size="icon" onClick={() => setCollapsed((c) => !c)} aria-label="Toggle sidebar"><Icon name="chevron-left" /></Button></SidebarFooter></Sidebar>
 ```
 
+### Grouped nav with an account menu
+
+```tsx
+import { Avatar, Icon, Menu, MenuContent, MenuItem, MenuSeparator, MenuTrigger, Sidebar, SidebarAccount, SidebarBrand, SidebarFooter, SidebarGroup, SidebarHeader, SidebarItem, SidebarNav } from "@sableui/react"
+
+<Sidebar><SidebarHeader><SidebarBrand mark={<Avatar shape="square" size="xs" fallback="F" alt="" />} label="Forma Studio" /></SidebarHeader><SidebarNav><SidebarItem icon={<Icon name="inbox" />} label="Inbox" badge={<span className="text-ui-num">4</span>} /><SidebarGroup label="Workspace"><SidebarItem icon={<Icon name="folder" />} label="Projects" active /><SidebarItem icon={<Icon name="users" />} label="Clients" /></SidebarGroup></SidebarNav><SidebarFooter><Menu><MenuTrigger render={<SidebarAccount avatar={<Avatar size="xs" fallback="EL" alt="" />} label="Emma Lee" detail="Forma Studio" />} /><MenuContent side="top" align="start"><MenuItem>Settings</MenuItem><MenuSeparator /><MenuItem>Sign out</MenuItem></MenuContent></Menu></SidebarFooter></Sidebar>
+```
+
 ### Inline (inside a bounded frame)
 
 ```tsx
@@ -22623,6 +23663,7 @@ Use Tabs to switch between related panels within the same page context.
 ### Best practices
 
 - Do: Use tabs when each panel is peer content and users may compare or switch often.
+- Do: In tool chrome (a WorkspaceBar, a compact panel header) use variant="pill" for a view switch such as Overview / Issues / Updates: it reads as a control beside the bar's other controls. Underline is the page-section idiom; inside a WorkspaceBar it sits on the bar's hairline rather than drawing its own.
 - Do: Keep tab labels short and make the active tab unmistakable.
 - Do: Use variant="pill" for a short switcher inside a card or toolbar (Preview / Code, List / Grid); keep the default underline for sections of a page.
 - Don't: Do not use Tabs for unrelated pages or primary navigation that needs distinct URLs. → use **SideNav**, **NavigationMenu**
@@ -24111,7 +25152,7 @@ import { Video } from "@sableui/react"
 
 The shell for a tool: a fixed viewport partitioned into independently scrolling regions, with a compact density scope, a skip link, and a canvas landmark.
 
-**Keywords:** workspace, tool, editor, shell, frame, canvas, chrome, panels, density, viewport
+**Keywords:** workspace, tool, editor, shell, frame, canvas, chrome, panels, density, viewport, issue tracker, tracker, inspector, reading view, mobile, responsive, bottom nav, media query, breakpoint, top bar, topbar
 
 ## Usage
 
@@ -24122,6 +25163,9 @@ Use Workspace as the outer frame for a tool — an editor, a console, a canvas a
 - Do: Put a PanelGroup in the body and a WorkspaceCanvas inside it, so panels are aside chrome and the work surface is the main landmark.
 - Do: Let each panel own its scrolling. The shell never scrolls, and the canvas clips rather than scrolls — panning is the viewport's job.
 - Do: Keep the density scope at compact unless you have a specific reason; the workspace register's measured control ladder is what makes tool chrome read as tool chrome.
+- Do: Put a WorkspaceBar inside a column when the bar belongs to that column only. An issue tracker's bar (breadcrumb, view tabs, filters) sits above the list, while the sidebar and the inspector beside it run the full height: put the WorkspaceBar first inside the WorkspaceCanvas, not in the `toolbar` slot, which spans every panel. Don't hand-build a fixed-height header for it.
+- Do: Wrap a reading view inside the workspace (a project overview, an update, a doc, release notes) in <Density value="comfortable">. The compact scope maps body text to the 11–12px UI tiers, which is right for chrome and too small for paragraphs; the comfortable scope gives prose its page size again while the chrome around it stays compact.
+- Do: Plan the phone layout with the shell rather than around it: pass a BottomNav to `bottomNav`, and give docked Panels `narrow="sheet"` (an inspector, a navigation rail) or `narrow="hidden"`. Don't measure the viewport with a resize listener, render the inspector twice, or subtract the nav's height from 100dvh.
 - Don't: Nest a Region or Page inside it to set a width. Region caps are a page-register idea; a workspace is edge-to-edge and its panels are fixed-width chrome outside the content grid.
 - Don't: Hardcode a control height (h-[32px]). CI rejects it (raw-control-height); read the ladder instead, e.g. h-(--control-sm), so the density scope can size it.
 - Don't: Put a Card in the chrome. Use PanelSection — a card inside a narrow panel spends its border and inset on nothing.
@@ -24135,6 +25179,7 @@ Use Workspace as the outer frame for a tool — an editor, a console, a canvas a
 | Body | yes | The flexible middle row, normally a PanelGroup. Constrained so its children can shrink and scroll. |
 | WorkspaceCanvas | no | The work surface and the main#main-content landmark the skip link targets. Clips rather than scrolls. |
 | StatusBar | no | Bottom chrome for ambient document facts. |
+| BottomNav | no | Phone navigation in the `bottomNav` slot. Its row is reserved below lg and gone above it, so the body ends where the nav begins. |
 
 ## Subcomponents
 
@@ -24142,6 +25187,8 @@ Use Workspace as the outer frame for a tool — an editor, a console, a canvas a
 | --- | --- | --- |
 | WorkspaceBar | ComponentProps<'header'> | The top chrome strip, sized to --chrome-bar-height with a hairline beneath. |
 | WorkspaceCanvas | ComponentProps<'main'> | The work surface: renders main#main-content, fills the body, clips its overflow. |
+| useMediaQuery | (query: string, options?: { serverValue?: boolean }) => boolean | True while a media query matches, read through useSyncExternalStore: no resize listener, no setState in an effect, no hydration mismatch (the server reports serverValue, default false). Use it to branch structure a class cannot express; style-only changes stay as lg: classes. |
+| useBelowBreakpoint | (breakpoint?: "sm" \| "md" \| "lg" \| "xl" \| "2xl", options?: { serverValue?: boolean }) => boolean | True below a named breakpoint (default lg), flipping at the width where that breakpoint's classes start to apply (Tailwind's sm 40 / md 48 / lg 64 / xl 80 / 2xl 96rem). Panel's `narrow` uses it; reach for it instead of a hand-rolled window.innerWidth check. |
 
 ## Props
 
@@ -24149,6 +25196,7 @@ Use Workspace as the outer frame for a tool — an editor, a console, a canvas a
 | --- | --- | --- | --- |
 | toolbar | ReactNode | — | Top chrome, normally a WorkspaceBar. |
 | statusBar | ReactNode | — | Bottom chrome, normally a StatusBar. |
+| bottomNav | ReactNode | — | Phone navigation, normally a BottomNav. Below lg (BottomNav's own breakpoint) the shell reserves the nav's height as its last row, so the body and the status bar end above the nav instead of under it; above lg the row is gone. Every slot is optional: the body is the shell's one growing row whichever of toolbar, statusBar and bottomNav are present. |
 | density | "compact" \| "comfortable" | "compact" | Density scope for everything inside. Sets the --control-* ladder via data-density; compact is the workspace register. Nothing hardcodes a height, so the same size="md" Button is 40px on a page and 32px inside a compact Workspace. A Dialog opened from inside resets to comfortable, because a modal is a page-register surface even when a tool launched it. |
 | skipLinkLabel | string | "Skip to canvas" | Text for the skip link that targets the canvas landmark. |
 
@@ -24230,6 +25278,79 @@ import { Input, Panel, PanelGroup, PanelSection, PropertyRow, StatusBar, Workspa
 </Workspace>
 ```
 
+### Issue tracker: column bar, docked inspector, phone sheet
+
+```tsx
+import { BottomNav, BottomNavItem, BreadcrumbItem, BreadcrumbLink, BreadcrumbPage, Breadcrumbs, BreadcrumbSeparator, Button, Icon, Input, Panel, PanelGroup, PanelSection, PropertyRow, StatusBar, Workspace, WorkspaceBar, WorkspaceCanvas } from "@sableui/react"
+
+function Tracker() {
+  const [selected, setSelected] = useState<string | null>("AES-104")
+  return (
+    <Workspace
+      bottomNav={
+        <BottomNav>
+          <BottomNavItem showLabel label="Issues" icon={<Icon name="list" />} active />
+          <BottomNavItem showLabel label="Inbox" icon={<Icon name="inbox" />} />
+        </BottomNav>
+      }
+      statusBar={<StatusBar><span>12 issues</span></StatusBar>}
+    >
+      <PanelGroup>
+        <Panel label="Navigation" width={220} narrow="hidden">
+          <PanelSection title="Workspace">
+            <PropertyRow label="Team"><Input defaultValue="Studio" /></PropertyRow>
+          </PanelSection>
+        </Panel>
+        <WorkspaceCanvas className="flex flex-col">
+          <WorkspaceBar>
+            <Breadcrumbs>
+              <BreadcrumbItem><BreadcrumbLink href="#">Studio</BreadcrumbLink></BreadcrumbItem>
+              <BreadcrumbSeparator />
+              <BreadcrumbItem><BreadcrumbPage>Digital flagship</BreadcrumbPage></BreadcrumbItem>
+            </Breadcrumbs>
+          </WorkspaceBar>
+          <div className="min-h-0 flex-1 overflow-y-auto scrollbar-quiet">
+            <Button size="xs" variant="ghost" onClick={() => setSelected("AES-104")}>AES-104 Refine product page</Button>
+          </div>
+        </WorkspaceCanvas>
+        <Panel
+          label="Issue details"
+          width={320}
+          narrow="sheet"
+          open={selected !== null}
+          onOpenChange={(open) => !open && setSelected(null)}
+        >
+          <PanelSection title={selected ?? ""}>
+            <PropertyRow label="Status"><Input defaultValue="In progress" /></PropertyRow>
+          </PanelSection>
+        </Panel>
+      </PanelGroup>
+    </Workspace>
+  )
+}
+```
+
+### Reading view inside a workspace
+
+```tsx
+import { Density, PanelGroup, Workspace, WorkspaceCanvas } from "@sableui/react"
+
+<Workspace>
+  <PanelGroup>
+    <WorkspaceCanvas className="overflow-y-auto scrollbar-quiet">
+      <Density value="comfortable">
+        <article className="max-w-prose p-6">
+          <h2 className="text-heading-3">Project overview</h2>
+          <p className="mt-3 text-body-md text-muted-foreground">
+            Paragraphs keep their page size here, while the chrome around the canvas stays compact.
+          </p>
+        </article>
+      </Density>
+    </WorkspaceCanvas>
+  </PanelGroup>
+</Workspace>
+```
+
 ### Comfortable density
 
 ```tsx
@@ -24439,8 +25560,10 @@ Which token to reach for, and what it is most often confused with. Generated fro
 - **`region-ultrawide (legacy — prefer region-full)`** — Deprecated. Kept so existing usage keeps resolving. *Use for:* Nothing new. Use `region-full`.
     - **Not** `region-full`, which is what this became.
 
-### typographyOverrides (60)
+### typographyOverrides (61)
 
+- **`type-base`** — The base size the page type scale is built on, as a unitless px number — 16 by default. Every page tier keeps its ratio to it, so `14` rebuilds the whole scale at 14, and the baseline step and spacing follow the body down. *Use for:* When the product asks for smaller or larger type everywhere: a dense technical tool at 13-14, a reading product at 17. Set it on :root, a theme scope or a preset (`tokens.shared["type-base"]: "14"`), not per component.
+    - **Not** Changing the root font-size, which also moves every rem the app wrote and the control ladder; or overriding tier sizes one by one, which breaks the ratios between them. Unitless: `14`, never `14px`.
 - **`type-display-4xl-size`** — The largest type: display-lg through display-4xl. Marketing-scale, one per view at most. *Use for:* A landing page hero, a section opener on a brand surface.
     - **Not** `heading-1` for page titles. Display is a *statement*; headings are *structure*. A settings page titled in display-3xl looks like an advert.
 - **`type-title-lg-size`** — The title of a *component*, not of a document. *Use for:* A card's heading, a dialog title, a section label inside a panel.
@@ -24714,7 +25837,7 @@ The `@utility` and `@custom-variant` layer in `styles.css`: what each one is, wh
     - **Instead of** `scrollbar-quiet` on a vertical list. A vertical region with no bar and no fade tells a reader nothing about how far through they are.
     - `<div className="flex gap-3 overflow-x-auto scrollbar-hidden">…</div>`
 
-### text (12)
+### text (13)
 
 - **`sable-list`** — A bulleted list as typography: body type, a hanging muted marker, and item rhythm. Put it on a native `<ul>`. *Use for:* Running content with bullets: release notes, a feature list, steps that are not ordered.
     - **Instead of** A stack of `<div>`s with a hand-drawn dot, or an unstyled `<ul>` that inherits the reset (no markers, no indent).
@@ -24731,6 +25854,9 @@ The `@utility` and `@custom-variant` layer in `styles.css`: what each one is, wh
 - **`text-overline`** — The eyebrow / overline / kicker tier: small, letter-spaced, uppercase by default (a theme may set sentence case via `--type-overline-transform`). *Use for:* A section eyebrow above a heading, a stat's label, a badge-style category line. Sits ABOVE and categorises.
     - **Instead of** `text-label-xs uppercase tracking-wider` assembled by hand, or `text-caption`, which sits BELOW and explains. In tool chrome, panel headers use `text-ui-section` instead.
     - `<p className="text-overline text-muted-foreground">Latest news</p>`
+- **`text-ui-title`** — The title of what a panel or inspector shows — the open issue, the selected object: 14px at 600 on a 20px line, one step above `text-ui-md`. *Use for:* The one title at the top of an inspector, a docked panel or a peek view inside the workspace register. Compact `text-title-lg` resolves to it on its own.
+    - **Instead of** `text-ui-md` made heavier (a title the size of the description under it reads as a label), or `text-heading-*`, which is page structure rather than chrome.
+    - `<h2 className="text-ui-title text-panel-foreground">Refine product detail page</h2>`
 - **`text-ui-md`** — Workspace-register chrome text, the default tier: ~12px at weight ~500 on 16px leading. *Use for:* Labels and values in tool chrome — panels, inspectors, toolbars, trees — inside the workspace register.
     - **Instead of** `text-label-sm` or `text-body-sm` in a dense panel (the page register's weights read as shouting at this size), or a size class plus a weight class composed by hand.
     - `<span className="text-ui-md text-panel-foreground">Opacity</span>`