@ultimat3/ui 23.0.0 → 25.0.0

package/README.md

@@ -20,10 +20,32 @@ channels** so `rgb(var(--color-accent) / 0.12)` gives a tint with no extra token
 | `scrim` | modal backdrops |
 | `accent` / `accent-strong` / `accent-fg` | primary action, its hover, text on it |
 | `success` / `warning` / `danger` / `info` | status solid, each with a `-soft` tint and a `-fg` text-on-solid |
+| `chart-1` … `chart-8` | categorical chart series, in assignment order (`CHART_ROLES`) |
+
+The chart series are Okabe–Ito-derived and **measured, not picked** (`As of 2026-10`): each clears
+3:1 against all four surfaces in both themes (WCAG 1.4.11, in `CONTRAST_PAIRS`), and every pair
+stays at least `CHART_DISTINCT_MIN` (ΔE 10) apart under protanopia, deuteranopia and tritanopia
+simulation (`colour-vision.test.ts`). A ninth series reuses `chart-1` with a second encoding — a
+dash, a pattern, a label — never a ninth hue.
 
 Scales: `--space-*` (4px base), `--stroke-*` (line weights: `hairline thick heavy`), `--text-*` (fluid `clamp()`), `--radius-*`,
 `--shadow-*` (themed — dark gets deeper, higher-alpha shadows), `--duration-*`,
-`--easing-*`, `--z-*` (named ladder, no magic numbers).
+`--easing-*`, `--z-*` (named ladder, no magic numbers), `--touch-target` (44px, as `2.75rem`).
+
+| Shadow rung (`t.shadow('…')`) | What it is |
+|---|---|
+| `xs` `sm` `md` `lg` `xl` | elevation: a drop shadow, deeper and darker in dark |
+| `glow-sm` `glow-md` `glow-lg` | a halo drawn from the **accent** role, no offset — a live tile, a focused panel, a selected series |
+| `tinted-sm` `tinted-md` `tinted-lg` | coloured elevation: a drop shadow in the accent hue |
+
+Glow and tinted rungs read `--color-accent`, so a brand's accent recolours them with no second
+override. `SHADOW_NAMES` / `ShadowName` is the list.
+
+| Font slot | Default stack | Read by |
+|---|---|---|
+| `--font-sans` | `system-ui` … | body copy |
+| `--font-mono` | `ui-monospace` … | `code` and `pre`, error frames |
+| `--font-data` | `ui-monospace`, `'Cascadia Mono'`, `'JetBrains Mono'` … | `@include t.data-text` — figures in tables, axes and stat tiles, ids, `Kbd` |
 
 Authoring helpers, from the same `@use '@ultimat3/ui/tokens' as t` — an app writes no mixin of its own for any of them:
 
@@ -34,6 +56,11 @@ Authoring helpers, from the same `@use '@ultimat3/ui/tokens' as t` — an app wr
 | `@include t.respond-between(md, lg)` | `@media (min-width: 768px) and (max-width: 1023.98px)` |
 | `t.rem(24px)` | `1.5rem` — px, rem or a unitless px count in; `t.rem(20px, 10px)` states another root |
 | `t.fluid(1rem, 2rem, 20rem, 80rem)` | `clamp(1rem, 0.6666666667rem + 1.6666666667vw, 2rem)` — the first size at a 20rem viewport, the second at 80rem (the default range), linear between. Takes px too; a size that shrinks is legal |
+| `@include t.data-text` | `font-family: var(--font-data); font-variant-numeric: tabular-nums` — columns of figures that do not wobble |
+| `@include t.touch-target` | `min-block-size` + `min-inline-size` of `var(--touch-target)` — the box itself is hittable |
+| `@include t.touch-target($extend: true)` | the box keeps its size; a centred `::after` grows the HIT AREA to the target — a chart point, a dense icon row |
+| `@include t.glow-edge` | `box-shadow: inset 0 0 0 var(--stroke-hairline) <accent / 0.55>, var(--shadow-glow-sm)` — `t.glow-edge('glow-lg', 0.8)` picks rung and ring alpha |
+| `@include t.grid-texture` | a faint accent grid on a `t.space(6)` pitch with scanlines over it, as `background-image` only; `t.grid-texture(t.space(4), 0.1, false)` drops the scanlines. Withdrawn under `prefers-contrast: more` and `forced-colors: active`; animates nothing |
 
 A rung is `sm md lg xl 2xl`, quoted or bare. Prefer a container query (`t.container` + `t.container-query`) to all three breakpoint mixins.
 
@@ -44,10 +71,10 @@ A rung is `sm md lg xl 2xl`, quoted or bare. Prefer a container query (`t.contai
 | No raw colours | a hex or `rgb()` literal in a component stylesheet fails review; `tokens.test.ts` asserts the shared SCSS is hex-free |
 | No Tailwind | not a dependency, not a config, not an escape hatch |
 | No CSS-in-JS | styles are `Foo.module.scss` next to `Foo.tsx`, compiled at build |
-| No physical directions | `margin-inline`, `inset-inline-start`, `text-align: start` — RTL needs no second stylesheet |
+| No physical directions | `margin-inline`, `inset-inline-start`, `text-align: start` — RTL needs no second stylesheet. Centring is `inset-inline` + `margin-inline: auto`, never a 50% logical inset beside a physical −50% translate, and an edge shadow's physical x offset gets a `[dir='rtl']` mirror (`components/rtl-sheets.test.ts`) |
 | No hardcoded strings | labels are props, or `t()` through `UI_KEYS` |
 | One token source | `src/tokens/*.scss` is canonical; `tokens.ts` mirrors it and `x verify` fails on drift |
-| AA contrast, both themes | `contrast.test.ts` measures every pairing a component renders — text, status fills, soft tints, focus rings, borders |
+| AA contrast, both themes | `contrast.test.ts` measures every pairing a component renders — text, status fills, soft tints, focus rings, borders, chart series (3:1 on every surface) |
 
 ## Contrast
 
@@ -118,16 +145,16 @@ review comment. Three properties are structural, not documented:
 
 ## Toasts
 
-`Toast` and `ToastRegion` render; `createToastStore()` is the queue behind them, and `<Toaster>` is
+`Toast` and `ToastRegion` render; `toastStore()` is the queue behind them, and `<Toaster>` is
 the one way to draw it.
 
 ```tsx
-import { createToastStore, Toaster } from '@ultimat3/ui';
+import { toastStore, Toaster } from '@ultimat3/ui';
 
 declare const t: (key: string) => string;
 declare const restore: () => void;
 
-const toasts = createToastStore();
+const toasts = toastStore();
 toasts.show({ message: t('post.saved'), tone: 'success' });
 toasts.show({ message: t('post.deleted'), action: { label: t('undo'), onAction: restore } });
 
@@ -157,11 +184,32 @@ Four composites cover the frame of an app screen. Below them are `Container`,
 | `Section` | a labelled `section` with a real heading and `aria-labelledby` | second-level structure inside a page |
 | `Toolbar` | `role="toolbar"` strip, start + end slots, arrow-key roving between its buttons (`As of 2026-08`) | filters and actions above a table or list |
 
-`AppShell` holds no state: below `md` the sidebar becomes a band above the content,
-and an off-canvas menu is `Drawer` — the one component that already does that.
+`AppShell` holds no state: below `md` the sidebar is a native `popover` panel behind a menu
+button (`menuLabel`), opened, closed and dismissed by the browser with no script; where `popover`
+is unsupported it stays a band above the content. A modal off-canvas panel is still `Drawer`.
 Heading levels are props (`headingTag`, `nextHeadingLevel`), so a nested `Section`
 never skips a level.
 
+### Data display
+
+Server-rendered, no island and no JS: a chart costs a route nothing until it asks to be focusable.
+Every chart stands in a `ChartFrame` — a `figure`, its caption, a legend and a visually-hidden data
+table — and every series has a dash and a marker as well as a colour (`chart-1` … `chart-8`).
+
+| Component | Renders | Use for |
+|---|---|---|
+| `LineChart` / `AreaChart` | multi-series line on a 1-2-5 axis (filled for `AreaChart`); `null` is a gap | a trend over keys |
+| `BarChart` | bars, an optional stacked second series with a legend | a count per key |
+| `DonutChart` | ring segments, a centre figure, a legend with value and share | parts of a whole |
+| `Gauge` | a 270° `meter` dial with a tone and a visible label | one value against its max |
+| `ChartFrame` | the figure, caption, legend and data table every chart stands in | a custom chart |
+| `niceTicks` · `chartTable` · `seriesStyle` | axis ticks, the fallback table, a series' dash and marker | building a custom chart |
+| `DataTable` | sort, cursor paging, states; `narrow: 'cards'` (default) collapses rows to labelled cards below `sm`; `Column.priority` hides a column behind a per-row disclosure, never losing its value; `stickyFirstColumn` | any list of records |
+| `Table` | a captioned table with a sticky header; `stickyFirstColumn` | static tabular data |
+| `InlineBar` | a caller-formatted figure with a decorative proportional bar | a number in a table cell |
+| `StatTile` / `Meter` / `Sparkline` | a KPI with its delta; a bar against a max; an inline mini line | the KPI row |
+
+
 ```tsx
 <AppShell header={<Toolbar label={t('nav.main')}>{nav}</Toolbar>} sidebar={<SideNav />}>
   <PageHeader
@@ -281,8 +329,13 @@ Components cancel theirs on cleanup, so a filter never fires into a tree that is
 override, no forked package, no second entry point — one call, validated, rendered
 as the custom properties that beat `theme.scss` at every specificity level it emits.
 
+An app declares it once, as `export const brand` in `apps/web/shared/theme.ts`. `x dev`, the
+container, `x build`'s static export and `/admin` inline it after the surface stylesheet, with its
+`sha256` in `style-src`; with no such module nothing is emitted. There is nothing to paste.
+
 ```ts
-import { brandStyleCspSource, brandStyleTag, defineTheme } from '@ultimat3/ui';
+// apps/web/shared/theme.ts
+import { defineTheme } from '@ultimat3/ui';
 
 export const brand = defineTheme({
   colors: {
@@ -292,27 +345,56 @@ export const brand = defineTheme({
   radius: { md: '0.125rem', lg: '0.25rem' },
   font: { sans: "Inter, system-ui, sans-serif" },
 });
-
-// in <head>, AFTER global.scss
-`${brandStyleTag(brand)}`;
-
-// …and the one source that admits it under the framework's locked CSP. The baseline is
-// `style-src 'self' 'sha256-…'` with no 'unsafe-inline', so a tag whose hash the header does
-// not carry is a stylesheet the browser parses zero rules out of.
-`Content-Security-Policy: style-src 'self' ${brandStyleCspSource(brand)}`;
 ```
 
+`brandStyleTag(brand)` and `brandStyleCspSource(brand)` are what the framework emits — exported
+for a host that renders documents itself.
+
 | Slot | Accepts | Refused with |
 |---|---|---|
 | `colors.light` / `colors.dark` | any `ColorRole`, as `R G B` channels | `X_TOKEN_UNKNOWN` for the role, `X_UI_INVALID_VALUE` for the value |
 | `radius` | any `RadiusName`, as a bare CSS length | `X_TOKEN_UNKNOWN` / `X_UI_INVALID_VALUE` |
-| `font` | `sans`, `mono`, as a `font-family` list | `X_TOKEN_UNKNOWN` / `X_UI_INVALID_VALUE` |
+| `font` | `sans`, `mono`, `data`, as a `font-family` list | `X_TOKEN_UNKNOWN` / `X_UI_INVALID_VALUE` |
+| `shadows.light` / `shadows.dark` | any `ShadowName`, as a `box-shadow`: comma-separated layers of lengths plus `rgb(R G B / a)` or `rgb(var(--color-<role>) / a)`, or `none` | `X_TOKEN_UNKNOWN` for the rung, `X_UI_INVALID_VALUE` for the value |
+| `preset` | a `THEME_PRESETS` name — `'scifi'` | `X_UI_INVALID_VALUE` |
 
 Values are validated, never escaped: the output goes into a `<style>` element, so
 anything carrying `;`, `}` or `</style>` is a refusal at the app's entry point rather
 than a CSS injection. Every component in the system follows the override — they only
 ever read the roles, never a colour.
 
+### The sci-fi preset
+
+`defineTheme({ preset: 'scifi' })` swaps the whole palette for a dashboard look: near-black
+panels in dark (`bg` `5 7 13`), cool paper in light, a cyan `accent` whose `accent-strong` (hover)
+is magenta, its own eight chart series, sharper radii, and — dark only — every elevation rung
+redrawn as an accent hairline plus a halo, so each card and popover has a glowing edge with no
+stylesheet of yours. It is a **base**: every other slot layers onto it role by role, and the
+merged palette is what `CONTRAST_PAIRS` measures.
+
+```ts
+import { defineTheme } from '@ultimat3/ui';
+
+export const brand = defineTheme({
+  preset: 'scifi',
+  colors: { dark: { 'chart-1': '120 220 255' } },   // scifi, with your own first series
+});
+```
+
+The preset ships tokens only (axiom 8). The texture and the edge are yours to place:
+
+```scss
+@use '@ultimat3/ui/tokens' as t;
+
+.main { background-color: t.role('bg'); @include t.grid-texture; }
+.tile { @include t.surface; @include t.glow-edge; }
+.tile[aria-current='true'] { @include t.glow-edge('glow-lg', 0.8); }
+```
+
+A dashboard that should open dark whatever the OS says sets the app default theme
+(`data-theme-default`, [Theme resolution](#theme-resolution)) — the preset never forces a theme.
+Like every brand, export it from `apps/web/shared/theme.ts` and the framework ships it with its CSP hash.
+
 ## The two render paths
 
 Every component renders on the server. Half of them read the ambient presentation context —
@@ -358,7 +440,7 @@ import '../../shared/global'; // `shared/global.scss` is the app's one `@use '@u
 
 ```tsx
 // A client entry — an island's `mount()`, or a hydrated app shell. In this order, once.
-import { createTranslator } from '@ultimat3/i18n';
+import { catalogTranslator } from '@ultimat3/i18n';
 import { setSolidRuntime, UiProvider } from '@ultimat3/ui';
 import type { JSX } from 'solid-js';
 import {
@@ -395,7 +477,7 @@ export function mount(el: HTMLElement, props: Props): void {
         locale={props.locale}
         timeZone={props.timeZone}
         currency={props.currency}
-        t={createTranslator(props.strings, props.locale)}
+        t={catalogTranslator(props.strings, props.locale)}
       >
         {props.tree}
       </UiProvider>
@@ -406,7 +488,7 @@ export function mount(el: HTMLElement, props: Props): void {
 ```
 
 **The prop is `t`, it takes a `Translator`, and omitting it is not neutral.** `<UiProvider>` with
-no `t` falls back to `fallbackTranslator(locale)` — `createTranslator({}, locale)`, an **empty**
+no `t` falls back to `fallbackTranslator(locale)` — `catalogTranslator({}, locale)`, an **empty**
 catalog — so every built-in string in the tree renders its key: `<Dialog>`'s close button reads
 `⟦ui.close⟧`, `<Field>`'s marker `⟦ui.required⟧`. The keys are `UI_KEYS`, and they live in the
 framework catalog the SERVER has registered; a browser chunk has none, which is why
@@ -462,7 +544,7 @@ is a type error rather than a review comment.
 
 | Prop | Emitted |
 |---|---|
-| `variants` | `srcset`, descriptors derived and ordered ascending (`srcsetFor`) |
+| `variants` | `srcset`, descriptors derived and ordered ascending (`variantSrcset`) |
 | `sources` | `{ avif?, webp? }` width lists → `<source type="image/avif">`, then `image/webp`, before the `<img>` (`sourceSetsFor`) |
 | `sizes` | `sizes`, verbatim, on the `<img>` and every `<source>` |
 | `priority` | `loading="eager"` + `fetchpriority="high"`; otherwise `lazy` + `auto`, always `decoding="async"` |
@@ -496,14 +578,15 @@ one politeness — `politeness="assertive"` for a region that carries errors alo
 
 ## Theme resolution
 
-`explicit choice in localStorage` → `OS preference`. `setTheme()` persists,
-`clearTheme()` forgets and follows the OS again, and the OS listener only applies
-while nothing is stored. `themeInlineScriptTag()` goes in `<head>` and applies the
-result before first paint, so there is no flash and screenshots are deterministic:
-
-```
-Content-Security-Policy: script-src 'self' 'sha256-…'   # themeInlineScriptCspSource()
-```
+`explicit choice in localStorage` → `the theme already on <html>` → `defaultTheme(env)`: the
+app's `theme.defaultMode` (`data-theme-default`), and the OS only when that is `'system'` or
+absent. The framework's boot inlines `themeScript({ fallback })` from
+`@ultimat3/render` and stamps `data-theme` before first paint, and `resolveTheme()` reads it back
+through `ThemeEnv.current()` — so with `defaultMode: 'dark'` on a light-OS machine the first toggle
+flips to light rather than writing the dark already on screen. `setTheme()` persists,
+`clearTheme()` forgets and returns to the app default (`data-theme-default`, which the boot stamps
+from `theme.defaultMode`; the OS for `'system'`), and the OS listener applies only while nothing is
+stored and that default is `'system'`.
 
 ## Forms bound to an action's input schema
 
@@ -582,9 +665,12 @@ refuses the submit again because Enter in a text field touches no button at all.
 
 A failed submit focuses the **first invalid control** (`form.firstInvalidField()`, in declaration
 order — a server may report the last field first), and the announced summary keeps the focus only
-when the rejection names no control at all. `form.touch(path)` and `form.edit(path, value)` record
-touched and dirty against the binding's `initial`; an empty control and an absent baseline are the
-same thing, so deleting what you just typed leaves the form clean.
+when the rejection names no control at all. Focus moves once per failure: a `touch()` or `edit()`
+afterwards re-renders the form but never pulls focus back, so the user can work down the list.
+`form.touch(path)` and `form.edit(path, value)` record touched and dirty against the binding's
+`initial`; an empty control and an absent baseline are the same thing, so deleting what you just
+typed leaves the form clean. A successful submit clears dirty except for the fields edited while it
+was in flight — the server never saw those, so a navigation guard still has something to protect.
 
 Blur-time validation is deliberately **absent**: this binding is server-authoritative, the local
 parse's value is already discarded, and a client-side "is this field valid" would be a second source

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/ui",
-  "version": "23.0.0",
+  "version": "25.0.0",
   "description": "SolidJS design system: semantic design tokens, dark/RTL-ready SCSS modules, a11y primitives",
   "license": "MIT",
   "type": "module",
@@ -40,7 +40,7 @@
     "LICENSE"
   ],
   "engines": {
-    "bun": ">=1.4.0"
+    "bun": ">=1.4.2"
   },
   "scripts": {
     "typecheck": "tsc --noEmit -p tsconfig.json",
@@ -49,10 +49,10 @@
     "icons": "bun run src/icons/build-icons.ts"
   },
   "dependencies": {
-    "@ultimat3/core": "23.0.0",
-    "@ultimat3/i18n": "23.0.0",
-    "@ultimat3/money": "23.0.0",
-    "@ultimat3/time": "23.0.0"
+    "@ultimat3/core": "25.0.0",
+    "@ultimat3/i18n": "25.0.0",
+    "@ultimat3/money": "25.0.0",
+    "@ultimat3/time": "25.0.0"
   },
   "peerDependencies": {
     "solid-js": "^1.9.0"

package/src/a11y.ts

@@ -20,27 +20,41 @@ export const FOCUSABLE_SELECTOR = [
 ].join(',');
 
 let idCounter = 0;
+let islandScope: string | undefined;
 
 /**
- * Unique id for label/description wiring, from a PROCESS-wide counter. Prefixed so a mismatch is
- * obvious in the DOM rather than silent.
+ * The part of an id that tells two copies of this module apart. Each island is its own bundle by
+ * default (`islands.sharedChunks` off — measured: every island chunk inlines this counter; with it
+ * on, one shared chunk holds it), so each island counts from zero and two of them both minted
+ * `field-1`. In a browser every copy draws its own scope once; a server render has one copy and no
+ * scope, so a document's ids carry no random part.
+ */
+function scope(): string {
+  if (typeof document === 'undefined') return '';
+  if (islandScope === undefined) {
+    const [draw = 0] = crypto.getRandomValues(new Uint32Array(1));
+    islandScope = draw.toString(36);
+  }
+  return `${islandScope}-`;
+}
+
+/**
+ * Unique id for label/description wiring. Prefixed so a mismatch is obvious in the DOM.
  *
- * Correct for the only render path that exists: a server render walks a tree once, so every id in
- * one document is distinct, which is all `for`/`aria-describedby` need. It is NOT stable across two
- * renders of the same tree — a second process, or a client re-render, starts its own count — so it
- * cannot survive hydration. That is latent rather than broken: this package has no client runtime
- * (see CLAUDE.md), so nothing re-renders a server tree yet. Making it survive needs a
- * RENDER-SCOPED counter, which means a seam in `@ultimat3/render` (or a `SolidRuntime` member);
- * resetting this one per request would only move the collision. Do not paper over it here.
+ * On the server it comes from a PROCESS-wide counter: every id in one document is distinct, which
+ * is all `for`/`aria-describedby` need, but two renders of one page mint different numbers — a
+ * render-scoped counter needs a seam in `@ultimat3/render`. An island never reuses a server id: it
+ * replaces its shell rather than hydrating it, and its own ids carry its scope (above).
  */
 export function useId(prefix = 'u'): string {
   idCounter += 1;
-  return `${prefix}-${idCounter.toString(36)}`;
+  return `${prefix}-${scope()}${idCounter.toString(36)}`;
 }
 
 /** Test-only: make id assertions deterministic. */
-export function resetIdCounter(): void {
+export function resetUseIdCounter(): void {
   idCounter = 0;
+  islandScope = undefined;
 }
 
 /**
@@ -76,7 +90,7 @@ export interface FocusTrap {
  * branch that pulls it back was unreachable by construction. Every branch still tests
  * `root.contains`, so the trap only acts while it is the active one.
  */
-export function createFocusTrap(root: HTMLElement): FocusTrap {
+export function focusTrap(root: HTMLElement): FocusTrap {
   let previous: HTMLElement | null = null;
 
   /**
@@ -167,7 +181,7 @@ export function nextRovingIndex(
 }
 
 /** Wire a roving group: one tabbable item, arrows move focus and selection. */
-export function createRovingTabindex(
+export function rovingTabindex(
   getItems: () => readonly HTMLElement[],
   options: RovingOptions = {},
 ): (event: KeyboardEvent) => void {

package/src/catalog/build-catalog.ts

@@ -5,8 +5,8 @@ import type { ComponentDoc } from './parse-component';
 import { parseComponents } from './parse-component';
 import { renderCatalog } from './render-catalog';
 
-const COMPONENTS_DIR = new URL('../components/', import.meta.url).pathname;
-export const CATALOG_PATH = new URL('../../CATALOG.md', import.meta.url).pathname;
+const COMPONENTS_DIR = Bun.fileURLToPath(new URL('../components/', import.meta.url));
+export const CATALOG_PATH = Bun.fileURLToPath(new URL('../../CATALOG.md', import.meta.url));
 
 /** Alphabetical by file, so the page's order is the order an agent scans for a name. */
 export async function collectComponents(): Promise<ComponentDoc[]> {

package/src/components/Accordion.tsx

@@ -11,6 +11,7 @@ import type { AccordionSection } from './accordion-view';
 import { accordionOpenIds } from './accordion-view';
 import type { HeadingLevel } from './heading-level';
 import { headingTag } from './heading-level';
+import { headingNode } from './heading-node';
 import { Icon } from './Icon';
 
 export interface AccordionItem extends AccordionSection {
@@ -39,7 +40,8 @@ export interface AccordionProps {
 export function Accordion(props: AccordionProps): JSX.Element {
   const base = useId('accordion');
   const open = accordionOpenIds(props.items, props.exclusive === true);
-  const Title = props.level === undefined ? 'span' : headingTag(props.level);
+  // Resolved once, so an off-scale level throws `X_UI_INVALID_VALUE` here as it always did.
+  const heading = props.level === undefined ? undefined : headingTag(props.level);
 
   return (
     <div class={cx(styles['accordion'], props.class)}>
@@ -53,7 +55,11 @@ export function Accordion(props: AccordionProps): JSX.Element {
         >
           <summary class={styles['summary']}>
             <Icon glyph={iconChevronDown} class={styles['marker']} size="sm" />
-            <Title class={styles['title']}>{item.title}</Title>
+            {heading === undefined ? (
+              <span class={styles['title']}>{item.title}</span>
+            ) : (
+              headingNode(heading, { class: styles['title'] }, () => item.title)
+            )}
           </summary>
           <div class={styles['panel']}>{item.panel}</div>
         </details>

package/src/components/AppShell.module.scss

@@ -4,6 +4,9 @@
 // writing mode is handled by the grid itself, so RTL needs no second rule.
 .shell {
   display: grid;
+  // `minmax(0, …)`, never the implicit `auto`: an auto track is at least its content's min-content
+  // width, so a header that did not shrink laid a 390px phone out 429px wide.
+  grid-template-columns: minmax(0, 1fr);
   grid-template-areas: 'header' 'sidebar' 'main' 'footer';
   grid-template-rows: auto auto 1fr auto;
   min-block-size: 100dvh;
@@ -51,13 +54,66 @@
   }
 }
 
+// The bar the banner sits in: the menu button (below `md`) and the app's header, side by side.
+.top {
+  display: flex;
+  min-inline-size: 0;
+  align-items: center;
+  gap: t.space(2);
+  grid-area: header;
+  padding-inline-start: t.space(2);
+  border-block-end: 1px solid t.role('line');
+  background: t.role('surface');
+
+  @include t.respond-to(md) {
+    padding-inline-start: 0;
+  }
+}
+
+.menuOnly {
+  display: none;
+}
+
 .header {
   @include t.row(t.space(4), center, space-between);
-  grid-area: header;
+  flex: 1;
+  min-inline-size: 0;
   padding-block: t.space(3);
   padding-inline: t.space(4);
-  border-block-end: 1px solid t.role('line');
-  background: t.role('surface');
+}
+
+// Hidden unless the engine can open the panel it names: a button that does nothing is worse than
+// the band an engine without popovers still shows. A touch target: this bar exists for a phone.
+.menuButton,
+.close {
+  @include t.focus-ring;
+  @include t.touch-target;
+  display: none;
+  align-items: center;
+  justify-content: center;
+  gap: t.space(2);
+  padding-inline: t.space(3);
+  border: 0;
+  border-radius: t.radius(md);
+  background: none;
+  color: t.role('fg-strong');
+  font: inherit;
+  cursor: pointer;
+
+  &:hover {
+    background: t.role('bg-soft');
+  }
+}
+
+.close {
+  margin-inline-start: auto;
+}
+
+// On a phone the menu button is its icon; the label stays in the accessibility tree as its name.
+.menuLabel {
+  @include t.respond-down(sm) {
+    @include t.visually-hidden;
+  }
 }
 
 .sticky {
@@ -66,13 +122,23 @@
   inset-block-start: 0;
 }
 
-// Below `md` the sidebar is a band above the content; from `md` it is the inline-start column.
+// From `md` the sidebar is the inline-start column; below it, the popover panel further down.
+// Every `[popover]` gets a UA style — fixed, centred, bordered, hidden while closed — so the
+// in-flow box undoes each, and is what an engine without popovers shows at every width.
 .sidebar {
   @include t.custom-scrollbar;
+  display: block;
+  position: static;
+  inset: auto;
+  inline-size: auto;
+  block-size: auto;
+  margin: 0;
   grid-area: sidebar;
   padding: t.space(4);
+  border: 0;
   border-block-end: 1px solid t.role('line');
   background: t.role('bg-soft');
+  color: t.role('fg');
   overflow: auto;
 
   // Deliberately not sticky: a sticky sidebar and a sticky header both anchored at 0 overlap,
@@ -108,3 +174,38 @@
   color: t.role('fg-muted');
   font-size: t.text(sm);
 }
+
+// --- Below `md`, where the engine has popovers: the sidebar is an edge panel ----------------------
+// The same look as `Drawer`'s inline-start side — raised surface, line edge, scrim — so the two
+// off-canvas surfaces in an app read as one.
+@include t.respond-down(md) {
+  @supports selector(:popover-open) {
+    .sidebar:not(:popover-open) {
+      display: none;
+    }
+
+    .sidebar:popover-open {
+      @include t.scrim-backdrop;
+      position: fixed;
+      inset-block: 0;
+      inset-inline-start: 0;
+      inset-inline-end: auto;
+      inline-size: min(var(--shell-sidebar, 16rem), calc(100vw - #{t.space(12)}));
+      block-size: 100dvh;
+      max-block-size: 100dvh;
+      border-block-end: 0;
+      border-inline-end: 1px solid t.role('line');
+      background: t.role('surface-raised');
+      box-shadow: t.shadow(xl);
+    }
+
+    .menuButton,
+    .close {
+      display: inline-flex;
+    }
+
+    .menuOnly {
+      display: flex;
+    }
+  }
+}

package/src/components/AppShell.tsx

@@ -1,28 +1,35 @@
 // The page frame every app screen sits in: skip link, banner, navigation, main, contentinfo.
-// Stateless on purpose — below `md` the sidebar becomes a band above the content instead of
-// growing an open/closed flag, because an off-canvas menu is already `Drawer` and axiom 1 allows
-// exactly one of those.
+// Stateless, and scriptless: below `md` the sidebar `<nav>` is a native `popover` panel at the
+// inline-start edge, opened by a `popovertarget` menu button — the browser holds the open state,
+// Esc and light dismiss, so the frame on every page costs no island. Not `Drawer`: that is a modal
+// `<dialog>` opened from an effect, so it needs a hydrated island, and a `<dialog>` cannot also be
+// the in-flow `navigation` landmark at `md` and up. An engine with no popovers keeps the old band.
 
 import type { JSX } from 'solid-js';
 import { LIVE_REGION_LEVELS, liveRegionAttrs, useId } from '../a11y';
 import { cx } from '../cx';
 import { UI_KEYS } from '../i18n-keys';
+import { iconMenu } from '../icons/glyphs/menu';
+import { iconX } from '../icons/glyphs/x';
 import { useUi } from '../theme/context';
 import styles from './AppShell.module.scss';
 import { shellIds } from './app-shell-view';
+import { Icon } from './Icon';
 
 export interface AppShellProps {
   /** The page. Rendered inside the one `<main>`, which is the skip link's target. */
   children: JSX.Element;
   header?: JSX.Element | undefined;
-  /** Rendered inside a `<nav>` landmark at the inline start. */
+  /** Rendered inside a `<nav>` landmark: the inline-start column at `md` and up, a panel below. */
   sidebar?: JSX.Element | undefined;
   footer?: JSX.Element | undefined;
   /** Accessible name for the sidebar landmark. Defaults to the translated `ui.navigation`. */
   sidebarLabel?: string | undefined;
   /** Skip-link text. Defaults to the translated `ui.skip`. */
   skipLabel?: string | undefined;
-  /** Sidebar track width at `md` and up. Any CSS length. */
+  /** The menu button's text below `md`. Defaults to the translated `ui.menu`. */
+  menuLabel?: string | undefined;
+  /** Sidebar track width at `md` and up, and the panel's width below. Any CSS length. */
   sidebarWidth?: string | undefined;
   /** Keeps the header pinned while the main region scrolls. */
   stickyHeader?: boolean | undefined;
@@ -41,13 +48,44 @@ export function AppShell(props: AppShellProps): JSX.Element {
       <a class={styles['skip']} href={ids.skipHref}>
         {props.skipLabel ?? ui.t(UI_KEYS.skip)}
       </a>
-      {props.header === undefined ? null : (
-        <header class={cx(styles['header'], props.stickyHeader !== false && styles['sticky'])}>
-          {props.header}
-        </header>
+      {props.header === undefined && props.sidebar === undefined ? null : (
+        // The menu button sits beside the banner, not inside it: the header holds exactly what
+        // the app handed it, and the bar is what sticks.
+        <div
+          class={cx(
+            styles['top'],
+            // A bar holding only the menu button is shown only where that button is.
+            props.header === undefined && styles['menuOnly'],
+            props.stickyHeader !== false && styles['sticky'],
+          )}
+        >
+          {props.sidebar === undefined ? null : (
+            <button type="button" class={styles['menuButton']} popovertarget={ids.navId}>
+              <Icon glyph={iconMenu} size="md" />
+              <span class={styles['menuLabel']}>{props.menuLabel ?? ui.t(UI_KEYS.menu)}</span>
+            </button>
+          )}
+          {props.header === undefined ? null : (
+            <header class={styles['header']}>{props.header}</header>
+          )}
+        </div>
       )}
       {props.sidebar === undefined ? null : (
-        <nav class={styles['sidebar']} aria-label={props.sidebarLabel ?? ui.t(UI_KEYS.navigation)}>
+        <nav
+          id={ids.navId}
+          class={styles['sidebar']}
+          popover="auto"
+          aria-label={props.sidebarLabel ?? ui.t(UI_KEYS.navigation)}
+        >
+          <button
+            type="button"
+            class={styles['close']}
+            popovertarget={ids.navId}
+            popovertargetaction="hide"
+            aria-label={ui.t(UI_KEYS.close)}
+          >
+            <Icon glyph={iconX} size="md" />
+          </button>
           {props.sidebar}
         </nav>
       )}