@poodle64/ui 2026.8.7

package/README.md

@@ -0,0 +1,624 @@
+# @poodle64/ui
+
+Household shared shadcn-svelte component primitives (bits-ui), extracted from
+the estate's most conformant consuming app's frontend — the best-looking,
+most battle-tested implementation of each primitive — plus `alert`/`popover`/
+`progress`/`tabs` from the first app that migrated onto this package (WP-51
+Lane WP) and needed them.
+
+`bits-ui` is a required peerDependency: components share compound-component
+context across the package, so a duplicated `bits-ui` instance is a real
+functional bug (mismatched types at best). `mode-watcher` and `svelte-sonner`
+are optional peers (`peerDependenciesMeta`), needed only if the consuming app
+uses `@poodle64/ui/sonner` (a single dark-mode store for `mode-watcher`, one
+toast queue for `svelte-sonner`'s `toast()` + `Toaster` pair — a duplicated
+instance there means a `Toaster` that never sees the app's own `toast()`
+calls). Declare whichever peers you use directly in your own `package.json`:
+pnpm auto-installs missing peers, but an explicit dependency is what lets
+Renovate track the version and `pnpm ls` show it.
+
+Every app previously vendored its own copy of these primitives and restyled them
+through its `@poodle64/design-tokens` alias layer. That let apps differ by palette,
+but a fix (an accessibility bug, a focus-trap issue) had to be applied once per app.
+This package is the same restyling mechanism: components consume shadcn's standard
+CSS variable names (`bg-primary`, `text-foreground`, `--radius`, …), and both the
+component code and the mapping those names resolve through now live once, here.
+Apps differ by palette and nothing else. Override `--ds-color-*` and the whole
+shadcn surface follows; a consuming app writes no alias layer of its own.
+
+## What is here
+
+```text
+src/lib/
+  utils.ts              cn() (clsx + tailwind-merge) and the shared TS helper types
+  styles.css            the component stylesheet: scale keys, .ds-edge, .ds-chip/.ds-dot,
+                          the dialogue-section divider rule
+  components/ui/         one directory per component: the shadcn-svelte primitives
+                          (bits-ui behaviour + shadcn markup/variants) and the composed
+                          page-chrome components built on top of them
+dist/                    generated by `pnpm build` (@sveltejs/package); never edit
+```
+
+**Primitives** (26 — battle-tested implementations pulled from whichever app had
+them first, not an invented "ideal" list): `alert`, `alert-dialog`, `avatar`,
+`badge`, `button`, `card`, `checkbox`, `command`, `data-table`, `dialog`,
+`dropdown-menu`, `input`, `input-group`, `label`, `password-input`, `popover`,
+`progress`, `select`, `separator`, `skeleton`, `sonner`, `switch`, `table`,
+`tabs`, `textarea`, `tooltip`.
+
+`avatar` is root, image and fallback only; the group and badge variants in the
+upstream registry had no consumer in any surveyed app. It is here because
+`AppShell`'s `identity` slot needs one, and a consumer filling a slot the shell
+itself defines should not have to keep a private copy of a primitive to do it.
+
+Not yet included: `sheet` — no app's `ui/` has vendored it yet. Add it here
+(`pnpm dlx shadcn-svelte@latest add <name>` inside `packages/ui`, or hand-port from
+a sibling app once one adopts it) the first time a converging app actually needs it;
+do not invent it speculatively.
+
+**Deliberately not here: `chart` and `form`.** Two apps keep local copies of each,
+and both stay local for reasons that are about coupling rather than effort.
+
+`form` in the upstream registry is a Formsnap wrapper over Superforms. Adding it
+would make a form library a peer of the whole design system and decide, for every
+app, how validation and submission work — which is an application-architecture
+choice, not a design one. An app that uses Superforms already gets its markup from
+`input`, `label`, `input-group` and `button` here; what it keeps locally is the
+binding layer, which is where it belongs.
+
+`chart` is a LayerChart wrapper, and it needs the `chart-1`…`chart-5` colour keys
+this stylesheet deliberately does not register — chart hue is the one part of the
+shadcn surface the estate genuinely disagrees on, and registering it here would
+claim a key no app can then override without a stylesheet-order coin toss (see
+the one-owner-per-key note below). It becomes a candidate the day two apps want
+the same chart palette; until then a shared chart component would be a shared
+disagreement.
+
+**Composed components** (20). Primitives are not what makes an app look like an
+app — the page chrome is. These are the cross-cutting surfaces every route
+composes from, so a household app gets its layout language from the package
+rather than rebuilding it:
+
+| Import                                          | What it is                                                                                                                                                                                                                                                                                                                                               |
+| ----------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `page-header`                                   | The only page-title pattern: optional `breadcrumbs` snippet, eyebrow, an optional title, one clamped subtitle, an `info` tooltip, an `actions` slot. Omit `title` for a header that is a breadcrumb bar.                                                                                                                                                 |
+| `panel`                                         | The generic titled card: optional icon, subtitle and trailing actions over a body that can opt out of padding.                                                                                                                                                                                                                                           |
+| `detail-panel`                                  | The entity-detail surface: header with icon/eyebrow/title/`StatusBadge`/close, scrollable body, footer of actions.                                                                                                                                                                                                                                       |
+| `context-column`                                | The persistent right-hand column: a standing `StatList` plus an optional detail that flows in on select.                                                                                                                                                                                                                                                 |
+| `app-dialog`                                    | The dialogue frame: titled header, scrollable body, footer action bar, five sizes (`xs`…`xl`), and an `onOpenChange` for the dismissals the caller did not drive.                                                                                                                                                                                        |
+| `dialog-section`                                | One section of a dialogue body; adjacent sections are divided automatically.                                                                                                                                                                                                                                                                             |
+| `stat-card`                                     | A single metric that earns its space (label, value, unit, sub, status dot, and `valueTone` to colour the figure itself).                                                                                                                                                                                                                                 |
+| `stat-list`                                     | A route's low-context integers as a label→value list. Zero-aware: `muted` keeps a healthy zero quiet.                                                                                                                                                                                                                                                    |
+| `arc-gauge`                                     | A radial capacity/percentage ring for a single 0–100 metric, in a footprint too compact for a `stat-card`.                                                                                                                                                                                                                                               |
+| `bar-row`                                       | A labelled horizontal bar with a trailing tabular value, for a ranked list (usage, rank, token burn).                                                                                                                                                                                                                                                    |
+| `scorecard`                                     | A compact 0/1/2 dot-row health strip for several independent checks read at a glance.                                                                                                                                                                                                                                                                    |
+| `sparkline`                                     | An inline multi-series area+line trend for a row or card with room for a trend but not a full chart.                                                                                                                                                                                                                                                     |
+| `status` / `status-badge`                       | The fixed five-state vocabulary (`success \| warning \| error \| info \| neutral`) and the one state chip, with `pulse` for a state still in motion and `class` for placement. `status-badge` alone also accepts `'primary'`, a brand-emphasis extension outside the shared vocabulary — `stat-card`, `stat-list` and `data-table-toolbar` never see it. |
+| `empty-state` / `error-state` / `loading-state` | The shared blank, error and loading surfaces. Never hand-roll one.                                                                                                                                                                                                                                                                                       |
+| `info-tip`                                      | One tooltip pattern: a small info trigger, or wrap an existing affordance as children.                                                                                                                                                                                                                                                                   |
+| `data-table-toolbar`                            | Search field plus filter-chip groups for a TanStack table. Owns no state; fires callbacks.                                                                                                                                                                                                                                                               |
+| `data-table-tanstack`                           | The TanStack-backed table: global search, column filters, master-detail row select, opt-in bulk selection, responsive column hiding, a first-class empty branch.                                                                                                                                                                                         |
+
+**The application shell** (`app-shell`, `command-palette`). Page chrome is not
+what makes an app feel like an app either — the shell is. Five household
+frontends were surveyed before this API was settled, and between them they had
+built five shells: a rail-plus-drawer, an eleven-file collapsible sidebar tree
+under its own top bar, and three header-only bars that each answered the mobile
+question differently. They agreed on almost nothing structurally while trying to
+be the same thing.
+
+There is now exactly one shell shape, no prop to choose a different one.
+Operator ruling, 31/07/2026: every household app renders the same composition,
+a permanent side rail on `md`+ (an overlay drawer below it) carrying primary
+navigation, brand and the collapse toggle, **plus** a real top navbar (search,
+leading/trailing slots, theme toggle, identity), always both together, with
+content that is always full-width. Apps do not choose variants, content modes,
+or spacing.
+
+Everything the apps otherwise differed on turned out to be a slot, not a variant.
+The package therefore imports no app store, no app route and no app brand:
+
+```svelte
+<script lang="ts">
+	import { page } from '$app/state';
+	import { goto } from '$app/navigation';
+	import AppShell, { type NavGroup } from '@poodle64/ui/app-shell';
+	import CommandPalette from '@poodle64/ui/command-palette';
+	import { nav } from '$lib/config/navigation'; // typed as NavGroup[]
+
+	let paletteOpen = $state(false);
+</script>
+
+<AppShell {nav} brandTitle="Console" currentPath={page.url.pathname}
+          onSearch={() => (paletteOpen = true)}>
+	{@render children()}
+</AppShell>
+<CommandPalette bind:open={paletteOpen} {nav} onNavigate={goto} />
+```
+
+That is the whole minimum. Everything below is optional.
+
+| Prop                                              | Purpose                                                                                                                 |
+| ------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
+| `nav`                                             | Bare `NavItem`s, `NavGroup`s, or a mix. Consecutive bare items collapse into one run; an emptied group renders nothing. |
+| `currentPath`                                     | Active state, and closing the mobile nav on navigation.                                                                 |
+| `collapsible`, `collapsed`                        | An icon-only rail collapse toggle whose state binds out so an app can persist it.                                       |
+| `brand` / `brandTitle` + `brandMark` / `homeHref` | Full control of the lockup, or the wordmark-plus-mark shorthand.                                                        |
+| `identity`                                        | The signed-in surface. Rendered once, at the end of the top bar.                                                        |
+| `context`, `actions`                              | Leading and trailing top-bar slots: a store/tenant switcher, app-level action buttons.                                  |
+| `banner`                                          | Full-width region under the bar: reconnect notices, trial warnings.                                                     |
+| `sidebar`                                         | A secondary, route-scoped column between the nav and the page body.                                                     |
+| `onSearch`, `searchLabel`, `searchShortcut`       | Provide `onSearch` to render the search affordance at all.                                                              |
+| `themeToggle`, `onToggleTheme`                    | Defaults to `mode-watcher`. Set `themeToggle={false}` when the app puts theming inside its own user menu.               |
+| `measure`                                         | How wide the page body may get, from a named scale. Defaults to `full` (no cap).                                        |
+| `texture`                                         | The house atmosphere on the content region. Defaults to `none`.                                                         |
+| `padded`, `mainClass`                             | Padding, and extra classes on the scrolling content container.                                                          |
+
+### Nested navigation
+
+A section with its own navigation puts it on the item, as `children`, and the
+rail discloses it in place:
+
+```ts
+{
+	label: 'Education',
+	href: '/education',
+	icon: BookOpen,
+	children: [
+		{ label: 'Open architecture', href: '/education/open-architecture' },
+		{ label: 'Autonomy', href: '/education/autonomy' }
+	]
+}
+```
+
+That is the whole API. An item with no `children` renders and behaves exactly as
+it did before the field existed.
+
+It exists because the alternative was two left-hand columns: an app whose
+sections have inner navigation had nowhere to put it in the rail, so it put
+modules in `nav` and the current section's pages in `sidebar`. The other way out
+(modules along the top bar, rail for the current module) was rejected on mobile:
+it leaves two navigation surfaces that both need collapsing and both want the
+same hamburger. One nested tree collapses to one drawer.
+
+The behaviour, and why:
+
+- **The parent stays a destination.** Its label navigates; a separate chevron
+  expands. Folding both into the link cannot be made honest, since
+  `aria-expanded` on something that navigates away announces a state the user
+  never observes; and making the label expand-only would silently change what
+  `href` means the day an app adds children to an item that already had one.
+- **A group holding the current page is open**, on first paint, with nothing
+  clicked. A rail that will not show you where you are is the defect this
+  feature exists to remove.
+- **A deliberate toggle wins, and keeps winning** for the life of the shell,
+  which in a SvelteKit layout is the session. It overrides the path default rather than
+  replacing it, so an untouched group still opens as you walk into it while a
+  group you made a decision about keeps your decision. Nothing is written to
+  storage: a shared package writing to a fixed key would collide with the app's
+  own, and with itself on a page rendering two navs.
+- **One level, enforced by the type.** `children` holds `NavChildItem`, which is
+  `NavItem` minus `children`, so a second nesting is a compile error where the
+  nav is authored. The rail is 15.5rem and every level costs an indent; by depth
+  three the label has less room than the chevron.
+- **A collapsed rail renders no tree.** 3.5rem of icons cannot hold one, and a
+  hover flyout would be a second interaction surface with its own positioning,
+  touch and focus story. The parent stays an icon-only link to its own page; the
+  way back is the Collapse control the user just used.
+- **The drawer renders the same tree.** It is the same element as the rail, and
+  it is never collapsed.
+
+What this does not absorb, and deliberately: a `children` list is flat and one
+deep, so a section whose own navigation is itself grouped under sub-headings, or
+whose rows disclose a third level, does not lift into the rail whole. The rail is
+not the place to fix that. At 15.5rem a third level leaves roughly 128px for the
+label, which is about fifteen characters. A section that deep keeps its deepest
+level on its own page, where there is width for it, and the `sidebar` snippet
+stays the right home for a column that is not `NavItem`-shaped at all: a document
+tree, a table of contents, a filter panel.
+
+`NavItem` / `NavGroup` are exported so an app types its own config against them.
+They carry **no notion of who may see an item**: two surveyed apps gate
+navigation on admin or per-module permission, and both do it with their own auth
+store. Apps filter before they pass (`nav.filter((i) => !i.adminOnly || user.isAdmin)`),
+and that is what keeps this package free of the auth coupling that made the best
+shell in the estate unliftable in the first place.
+
+`currentPath` is a prop rather than a `$app/state` import for the same reason:
+this package is built with `svelte-package` and has no SvelteKit runtime, so
+importing it would make SvelteKit a hard peer and make the shell untestable
+outside a running app.
+
+`CommandPalette` ships beside the shell because it carried the identical
+coupling to a hardcoded navigation module; leaving it behind would have stranded
+the shell's search affordance. It binds ⌘K / Ctrl-K itself (`shortcut={false}` to
+opt out) and takes a `children` snippet for app-specific command groups beneath
+the navigation group.
+
+The shell paints its chrome from `--ds-shell-chrome`, registered as the `shell`
+colour key. It is deliberately **not** `sidebar`: those keys stay the app's to
+define, and one-owner-per-key is what keeps an override from depending on
+stylesheet order. An app that already has a chrome hue points it there in one
+line, `:root { --ds-shell-chrome: var(--sidebar); }`, and `--ds-shell-rail-width`
+retunes the rail.
+
+Chrome **ink** follows the same pattern, through `--ds-shell-chrome-foreground`
+and `--ds-shell-chrome-muted-foreground`. Both default to the page's own
+foreground tokens, so nothing moves until an app asks; set them to invert the
+whole chrome — rail, bar, every chrome control and every nav row — against the
+palette:
+
+```css
+:root {
+	--ds-shell-chrome: var(--ds-color-primary);
+	--ds-shell-chrome-foreground: var(--ds-color-primary-foreground);
+	--ds-shell-chrome-muted-foreground: color-mix(
+		in oklch,
+		var(--ds-color-primary-foreground) 70%,
+		transparent
+	);
+}
+```
+
+`AppNav` used outside the chrome (the `sidebar` slot's own column) keeps the
+page's ink, so inverting the rail does not drag a secondary nav with it.
+
+### The content measure
+
+How wide the page body may get, chosen once in the layout from a scale of four:
+
+```svelte
+<AppShell {nav} currentPath={page.url.pathname} measure="page">
+	{@render children()}
+</AppShell>
+```
+
+| Value   | Width    | Reach for it when the page is                                        |
+| ------- | -------- | -------------------------------------------------------------------- |
+| `prose` | `72ch`   | long-form running text: documentation, an article, a policy, a guide |
+| `page`  | `80rem`  | an everyday page: a form, a detail view, settings, a wizard          |
+| `wide`  | `120rem` | an index or a dashboard: card grids, tables, charts, board columns   |
+| `full`  | no cap   | a canvas that should use the whole panel: a map, a diagram, a board  |
+
+`full` is the default, so a shell that does not mention `measure` renders exactly
+as it did before the prop existed — verified, not assumed: the content region's
+markup and geometry were diffed against the pre-change build across three
+surfaces at three viewports and are identical on every field (`harness/drive.md`).
+Adoption is deliberate, one app at a time.
+
+It exists because "content is always full-width" did not remove the width
+decision, it pushed it into every page. Surveyed at 2560px, one consumer had six
+distinct caps across nine routes — each a hand-written `mx-auto max-w-*` at the
+top of a `+page.svelte`, none wrong on its own, no two agreeing — using between
+15% and 79% of the width available. Across the estate that is 42 hand-rolled caps
+in 34 page files, spanning eight different `max-w-*` values. A scale with four
+names cannot drift like that.
+
+**Why `prose` is a tier at all.** Because a shared measure that let running text
+span a large display would be worse than what it replaces, and worse everywhere
+at once. Measured in Chromium at 2560px: the same paragraph runs to **311
+characters per line** uncapped, against an accepted band of 45–90 for continuous
+text. `prose` puts it at 80. It is stated in `ch` rather than `rem` deliberately —
+a reading measure is a count of characters, not a length, so it has to track
+whatever face and size the app actually set.
+
+Every tier is a CSS custom property, so an app retunes one without waiting on a
+release of this package:
+
+```css
+:root {
+	--ds-shell-measure-prose: 66ch;
+	--ds-shell-measure-page: 72rem;
+	--ds-shell-measure-wide: 100rem;
+}
+```
+
+Two things worth knowing before you set it:
+
+- **The cap is a ceiling, never a floor.** `page` caps at 80rem; a 1440px laptop
+  has less than that available, so nothing changes there. A measure never narrows
+  a window that was already narrower than the tier.
+- **`prose` moves when the font does.** A webfont arriving after first paint
+  reflows the column, because `ch` is measured in the face that actually
+  rendered. That is the tier doing its job rather than a bug; `page` and `wide`
+  are lengths and never move.
+- **The cap is the border box, so `padded` spends its padding inside it.**
+  `measure="page"` with the default padding is 80rem of box holding 78rem of
+  content, which is the same arithmetic as the `mx-auto max-w-4xl px-6` idiom it
+  replaces. An app running `padded={false}` and its own page padding gets the cap
+  flush, which is usually what it wanted.
+
+Set it in the layout, not the page. A page reaching for `measure` is the habit
+this replaces; a route group that genuinely differs (a docs section inside an
+app of dashboards) gets its own layout, which is where a shared decision belongs.
+
+### The content texture
+
+The house atmosphere — a faint dot-grid floor with a soft accent vignette in the
+top-right — painted once, by the shell, on the region that scrolls:
+
+```svelte
+<AppShell {nav} currentPath={page.url.pathname} texture="grid">
+	{@render children()}
+</AppShell>
+```
+
+| Value  | What it paints                                          | Reach for it when                                                        |
+| ------ | ------------------------------------------------------- | ------------------------------------------------------------------------ |
+| `grid` | a dot-grid floor plus one accent vignette in the corner | the app wants the house "instrument-grade" surface rather than flat page |
+| `none` | nothing at all                                          | the default                                                              |
+
+`none` is the default, so a shell that does not mention `texture` renders exactly
+as it did before the prop existed. Verified, not assumed, and reproducibly so:
+
+```sh
+node harness/additivity.mjs ui-v2026.8.3
+# 15 surface/viewport pairs, 105 compared fields (including the screenshot hash)
+# IDENTICAL on every field and every pixel — the change is additive.
+```
+
+`harness/additivity.mjs` builds the package at any base ref in a throwaway git
+worktree, renders the five surfaces an existing consumer already has at 2560px,
+1440px and 360px, and diffs the markup, both attribute sets, the computed box and
+background properties, the geometry and the rendered pixels. Adoption is
+deliberate, one app at a time.
+
+**Why it lives on the shell rather than being a class an app applies.** Because
+that is the entire defect it fixes. Two apps had built this same picture
+separately, under two names, in two `app.css` files, and one of them shipped it
+as a helper class routes opt into, which reached four routes out of about
+fifteen. Whether a given page wore the house atmosphere therefore came down to
+which pages someone had happened to touch, and no amount of care at the call site
+fixes that: a texture an app has to _remember_ to apply is not a texture, it is a
+coin toss with a stylesheet. On the shell there is one place to say it and no
+per-route decision left to get wrong.
+
+It is one texture rather than a menu. The two apps wanted the same picture and
+differed only on values: how dark the dots are, how the vignette is tinted, how
+far apart the dots sit. Those are custom properties, retuned in one
+declaration without waiting on a release of this package:
+
+```css
+:root {
+	--ds-shell-texture-grid-ink: oklch(0.68 0.02 250 / 0.5);
+	--ds-shell-texture-vignette-ink: color-mix(in oklch, var(--primary) 8%, transparent);
+	--ds-shell-texture-grid-pitch: 24px;
+	--ds-shell-texture-vignette-height: 40rem;
+	--ds-shell-texture-vignette-at: 15% -10%;
+}
+```
+
+The defaults derive from the app's own `--foreground` and `--primary`, so the
+grid inverts between light and dark with no per-mode override and the vignette
+carries the app's brand rather than a colour this package picked. A plain wash
+instead of a grid is the same declaration with `--ds-shell-texture-grid-ink: transparent`.
+
+Three things worth knowing before you set it:
+
+- **It is a background, not a layer.** Both apps that built this first reached for
+  an absolutely positioned `::before` inside the scroller, which is subtly wrong
+  three ways: at `z-index: auto` a positioned box paints _above_ non-positioned
+  content, so the atmosphere tints the page instead of sitting under it (invisible
+  only because it is faint); `z-index: -1` trades that for sinking behind an
+  ancestor's background; and it has to be excused from hit-testing by hand. A
+  background cannot be hit-tested, always paints beneath every descendant, adds no
+  box to the flex column and opens no stacking context. Proved rather than
+  claimed: an opaque card photographs byte-identically with the texture on and
+  off, while the floor beside it does not.
+- **It does not print.** A 30px dot grid prints as banding and a vignette as a
+  corner smudge, so on paper the texture is suppressed and the content region goes
+  white. That lives here rather than in each app's print rules; it is the same
+  copy both apps had already written for themselves. `html`/`body` stay the app's
+  to decide.
+- **It travels with the content.** A scroll container's background defaults to
+  being pinned to its own box, which would leave the dots hanging motionless while
+  the page slid over them; `background-attachment: local` makes it the floor the
+  page sits on. Driven by photographing bare floor either side of a half-pitch
+  scroll, with the frozen behaviour forced on as a control.
+- **The corner is a knob because a gradient position is physical.** There is no
+  logical form of `at 85%`, so an RTL app wanting the glow at the reading-start
+  corner sets `--ds-shell-texture-vignette-at`. Driven at `dir=rtl`, at a 24px
+  root size, and under `forced-colors: active`; none of those move the texture on
+  their own.
+
+Set it in the layout, once. That is the whole point of the prop.
+
+### The active nav row: primary is a fill, never an ink
+
+The active row is marked with a 12% `--ds-color-primary` tint, a primary edge
+bar on the rail, a weight step to 500, and `aria-current="page"`.
+Its **label** is painted in the chrome's own foreground, not in the brand colour.
+
+That is deliberate. `--ds-color-primary` is the one token every app overrides,
+and the only constraint stated where an app picks it is that it clear AA against
+its own `-foreground` pair: the fill case. Painting it as ink on the chrome
+would impose a second, stricter requirement that nothing states and that
+constrains a brand hue far more tightly. Measured in Chromium, a warm amber that
+is 7.69:1 as a fill was **1.90:1** as an active nav label, and a saturated blue
+that is 5:1 as a fill was **2.87:1**. Both palettes were entirely sanctioned. So
+the shell stops asking a colour it does not control to be legible text, and no
+app is ever told to repaint its brand to make the shared shell readable.
+
+An app whose primary genuinely is legible as ink on its chrome can put it back,
+and owns the contrast in doing so:
+
+```css
+:root {
+	--ds-nav-ink-active: var(--ds-color-primary);
+}
+```
+
+Check that at ≥4.5:1 against `--ds-color-surface-1` (the chrome), not against
+`--ds-color-background`; they are different surfaces, and the chrome is the
+darker of the two. `harness/drive.mjs` gates the default path across three
+palettes in both themes on every run.
+
+### Measuring the content region
+
+About overflow, not width — for how wide the body is allowed to get, see
+[The content measure](#the-content-measure) above.
+
+`<main>` is the scrolling content region and carries
+`data-slot="app-shell-content"`. A consuming app's "no horizontal overflow" check
+must measure **that element**, not the document:
+
+```ts
+const region = page.locator('[data-slot="app-shell-content"]');
+expect(await region.evaluate((el) => el.scrollWidth - el.clientWidth)).toBeLessThanOrEqual(0);
+```
+
+`overflow-y: auto` makes `overflow-x` compute to `auto` too, so a wide child's
+excess ends up in this box and never reaches
+`document.documentElement.scrollWidth` — the number nearly every app's overflow
+test reads, and one that cannot move. A page can scroll sideways on a phone with
+that suite green throughout.
+
+The shell constrains its own boxes, but a child wider than the region has to
+carry its own scroller: `@poodle64/ui/table` does (`data-slot="table-container"`,
+and `containerClass` if you need to cap its height for a sticky header), and a
+`<pre>` or an unbreakable string needs one from the page.
+
+The table is the TanStack-shaped pair the household actually runs, not a
+`rows`/`columns` config API. The page owns the `Table` instance (built with
+`createSvelteTable` from `@poodle64/ui/data-table`) and passes it in; the
+component owns how it looks and how a row is picked. For a small static table
+that does not earn a table instance, `@poodle64/ui/table` also exports the
+`TH_CLASS` / `TD_CLASS` / `TH_HIDDEN_UNTIL_XL` constants for the raw-`<table>`
+idiom.
+
+A column's `meta.class` reaches both its `<th>` and its `<td>`; `meta.headClass`
+/ `meta.cellClass` reach one cell only, additive on top of `class` (the
+cell-specific slot wins on a conflicting Tailwind utility). Reach for the split
+whenever a class must differ between the two — a truncating column needs
+`max-w-0` on the `<td>` to ellipsis instead of pushing every other column out,
+but the same class on the `<th>` collapses the heading over its neighbour:
+
+```ts
+{ accessorKey: 'filename', header: 'Document', meta: { class: 'w-full', cellClass: 'max-w-0' } }
+```
+
+## Consuming the package
+
+Published to public npm under the `@poodle64` scope, same as `@poodle64/design-tokens`
+— no registry config, no `.npmrc`, and no auth token needed to install.
+
+```bash
+pnpm add @poodle64/ui @poodle64/design-tokens
+```
+
+```svelte
+<script lang="ts">
+	import { Button } from '@poodle64/ui/button';
+	import * as Dialog from '@poodle64/ui/dialog';
+	import PageHeader from '@poodle64/ui/page-header';
+	import StatusBadge from '@poodle64/ui/status-badge';
+	import type { Status } from '@poodle64/ui/status';
+</script>
+```
+
+Composed components export both a default and a named binding, so either import
+style works. `stat-list` also exports its `StatItem` type, and
+`data-table-toolbar` its `ChipGroup` / `ChipSpec` types.
+
+Each component is its own subpath export (`@poodle64/ui/<name>`), matching
+shadcn-svelte's own convention; a flat barrel would collide on the generic names
+(`Root`, `Content`, `Trigger`) that most primitives share.
+
+**`CardTitle` takes an optional `level`.** It renders a `<div>` by default, as
+upstream shadcn does, because a card title is not always a heading. Where it IS
+the heading for that card's content — the common case on a dashboard — pass the
+level and it becomes a real `<h1>`–`<h6>`:
+
+```svelte
+<Card.Title level={2}>Estate summary</Card.Title>
+```
+
+Nothing else changes: the class list is identical either way, so `level` moves
+the document outline and not a pixel. Worth knowing before a migration, because
+the default is silent — an app replacing its own `<h3>` card titles with this
+component loses every heading below its page `<h1>` with no error, no lint hit
+and no visual difference.
+
+**Two lines in the app's `app.css`**, after the token imports:
+
+```css
+@import '@poodle64/design-tokens/tokens.tw.css';
+@import '@poodle64/design-tokens/tokens.css';
+@import '@poodle64/ui/styles.css'; /* required: theme registration + component styles */
+@source '../node_modules/@poodle64/ui/dist'; /* Tailwind content scan */
+```
+
+`@poodle64/ui/styles.css` is **required, not optional**. It carries two things.
+
+First, the shadcn semantic surface: `--card`, `--popover`, `--muted`, `--accent`,
+`--secondary`, `--input` and their `-foreground` pairs, each mapped to a `--ds-*`
+token and registered with Tailwind so `bg-card`, `bg-muted`, `border-input` and
+friends actually generate CSS. Declaring those names as plain custom properties
+is not enough: the variable exists, Tailwind still does not know it is a colour,
+and the utility compiles to no rule at all. That is a silent failure with no
+build error, no lint hit and no failing test, which is exactly how it went
+unnoticed through a full app migration (#3).
+
+Second, what the variable layer does not cover: the `text-display` / `text-body` /
+`text-stat` / `tracking-eyebrow` scale keys, the `.ds-edge` card treatment, the
+`.ds-dialog-section` divider rule, the `.ds-chip` / `.ds-dot` / `.ds-ink` status
+classes, and the two things that make this package's overlays animate at all —
+`@custom-variant data-open` / `data-closed` (bits-ui emits `data-state="open"`,
+so a bare `data-open:` utility matches nothing without them) and an import of
+`tw-animate-css`, which defines `animate-in`, `fade-in-0`, `zoom-in-95` and
+`slide-in-from-*`. Both used to be the app's job, and an app that never did the
+job got dialogues, dropdowns, popovers and selects that opened with no
+transition, silently. A consuming app now declares neither; one that already
+declares them loses nothing, since the definitions are identical.
+
+It holds no palette. Every value resolves through a `--ds-*` token, so choosing a
+palette stays a matter of overriding `--ds-color-*` in your own `app.css`, and
+`.dark` flows through untouched. Any single name can still be overridden by
+re-declaring it after the import, which is now a deliberate deviation rather than
+setup every app has to repeat.
+
+Sidebar and chart colours are not registered here: this package ships no sidebar
+or chart component, and those are the one part of the surface apps genuinely
+differ on. An app using them registers them itself.
+
+`@source` is needed because the package's Tailwind classes live in
+`node_modules/@poodle64/ui/dist`, outside the app's own `src/`, so the default
+source scan misses them. Without it the components render unstyled (no build
+error, no lint hit; the classes just never reach the compiled CSS).
+
+## Verifying a change
+
+```bash
+pnpm test              # build + vitest: jsdom interaction, and compiled-CSS gates
+pnpm run check         # svelte-check
+pnpm run test:browser  # build the harness and drive it in a real browser
+
+# Before releasing a change that claims to be additive (minutes, not seconds):
+node harness/additivity.mjs ui-v2026.8.3
+```
+
+`pnpm test` includes the gates that compile the built package through the real
+Tailwind chain, exactly as a consuming app wires it — a class that generates no
+rule, a colour that resolves to nothing, a registered theme key nothing reads, a
+variant whose selector cannot match the DOM, and a sizing utility that has
+silently changed meaning all fail there rather than shipping.
+
+`pnpm run test:browser` is the leg nothing else can stand in for: jsdom applies
+no stylesheet and returns unresolved `var(…)` literals, so it passes just as
+happily on a dead animation, an unregistered colour and a layout that does not
+exist. `harness/drive.md` records what is asserted, what each defect looked like
+before it was caught, and the measurement traps worth inheriting.
+
+`harness/additivity.mjs` is the leg that runs across two builds. Every additive
+prop this package has added promised the same thing — that a consumer who never
+names it renders identically — and that promise used to be checked by hand and
+written up as prose nobody could re-derive. It now builds the base ref in a
+throwaway worktree and diffs the markup, the computed boxes, the geometry and the
+pixels of the surfaces a consumer gets without opting into anything, exiting
+non-zero and naming the field on any difference.
+
+## Releasing
+
+1. Change a component; bump `version` in `package.json` (CalVer).
+2. `pnpm build`, which runs `svelte-package` then `publint` (package.json/exports sanity).
+3. Commit, tag `ui-v<version>`, push the tag; CI publishes to public npm.

package/dist/components/ui/alert/alert-description.svelte

@@ -0,0 +1,23 @@
+<script lang="ts">
+	import type { HTMLAttributes } from 'svelte/elements';
+	import { cn, type WithElementRef } from '../../../utils';
+	import type { Snippet } from 'svelte';
+
+	let {
+		ref = $bindable(null),
+		class: className,
+		children,
+		...restProps
+	}: WithElementRef<HTMLAttributes<HTMLDivElement>> & {
+		children?: Snippet;
+	} = $props();
+</script>
+
+<div
+	bind:this={ref}
+	data-slot="alert-description"
+	class={cn('text-muted-foreground col-start-2 grid justify-items-start gap-1 text-sm', className)}
+	{...restProps}
+>
+	{@render children?.()}
+</div>

package/dist/components/ui/alert/alert-description.svelte.d.ts

@@ -0,0 +1,9 @@
+import type { HTMLAttributes } from 'svelte/elements';
+import { type WithElementRef } from '../../../utils';
+import type { Snippet } from 'svelte';
+type $$ComponentProps = WithElementRef<HTMLAttributes<HTMLDivElement>> & {
+    children?: Snippet;
+};
+declare const AlertDescription: import("svelte").Component<$$ComponentProps, {}, "ref">;
+type AlertDescription = ReturnType<typeof AlertDescription>;
+export default AlertDescription;