@poodle64/ui 2026.8.15 → 2026.9.0

package/README.md

@@ -31,6 +31,8 @@ shadcn surface follows; a consuming app writes no alias layer of its own.
 ```text
 src/lib/
   utils.ts              cn() (clsx + tailwind-merge) and the shared TS helper types
+  format.ts             the Australian value formatters: money, dates, percentages,
+                          numbers — en-AU, AUD, Australia/Brisbane
   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
@@ -81,7 +83,7 @@ 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.                                                                                                                                                    |
+| `page-header`                                   | The only page-title pattern: optional `breadcrumbs` and `icon` snippets, eyebrow, an optional title, one clamped subtitle, an `info` tooltip, a `meta` row and 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.                                                                                                                                                                                                                                                    |
@@ -147,7 +149,7 @@ That is the whole minimum. Everything below is optional.
 | ------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
 | `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.                                       |
+| `collapsible`, `collapsed`                        | An icon-only rail collapse toggle whose state binds out so an app can persist it. `collapsible` defaults to `true`.     |
 | `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.                                  |
@@ -155,7 +157,7 @@ That is the whole minimum. Everything below is optional.
 | `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`.                                                         |
+| `texture`                                         | The house atmosphere on the content region. Defaults to `grid`; `none` is the opt-out.                                  |
 | `padded`, `mainClass`                             | Padding, and extra classes on the scrolling content container.                                                          |
 
 ### Nested navigation
@@ -343,36 +345,66 @@ 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.
 
+#### A block inside the page: `.ds-measure`
+
+A route legitimately set to `wide` — a dashboard, a table, a card grid — often
+also carries a paragraph of explanatory prose, and that prose inherits the wide
+measure. Cap the block, not the route:
+
+```svelte
+<p class="ds-measure" data-measure="prose">Explanatory running text…</p>
+```
+
+Same attribute and same custom properties as the shell's own measure, so the
+block retunes when the scale does. That is the point of it: the alternative an
+app reaches for is a local `max-w-prose` or `max-w-[72ch]`, a number typed once
+that never hears about a retune — four apps had written ten of them between
+them and not one matched this package's own `72ch`.
+
+`.ds-measure` caps and nothing else. `.ds-shell-measure`, which the shell puts
+on its own content box, is that plus `margin-inline: auto` — right for a content
+box, wrong for a block within a page, where it indented a set of left-anchored
+paragraphs ~207px away from their own label. Both halves are gated in
+`harness/drive.mjs` at 2560px on a `wide` route: the cap binds, the block stays
+on the page's own left edge, and it follows a retune of
+`--ds-shell-measure-prose`.
+
 ### 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">
+<AppShell {nav} currentPath={page.url.pathname}>
 	{@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                                                              |
+| `grid` | a dot-grid floor plus one accent vignette in the corner | the default — the house "instrument-grade" surface                       |
+| `none` | nothing at all                                          | an app arguing a deliberate exception                                    |
 
-`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:
+`grid` is the default since `2026.8.8`, so a shell that does not mention
+`texture` wears the house atmosphere. It shipped `none`-by-default in `2026.8.4`
+and the estate's answer to opt-in was measured a fortnight later: five of nine
+stamped apps wore it, three of them through a hand-rolled `*-dotgrid` class in
+their own `app.css` under three names. An opt-in house style measures who
+remembered, not what the house looks like.
+
+`texture="none"` is the complete opt-out and renders the region exactly as it
+was before the feature existed — gated, not assumed:
 
 ```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.
+# IDENTICAL on every field and every pixel against an explicit texture="none".
 ```
 
 `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.
+background properties, the geometry and the rendered pixels.
 
 **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
@@ -434,6 +466,49 @@ Three things worth knowing before you set it:
 
 Set it in the layout, once. That is the whole point of the prop.
 
+### The page header: `icon`, `meta`, and what `eyebrow` is for
+
+```svelte
+<PageHeader title="Rivers Family Trust" subtitle="Deed of variation">
+	{#snippet icon()}<FileText />{/snippet}
+	{#snippet meta()}
+		<span>Opened 12/03/2026</span>
+		<StatusBadge status="success" label="Active" />
+	{/snippet}
+	{#snippet actions()}<Button>Edit</Button>{/snippet}
+</PageHeader>
+```
+
+`icon` takes the **glyph alone**; the tinted square around it — its size, its
+radius, its alignment against the title — belongs to this component. That split
+is the whole reason the slot exists rather than each app placing its own icon:
+two apps had built the square and picked two sizes for it. `meta` is a wrapped
+row of facts under the title, in muted small text.
+
+Both are additive. A header that names neither renders exactly as it did
+before, asserted rather than assumed.
+
+They were promoted on **duplication, not on request**: three apps had
+hand-rolled the meta row and two the icon square, and one of them had
+reimplemented this entire component locally to get them, across 38 of its 49
+page headers. One app wanting something does not earn a shared slot; three
+apps having already built it does.
+
+#### `eyebrow` is an exception, not a slot to fill
+
+`eyebrow` renders a small uppercase kicker above the title, and a kicker above a
+heading is one of the more reliable visual tells of generated UI. In an app with
+a persistent nav rail it usually restates the section the rail already
+highlights, and it costs vertical space above every title in the app.
+
+It is kept because it is genuinely load-bearing in a few places, not because it
+is a good default — one audited app passed it on **all 17** of its page headers,
+including a home surface whose kicker read "AIR 6015 · CASPO Workbench" directly
+above a title reading "Workbench". Before reaching for it, check whether the
+fact belongs in `subtitle` (a short line), `info` (an explanation), `meta` (a
+fact about the page) or `breadcrumbs` (where you are). If one of those fits, use
+it.
+
 ### 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
@@ -464,6 +539,105 @@ Check that at ≥4.5:1 against `--ds-color-surface-1` (the chrome), not against
 darker of the two. `harness/drive.mjs` gates the default path across three
 palettes in both themes on every run.
 
+### `.ds-prose`: HTML the app did not author
+
+Rendered markdown, an extracted document body, a rich-text field — content whose
+tags the app did not write and cannot style at the call site:
+
+```svelte
+<div class="ds-prose ds-measure" data-measure="prose">
+	{@html sanitised}
+</div>
+```
+
+Headings take the display face at sizes relative to the body copy around them
+(an `<h1>` inside a document is not the page's `<h1>`), lists keep the markers
+the preflight reset strips, links take the accent, code takes the mono face, and
+a table wider than the measure **scrolls in its own box rather than taking the
+page sideways** — gated at 360px, and driven red by removing its `overflow-x`,
+which pushes 901px into the content region.
+
+The face carries no measure. A reading width and a reading face are two
+decisions, so compose it with [`.ds-measure`](#a-block-inside-the-page-ds-measure)
+as above.
+
+**The package styles this content; it does not render it.** Sanitising untrusted
+HTML is a security boundary, and a package cannot see the inputs the boundary is
+protecting — the app owns the markdown-to-HTML seam and hands the result in.
+
+It is here because three consumers had each built one, by three different
+mechanisms — a hand-written token-based block, the Tailwind typography plugin,
+and a second hand-written block one of them had already duplicated inside
+itself. Typography degrades worse than most things when it is re-derived per
+app.
+
+### Depth: the ladder and one hairline, not an elevation scale
+
+A raised surface reads as raised from **the surface ladder plus a 1px inner
+highlight**, applied by `.ds-edge` — which `DetailPanel`, `AppDialog`, `Panel`,
+`StatCard`, `StatList`, `EmptyState`, `ErrorState` and `DataTableTanstack`
+already carry, so most apps never write it. There is one knob:
+
+```css
+:root {
+	/* The drop shadow under .ds-edge. Neutral translucent black in both modes —
+	   a shadow is an absence of light, not a palette colour. */
+	--ds-shadow-sm: 0 1px 2px oklch(0 0 0 / 0.12);
+}
+```
+
+**There is deliberately no `sm`/`md`/`lg` elevation scale**, and that is a
+decision rather than a gap. A hairline border under a wide soft shadow is a
+recognised generated-UI tell, and a named ladder of shadows invites exactly it —
+so depth is declared once per surface, by the rung it sits on, and the edge does
+the rest.
+
+Measured across nine consumers before deciding: **two** declared their own
+shadows, not the "every app" the case for a scale assumed. One of the two
+already points `--ds-shadow-sm` at its own value, which is the supported path
+working as intended. The other had rebuilt `.ds-edge`'s exact formula under a
+different local name, which is a discoverability problem this section exists to
+fix, not an argument for more tokens.
+
+Motion is the same answer for a stronger reason: **no** consumer declares a
+duration or easing scale. What three of them do share, verbatim, is a
+`prefers-reduced-motion` block — an accessibility guard rather than a scale, and
+a better candidate for sharing than any easing curve.
+
+### Making a surface interactive: `hover:bg-accent`
+
+A clickable card, row or tile takes the ordinary shadcn treatment, and it works:
+
+```svelte
+<Card class="hover:bg-accent/50 cursor-pointer">…</Card>
+```
+
+`bg-accent` is a **12% tint of `--ds-color-primary`**, the same fill the active
+nav row wears — so a hover reads as the same language as a selection, and it
+follows an app's own accent with no per-app CSS. Reach for it rather than
+writing a local `hover:border-primary`, which is what four apps had each
+arrived at separately.
+
+It has not always worked, and the way it failed is worth keeping. Until
+`2026.8.17`, `--color-accent` and `--color-card` both resolved to
+`--ds-color-surface-2` — the same rung — so `hover:bg-accent/50` on a card
+mixed a colour at 50% over a ground identical to it and could not move a pixel.
+Every app that made a card clickable shipped a control with no hover
+affordance, and nothing caught it: it compiled, type-checked, passed the
+component tests, and satisfied every contrast check on text. It was wrong only
+when a human moved a mouse.
+
+So the gate for it is a value comparison in a real browser rather than a
+structural one — `harness/drive.mjs` drives a pointer onto a card in both
+colour schemes, composites the resting and hovered fills, and asserts they
+differ, that the difference is large enough to see, and that **the hover fill
+moves when the app retunes `--ds-color-primary`**. That last check is the one
+that matters: the first two passed against the broken build.
+
+Depth is not the affordance. The household design language separates surfaces
+with the ladder and a hairline edge, not with a drop shadow that grows on
+hover — see `packages/design-tokens/README.md`.
+
 ### Measuring the content region
 
 About overflow, not width — for how wide the body is allowed to get, see
@@ -508,6 +682,60 @@ but the same class on the `<th>` collapses the heading over its neighbour:
 { accessorKey: 'filename', header: 'Document', meta: { class: 'w-full', cellClass: 'max-w-0' } }
 ```
 
+## Hand-written forms
+
+The shadcn-svelte Formsnap wrapper set, over `sveltekit-superforms`:
+
+```svelte
+<script lang="ts">
+	import * as Form from '@poodle64/ui/form';
+	import { Input } from '@poodle64/ui/input';
+</script>
+
+<Form.Field {form} name="title">
+	<Form.Control>
+		{#snippet children({ props })}
+			<Form.Label>Title</Form.Label>
+			<Input {...props} bind:value={$formData.title} />
+		{/snippet}
+	</Form.Control>
+	<Form.Description>What the record is called.</Form.Description>
+	<Form.FieldErrors />
+</Form.Field>
+<Form.Button>Save</Form.Button>
+```
+
+`Field`, `Control`, `Label`, `Description`, `FieldErrors`, `Fieldset`, `Legend`,
+`ElementField` and `Button`, each also exported under a `Form`-prefixed alias
+(`FormField`, `FormLabel`, …) for a flat import.
+
+`formsnap` and `sveltekit-superforms` are **optional peer dependencies**. An app
+that renders no form installs neither and the other 54 components are
+unaffected; an app that does already has both, since these wrappers are useless
+without them.
+
+This is the sibling of [Server-described forms](#server-described-forms) below,
+and the two answer different questions: reach for these when the app knows the
+fields at build time, and for `SchemaForm` when the shape arrives at runtime.
+
+**Why it lives here.** Three apps had vendored the same nine files. The diff
+between two of them was quote style; between those and the third, which package
+the shared `cn` and `Label` were imported from. Nothing had diverged — but every
+one of them owned its own copy of the ARIA wiring, so a fix to how an error is
+announced, or to the `aria-describedby` chain, landed once per app or not at
+all.
+
+That is what the tests assert, rather than the markup: the label resolves `for`
+to the control's generated id, `aria-describedby` reaches both the description
+and the error node, an errored field flips `aria-invalid` and marks the label
+`data-fs-error`, and `Form.Button` is `type="submit"` without the call site
+saying so. Each was driven red before being kept. A test on the class strings
+would have passed against all three copies while any one of them quietly stopped
+pointing at its own error node.
+
+Consumers drop their local `form/` directory at their next frontend change set
+— there is no forced sweep, and their own `check-ui-drift.mjs` will name it.
+
 ## Server-described forms
 
 `<SchemaForm>` renders a config object whose shape arrives at runtime. It is the
@@ -712,15 +940,25 @@ 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
+classes, the `--ds-control-*` geometry the density option turns (below), and the
+two things that make this package's overlays animate at all — a
+`@custom-variant` per `data-state` value (bits-ui emits `data-state="open"`, so
+a bare `data-open:` utility matches nothing without one) 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.
 
+The `data-state` set covers `open`/`closed`, `checked`/`unchecked`/
+`indeterminate` and `active`/`inactive`, so `data-checked:` and `data-active:`
+are usable shorthands in an app's own components too. Only `open`/`closed` were
+declared until 2026.9.0, and the gap was not theoretical: in one app every
+checked checkbox painted no primary fill and every tab strip rendered its
+selected trigger identically to the rest, on eleven routes, for months. Nothing
+fails when a variant is missing — the class is in the DOM, and only the rule is
+absent.
+
 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
@@ -736,6 +974,121 @@ differ on. An app using them registers them itself.
 source scan misses them. Without it the components render unstyled (no build
 error, no lint hit; the classes just never reach the compiled CSS).
 
+### Control density
+
+An app that runs its controls denser than 40px used to have exactly one move
+available: fork `Button`. Its heights were hard-coded Tailwind classes, so no
+token could reach them — and forking Button takes `dialog`, `alert-dialog`,
+`command`, `input-group` and `form` with it, because each of those imports it.
+One app carried all six for that reason, five of them otherwise identical to
+this package's, and pinned a height on 75 call sites across 20 files.
+
+The knob is one attribute, on any ancestor — ordinarily `<html>`, in
+`app.html`:
+
+```html
+<html lang="en-AU" data-ds-density="compact"></html>
+```
+
+Two named values, `comfortable` (the default) and `compact`:
+
+| Size      | comfortable | compact |
+| --------- | ----------- | ------- |
+| `xs`      | 28px        | 24px    |
+| `sm`      | 36px        | 28px    |
+| `default` | 40px        | 32px    |
+| `lg`      | 44px        | 36px    |
+
+Inline padding and the trim beside an icon move with the height; the `icon-*`
+sizes stay squares of the same heights.
+
+`compact` is not a picked scale. This package's `Input` already renders at 32px
+and its `Select` trigger at 32/28px, so a default-size `Button` beside an
+`Input` has always been 8px taller than it. At `compact` they are the same
+height, which is the alignment the forking app was hand-pinning.
+
+The attribute is honoured wherever it appears, so a dense toolbar can carry it
+without the page doing so — and `data-ds-density="comfortable"` on a subtree
+returns that subtree to the default inside a compact page.
+
+Nothing moves for an app that names no density: the `--ds-control-*` defaults
+reproduce the previous hard-coded classes exactly, measured in a real browser
+(`harness/drive.md` §"The control density ramp") rather than asserted here.
+Hand-tuning an individual rung remains possible and remains a deviation — the
+sanctioned move is choosing a named density, as choosing a palette rather than a
+hex value is the sanctioned move for colour.
+
+### Checkbox and Switch
+
+Both carry a transparent `::after` skirt that lifts the pointer target over WCAG
+2.5.8's 24px minimum without moving a painted pixel — a 16px checkbox has a 29px
+target, a 36x20px switch track a 35x31px one. Both take `aria-invalid`, which
+paints the destructive ring the inputs already use, so a Formsnap-wired field
+marks itself. `Checkbox` binds `indeterminate` and now paints the same fill as a
+checked box for it, rather than a dash on a transparent ground. `Switch` takes
+`size="sm"`, a 28x16px track that lines up with a `size="sm"` control row.
+
+## Australian value formatters
+
+```ts
+import { formatCurrency, formatDate, formatPercentage } from '@poodle64/ui/format';
+```
+
+Money, dates and times, percentages and plain numbers, in `en-AU` / AUD /
+`Australia/Brisbane`. No dependencies and no DOM — it is `Intl` and arithmetic,
+so it runs in a load function as happily as in a component.
+
+| Function                                                      | What it does                                                                                                                                |
+| ------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
+| `formatCurrency(dollars, opts)`                                | `$1,234.56`. `decimals` (default 2), `currency` (default AUD), `fallback`.                                                                   |
+| `formatCurrencyFromCents(cents, opts)`                         | The same, for money stored as integer cents.                                                                                                 |
+| `formatCurrencyString(str, opts)`                              | Groups a money STRING without ever parsing it to a float — for a figure that reaches a tax return.                                            |
+| `compactCurrency(value, opts)`                                 | `$1.1m` / `$12k`, for a chart axis or a dense tile.                                                                                          |
+| `isNegativeMoney(value)`                                       | The sign, without a parse, for choosing a tone class.                                                                                        |
+| `dollarsToCents(dollars)`                                      | Whole cents.                                                                                                                                 |
+| `formatNumber(value, opts)`                                    | `1,234,567`.                                                                                                                                 |
+| `formatPercentage(value, opts)`                                | Value is already in percentage POINTS: `4.5` → `4.5%`.                                                                                       |
+| `formatRatioAsPercentage(value, opts)`                         | Value is a 0–1 RATIO: `0.045` → `4.5%`.                                                                                                      |
+| `formatDate(value, opts)`                                      | `19 Dec 2024`, `19 December 2024` (`format: 'long'`) or `19/12/2024` (`format: 'numeric'`).                                                   |
+| `formatDateTime(value, opts)`                                  | The same plus a 24-hour time: `19 Dec 2024, 14:05`.                                                                                          |
+| `parseApiDate(iso)`                                            | Reads an offset-less timestamp as UTC — the naive-UTC backend trap below.                                                                     |
+
+Four decisions worth knowing before a migration, because each was settled
+against an app that had decided it the other way:
+
+- **A missing value renders `N/A`**, and every formatter takes `fallback` to say
+  otherwise. `-` is deliberately not the default: beside a money column it reads
+  as a minus sign.
+- **Money keeps its cents by default.** Dropping them is a loss of fidelity the
+  caller asks for (`{ decimals: 0 }`), not the default that rounds $1,234.56 up
+  to $1,235.
+- **A negative carries its sign outside the symbol** — `-$1,234.56`, never
+  `$-1,234.56`.
+- **`formatPercentage` and `formatRatioAsPercentage` are named apart on
+  purpose.** The two apps had settled on `formatPercent` meaning opposite
+  things; reusing either spelling for both would make a 100x error a
+  one-character mistake.
+
+Timestamps are read in `Australia/Brisbane` unless a `timeZone` is passed. The
+household's books are kept in AEST, so a laptop in another zone should not
+renumber them — and it makes the output deterministic under CI. A date-only
+value (`YYYY-MM-DD`) gets no zone conversion at all: a date is not an instant,
+and converting one is how a booking dated the 1st shows as the 31st.
+
+`parseApiDate` exists because a backend that stores naive UTC
+(`datetime.now(UTC).replace(tzinfo=None)`) serialises it with no offset, and
+JavaScript reads that as LOCAL time. In Brisbane that lands every stored moment
+ten hours early, so anything after 2pm UTC shows the wrong DAY. `formatDate` and
+`formatDateTime` already go through it; call it directly when you need the
+`Date` itself.
+
+Deliberately not here: file sizes, AI model names, loan repayment frequencies,
+pager arithmetic and the per-line GST recompute for bill approvals. Each has one
+consumer and is a domain vocabulary rather than a shared value class; the GST
+one is bound to Xero tax codes besides. Relative time ("2 hours ago") is out
+too — it rides on `date-fns` in the one app that has it, and a display formatter
+is not worth making that a dependency of every consumer.
+
 ## Verifying a change
 
 ```bash

package/dist/components/ui/button/button.svelte

@@ -18,18 +18,23 @@
 					'bg-destructive/10 hover:bg-destructive/20 focus-visible:ring-destructive/20 dark:focus-visible:ring-destructive/40 dark:bg-destructive/20 text-destructive focus-visible:border-destructive/40 dark:hover:bg-destructive/30',
 				link: 'text-primary underline-offset-4 hover:underline'
 			},
+			// Every geometry value here is a `--ds-control-*` token whose default is
+			// the class it replaced (`h-10` is 2.5rem, `px-4` is 1rem, …), so a
+			// consumer that names no density renders unchanged. The tokens, the two
+			// named densities and why the ramp is a table rather than a ratio are in
+			// styles.css §"Control geometry".
 			size: {
 				default:
-					'h-10 gap-1.5 px-4 has-data-[icon=inline-end]:pr-3 has-data-[icon=inline-start]:pl-3',
-				xs: "h-7 gap-1 rounded-[min(var(--radius-md),10px)] px-2.5 text-xs in-data-[slot=button-group]:rounded-lg has-data-[icon=inline-end]:pr-1.5 has-data-[icon=inline-start]:pl-1.5 [&_svg:not([class*='size-'])]:size-3",
-				sm: "h-9 gap-1.5 rounded-[min(var(--radius-md),12px)] px-3.5 text-[0.85rem] in-data-[slot=button-group]:rounded-lg has-data-[icon=inline-end]:pr-2 has-data-[icon=inline-start]:pl-2 [&_svg:not([class*='size-'])]:size-4",
-				lg: 'h-11 gap-1.5 px-5 has-data-[icon=inline-end]:pr-3 has-data-[icon=inline-start]:pl-3',
-				icon: 'size-10',
+					'h-(--ds-control-height-md) gap-1.5 px-(--ds-control-pad-md) has-data-[icon=inline-end]:pr-(--ds-control-pad-icon-md) has-data-[icon=inline-start]:pl-(--ds-control-pad-icon-md)',
+				xs: "h-(--ds-control-height-xs) gap-1 rounded-[min(var(--radius-md),10px)] px-(--ds-control-pad-xs) text-xs in-data-[slot=button-group]:rounded-lg has-data-[icon=inline-end]:pr-(--ds-control-pad-icon-xs) has-data-[icon=inline-start]:pl-(--ds-control-pad-icon-xs) [&_svg:not([class*='size-'])]:size-3",
+				sm: "h-(--ds-control-height-sm) gap-1.5 rounded-[min(var(--radius-md),12px)] px-(--ds-control-pad-sm) text-[0.85rem] in-data-[slot=button-group]:rounded-lg has-data-[icon=inline-end]:pr-(--ds-control-pad-icon-sm) has-data-[icon=inline-start]:pl-(--ds-control-pad-icon-sm) [&_svg:not([class*='size-'])]:size-4",
+				lg: 'h-(--ds-control-height-lg) gap-1.5 px-(--ds-control-pad-lg) has-data-[icon=inline-end]:pr-(--ds-control-pad-icon-lg) has-data-[icon=inline-start]:pl-(--ds-control-pad-icon-lg)',
+				icon: 'size-(--ds-control-height-md)',
 				'icon-xs':
-					"size-7 rounded-[min(var(--radius-md),10px)] in-data-[slot=button-group]:rounded-lg [&_svg:not([class*='size-'])]:size-3",
+					"size-(--ds-control-height-xs) rounded-[min(var(--radius-md),10px)] in-data-[slot=button-group]:rounded-lg [&_svg:not([class*='size-'])]:size-3",
 				'icon-sm':
-					'size-9 rounded-[min(var(--radius-md),12px)] in-data-[slot=button-group]:rounded-lg',
-				'icon-lg': 'size-11'
+					'size-(--ds-control-height-sm) rounded-[min(var(--radius-md),12px)] in-data-[slot=button-group]:rounded-lg',
+				'icon-lg': 'size-(--ds-control-height-lg)'
 			}
 		},
 		defaultVariants: {

package/dist/components/ui/checkbox/checkbox.svelte

@@ -13,13 +13,35 @@
 	}: WithoutChildrenOrChild<CheckboxPrimitive.RootProps> & { class?: string } = $props();
 </script>
 
+<!--
+  The box is 16px, which is what a checkbox has always looked like and is also
+  well under WCAG 2.5.8's 24px minimum target. The `::after` overlay is the
+  standard answer: a transparent skirt on every side takes the POINTER target to
+  a measured 29px without moving a pixel of the control, so the tick still sits where a
+  reader expects it and the row's rhythm is unchanged. `harness/drive.mjs`
+  measures that by walking outward from the centre until the hit test stops
+  returning this element, rather than by trusting the arithmetic here.
+
+  The inset is 2 rather than 1.5 for margin, not neatness: 1.5 measured 25px,
+  which clears the 24px floor at a 16px root and misses it at a 14px one — and
+  the floor is in absolute CSS pixels while the skirt is in rem. It stops 1px
+  short of a `gap-2` label, and a click that lands on the label toggles the box
+  through the label's own `for` anyway, so the enlarged area can never steal an
+  interaction from something else.
+
+  `data-indeterminate` paints the same fill as `data-checked`. It carried none
+  until now, so a tri-state checkbox rendered its dash in the FOREGROUND ink on
+  a transparent ground — the identical defect the `data-checked` mapping was
+  fixed for, one value along, and invisible for the same reason. See styles.css
+  §"The bits-ui `data-state` variants".
+-->
 <CheckboxPrimitive.Root
 	bind:ref
 	bind:checked
 	bind:indeterminate
 	data-slot="checkbox"
 	class={cn(
-		'peer border-border focus-visible:ring-ring data-[state=checked]:bg-primary data-[state=checked]:text-primary-foreground data-[state=checked]:border-primary size-4 shrink-0 rounded-sm border shadow-none transition-shadow focus-visible:ring-1 focus-visible:outline-none disabled:cursor-not-allowed disabled:opacity-50',
+		'peer border-border focus-visible:ring-ring data-checked:bg-primary data-checked:text-primary-foreground data-checked:border-primary data-indeterminate:bg-primary data-indeterminate:text-primary-foreground data-indeterminate:border-primary aria-invalid:ring-destructive/20 dark:aria-invalid:ring-destructive/40 aria-invalid:border-destructive dark:aria-invalid:border-destructive/50 relative size-4 shrink-0 rounded-sm border shadow-none transition-shadow after:absolute after:-inset-2 focus-visible:ring-1 focus-visible:outline-none disabled:cursor-not-allowed disabled:opacity-50 aria-invalid:ring-3',
 		className
 	)}
 	{...restProps}

package/dist/components/ui/dropdown-menu/dropdown-menu-content.svelte

@@ -23,7 +23,7 @@
 		{sideOffset}
 		{align}
 		class={cn(
-			'data-open:animate-in data-closed:animate-out data-closed:fade-out-0 data-open:fade-in-0 data-closed:zoom-out-95 data-open:zoom-in-95 data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 bg-popover text-popover-foreground data-[side=inline-start]:slide-in-from-right-2 data-[side=inline-end]:slide-in-from-left-2 z-50 max-h-(--bits-dropdown-menu-content-available-height) min-w-44 overflow-x-hidden overflow-y-auto rounded-lg border border-[--border-strong] p-1 whitespace-nowrap shadow-lg duration-100 outline-none data-closed:overflow-hidden',
+			'data-open:animate-in data-closed:animate-out data-closed:fade-out-0 data-open:fade-in-0 data-closed:zoom-out-95 data-open:zoom-in-95 data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 bg-popover text-popover-foreground data-[side=inline-start]:slide-in-from-right-2 data-[side=inline-end]:slide-in-from-left-2 z-50 max-h-(--bits-dropdown-menu-content-available-height) min-w-44 overflow-x-hidden overflow-y-auto rounded-lg border border-border-strong p-1 whitespace-nowrap shadow-lg duration-100 outline-none data-closed:overflow-hidden',
 			className
 		)}
 		{...restProps}

package/dist/components/ui/form/form-button.svelte

@@ -0,0 +1,7 @@
+<script lang="ts">
+	import { Button, type ButtonProps } from '../button/index.js';
+
+	let { ref = $bindable(null), ...restProps }: ButtonProps = $props();
+</script>
+
+<Button bind:ref type="submit" {...restProps} />

package/dist/components/ui/form/form-button.svelte.d.ts

@@ -0,0 +1,4 @@
+import { type ButtonProps } from '../button/index.js';
+declare const FormButton: import("svelte").Component<ButtonProps, {}, "ref">;
+type FormButton = ReturnType<typeof FormButton>;
+export default FormButton;

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

@@ -0,0 +1,18 @@
+<script lang="ts">
+	import * as FormPrimitive from 'formsnap';
+	import { cn } from '../../../utils.js';
+	import type { WithoutChild } from '../../../utils.js';
+
+	let {
+		ref = $bindable(null),
+		class: className,
+		...restProps
+	}: WithoutChild<FormPrimitive.DescriptionProps> = $props();
+</script>
+
+<FormPrimitive.Description
+	bind:ref
+	data-slot="form-description"
+	class={cn('text-muted-foreground text-sm', className)}
+	{...restProps}
+/>

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

@@ -0,0 +1,4 @@
+import * as FormPrimitive from 'formsnap';
+declare const FormDescription: import("svelte").Component<Omit<FormPrimitive.DescriptionProps, "child">, {}, "ref">;
+type FormDescription = ReturnType<typeof FormDescription>;
+export default FormDescription;

package/dist/components/ui/form/form-element-field.svelte

@@ -0,0 +1,25 @@
+<script lang="ts" generics="T extends Record<string, unknown>, U extends FormPathLeaves<T>">
+	import * as FormPrimitive from 'formsnap';
+	import type { FormPathLeaves } from 'sveltekit-superforms';
+	import type { HTMLAttributes } from 'svelte/elements';
+	import { cn } from '../../../utils.js';
+	import type { WithElementRef, WithoutChildren } from '../../../utils.js';
+
+	let {
+		ref = $bindable(null),
+		class: className,
+		form,
+		name,
+		children: childrenProp,
+		...restProps
+	}: WithoutChildren<WithElementRef<HTMLAttributes<HTMLDivElement>>> &
+		FormPrimitive.ElementFieldProps<T, U> = $props();
+</script>
+
+<FormPrimitive.ElementField {form} {name}>
+	{#snippet children({ constraints, errors, tainted, value })}
+		<div bind:this={ref} class={cn('space-y-2', className)} {...restProps}>
+			{@render childrenProp?.({ constraints, errors, tainted, value: value as T[U] })}
+		</div>
+	{/snippet}
+</FormPrimitive.ElementField>