@ponchia/ui 0.7.0 → 0.8.1

package/docs/stability.md

@@ -1,7 +1,7 @@
 # Public API stability
 
 `@ponchia/ui` is pre-1.0. Breaking changes ship in the minor (`0.x.0`), and
-patches are non-breaking. In practical terms: **PATCH releases (`0.7.x`) are
+patches are non-breaking. In practical terms: **PATCH releases (`0.8.x`) are
 non-breaking bug-fixes and additive changes — safe to upgrade without review;
 MINOR releases (`0.x.0`) may include breaking changes and consumers should
 review the CHANGELOG before upgrading.** Pin `~0.x` (tilde) to accept only
@@ -68,13 +68,41 @@ Package-proven is necessary but does not establish demand. During the catalog
 freeze, do not expand package-only surfaces. Recheck this table against real
 consumer upgrades before the 1.0 release candidate.
 
+> **The 0.8.0 consumer audit — read this before trusting the table below.** A
+> full-surface audit of the largest downstream consumer (a Yjs-collaborative
+> spatial canvas workspace: React, Vite, ~10k lines of its own CSS) found it
+> using **26 of the 646 published classes**, and hand-rebuilding much of the
+> rest — 10 bespoke empty states, 15 error surfaces, 17 control bars, three
+> parallel severity vocabularies, its own Markdown prose layer, its own diff
+> rows, its own meters, and two copies of visually-hidden text. Thirteen
+> primitives that map almost exactly onto what it built return **zero** uses:
+> `ui-state`, `ui-prose`, `ui-diff`, `ui-code`, `ui-meter`, `ui-progress`,
+> `ui-toolstrip`, `ui-dot`, `ui-chip`, `ui-tag`, `ui-timeline`, `ui-steps`,
+> `ui-job`.
+>
+> The lesson for this document is not about that consumer. It is that **"no
+> inspected consumer imports the surface" has been measuring discoverability,
+> not demand.** Those surfaces were not rejected; they were never found. The
+> opt-in leaf model is right, but nothing tells a consumer which leaf it is
+> about to reimplement — and `bronto-ui-check`, which catches part of it, was
+> installed in that consumer and had never been run. Before any 1.0 decision
+> retires a package-proven surface for lack of adoption, confirm the surface was
+> *reachable*: named in the consumer's imports, or at least in a leaf it
+> imports. Non-adoption of an unimported leaf is not evidence.
+>
+> The same audit produced this release's four consumer-driven changes (the tap
+> target floor, the safe-area tokens, `ui-button__label`, and the dense tier)
+> and the ADR-0001 canvas amendment. That is the intended loop: the consumer's
+> local classes are the backlog, resolving either to a deletion there or an
+> addition here.
+
 | Surface family | Current evidence | 1.0 disposition |
 | --- | --- | --- |
 | Core CSS, class recipes, vanilla behaviors, tokens, and Tailwind bridge | Downstream-proven across five inspected non-example app, site, and service consumers. | Stabilize names and behavior contracts. Use consumer upgrades as the release-candidate proof. |
 | Report, provenance, analytical CSS, annotations, glyphs, skins, workbench CSS, chart data, and Vega theme | Downstream-proven across four inspected report, site, dashboard, and tool consumers. | Keep opt-in. Stabilize the consumed paths; do not broaden the catalog during the freeze. |
 | Controlled non-`<dialog>` modal | Package-proven by stack, portal, late-node, focus, and cleanup regressions. None of ten inspected non-example consumers initializes `initModal`. | Deprecated in 0.7; remove no earlier than 0.8 unless a real consumer adopts it. Native `<dialog>` + `initDialog` is the stable path. |
 | React, Solid, Qwik, Svelte, and Vue lifecycle adapters | Package-proven by packed examples, types, and lifecycle tests. None of ten inspected non-example consumers imports an adapter entrypoint. | Deprecated in 0.7; remove no earlier than 0.8 unless a real consumer adopts one. Vanilla behaviors remain stable. |
-| Mermaid, D2, Shiki, Figma Variables, and the report-claims schema | Package-proven by generated-data, render, schema, and drift checks. No inspected non-example consumer currently supplies downstream proof for every path. | Keep compatible through 0.7.x, but decide each 1.0 contract from adoption evidence rather than generator coverage alone. |
+| Mermaid, D2, Shiki, Figma Variables, and the report-claims schema | Package-proven by generated-data, render, schema, and drift checks. No inspected non-example consumer currently supplies downstream proof for every path. | Keep compatible through 0.8.x, but decide each 1.0 contract from adoption evidence rather than generator coverage alone. |
 
 After 1.0, breaking changes move to majors. Until then, the table below is the
 current public-surface matrix and the release policy above still applies.
@@ -85,6 +113,7 @@ current public-surface matrix and the release policy above still applies.
 | JS module format | Stable | JS subpaths are ESM-only. CommonJS consumers use dynamic `import()`. |
 | CSS class names (`.ui-*`) | Stable | Names and documented modifier semantics are public. Internal selector structure and leaf-file boundaries may change. |
 | Class recipes (`@ponchia/ui/classes`) | Stable | Exported `cls`, `ui`, `cx`, `attrs`, recipe names, ARIA attribute helper names, and option unions are public. |
+| Severity ladder (`SEVERITY_LEVELS`, `severity()`, `.ui-severity*`) | Stable additive | The tier names and **their order** are public: `critical` › `error` › `warning` › `notice` › `ok`, with `unknown` deliberately outside the ordering as the fallback for "not measured". `severity()` returns `{ class, 'data-level' }`, and `data-level` is the public attribute contract — a host may carry it on its own element and read `var(--severity-tone)`. New tiers would be a breaking reorder, not an addition, so the ladder is closed; new *parts* (`chip`/`dot`/`row`) are additive. Ships in the opt-in `css/state.css`, not the default bundle. |
 | Class vocabulary as data (`@ponchia/ui/classes.json`, `@ponchia/ui/vscode.css-custom-data.json`) | Stable additive | The JSON shape (`groups`/`classes`/`states`/`customProperties`) and class/custom-property entries are public — for validating markup from a non-JS/non-TS host or editor integration. Generated from `cls` and CSS selectors; `classes.json`, `.d.ts`, reference docs, and VS Code custom data are drift-checked together. New classes/hooks are additive. |
 | Design tokens | Stable names/roles | Token names and documented roles are public. Exact values and generated colour math outputs may change for visual tuning before 1.0. |
 | `--accent-1..6` | Stable names/roles | A subtle-to-bold accent ramp derived from `--accent`. Exact resolved values are visual tuning; algorithm changes require release-note visibility and resolver/browser checks. |

package/docs/state.md

@@ -124,14 +124,64 @@ For indeterminate jobs, omit the progress block or omit `aria-valuenow`, and
 make the written state clear ("Running", "Waiting for worker", "Retrying").
 Use `ui-job--compact` for dense queues.
 
+## Severity — `.ui-severity`
+
+`.ui-state` answers *what is this thing doing*. Severity answers *how bad is
+it*. Bronto already shipped the tones as per-component modifiers, but never the
+**scale** — the tier names, their order, and the attribute carrying them. So
+every consumer invents the ladder, and inside one app it drifts: one surface
+saying `critical|error|warning|note`, the next `bad|warn`, a third
+`critical|warning|info|ok`, under two different attribute names. Findings then
+do not sort against alerts, and a filter written for one list misses the other.
+
+The ladder, worst to best:
+
+| Level | Means |
+| --- | --- |
+| `critical` | Broken now, and still losing something. |
+| `error` | Something failed; it is not currently getting worse. |
+| `warning` | A threshold was crossed; nothing has failed yet. |
+| `notice` | Worth reading, no action implied. |
+| `ok` | Checked and healthy — an **assertion**, not the absence of news. |
+| `unknown` | Not measured, stale, or the check itself failed. |
+
+`unknown` sits **outside** the ordering on purpose. It is not "slightly worse
+than ok", it is "we do not know" — and collapsing it into `ok` is how a dead
+collector reads as a healthy system. `SEVERITY_LEVELS` therefore excludes it.
+
+The level travels on `data-level`, one attribute name, so the same selector
+works on a chip, a row, a dot, or your own element via `var(--severity-tone)`:
+
+```html
+<span class="ui-severity" data-level="critical">Critical</span>
+
+<li class="ui-severity-row" data-level="warning">
+  <span class="ui-severity-row__title">Disk 84% on kpi-1</span>
+  <span class="ui-severity-row__meta">12m</span>
+</li>
+```
+
+Colour is never the only channel (WCAG 1.4.1): `.ui-severity` carries an
+author-written label, and `.ui-severity-dot` is only for rows that **also** name
+their level in text.
+
 ## Recipe
 
 ```js
-import { ui } from '@ponchia/ui/classes';
+import { ui, severity, SEVERITY_LEVELS } from '@ponchia/ui/classes';
 
 ui.state({ state: 'saving', busy: true }); // "ui-state ui-state--saving ui-state--busy"
 ui.state({ state: 'conflict' }); // "ui-state ui-state--conflict"
 ui.job({ state: 'running' }); // "ui-job ui-job--running"
+
+// Bundles the class WITH data-level, so the attribute that carries the meaning
+// cannot be forgotten — the class alone paints the neutral tone and silently
+// loses the level.
+severity('critical'); // { class: 'ui-severity', 'data-level': 'critical' }
+severity('warning', { part: 'row' }); // { class: 'ui-severity-row', … }
+severity('nope'); // { class: 'ui-severity', 'data-level': 'unknown' }
+
+SEVERITY_LEVELS; // ['critical','error','warning','notice','ok'] — sort/filter from this
 ```
 
 ## Scope

package/docs/theming.md

@@ -140,6 +140,24 @@ you change CSS `--accent` later.
   [ADR-0003](adr/0003-theme-model.md) for the theme-model rationale.
 - **Radius** — `--radius-sm … --radius-xl`, `--radius-pill`. The Nothing
   default is near-sharp; raise these for a softer brand.
+- **Tap targets** — `--tap-target` (44px, WCAG 2.5.5 / iOS HIG / Material) is
+  the floor every control floats to inside `@media (pointer: coarse)`;
+  `--tap-target-min` (24px) is the WCAG 2.5.8 AA minimum used by controls that
+  only have to clear the smaller bar. Both are authored as `max(px, rem)` on
+  purpose: they scale up with a larger root font but **cannot shrink below the
+  standard** if you re-point `html { font-size }`. If you override them, keep
+  the clamp — a bare rem is how a 44px floor quietly becomes 43.5px. Raise them
+  for a glove-friendly or kiosk build; do not lower them.
+- **Safe areas** — `--safe-area-top / -right / -bottom / -left` default to
+  `env(safe-area-inset-*, 0px)`, so they are 0 everywhere except a device with
+  a display cutout or a gesture bar. Every viewport-anchored surface Bronto
+  ships reads them: the app rail and topbar, a sticky site header, the skip
+  link, both toast stacks, the drawer modal and the lightbox. Override them
+  when your host supplies its own insets — an embedded webview, a kiosk frame,
+  or a test runner that cannot emulate `env()`, which is the reason the values
+  are indirected through custom properties rather than called at the point of
+  use. Consumers positioning their own floating chrome should follow the same
+  convention: `inset-block-end: max(<your offset>, var(--safe-area-bottom))`.
 - **Type** — `--display` (dot-matrix face), `--mono`, `--sans`. Override
   to drop Doto or swap the body face; the token layer keeps working even
   if you self-host fonts (see the `fonts.css` note in the README).

package/docs/usage.md

@@ -167,15 +167,50 @@ a `.ui-legend` key, and fallback data. Full LLM/static report cookbook:
 
 ## Buttons: variant and size
 
-- **primary** — the single most important action in a view. Aim for one.
+- **primary is the bare `ui-button`.** There is no `--primary` and no
+  `--accent`: the unmodified class already paints the accent fill, and the
+  variants below all step *down* from it. Aim for one per view. Consumers reach
+  for a `--primary` or `--accent` modifier often enough that it is worth
+  stating plainly: neither exists. Writing one is harmless *and invisible* —
+  the unknown class does nothing and the button still looks right, which is why
+  the mistake survives review. `bronto-ui-check` is what catches it.
 - **ghost** — secondary actions; the default for "another button here".
 - **subtle** — tertiary / low-stakes (toolbar, inline).
+- **danger** — destructive confirmation.
 - Size: default everywhere; `--sm` for dense tooling (toolbars,
-  pagination, table row actions), `--lg` for a hero CTA only.
+  pagination, table row actions), `--lg` for a hero CTA only, `--dense` when a
+  bar's *height* is the constraint (a pane title bar). `--dense` lowers only the
+  visual floor — coarse pointers still get the full `--tap-target`, so a control
+  you shrink for a mouse is never shrunk for a finger.
 - Loading is **not** a class: set `aria-busy="true"` (+ `disabled`); the
   spinner is CSS. This is the ARIA-driven contract — see reference.md
   → "Composition & state".
 
+## Empty state vs invite
+
+Both use `ui-empty-state`, and the slots are the same three parts — a quiet
+`__glyph`, one sentence of full ink in `__lead`, a quieter `__hint`. What
+differs is the job:
+
+- **Plain `ui-empty-state`** *reports absence*: a dashed card saying this region
+  has no rows today. Use it for a list, a table, a results pane.
+- **`--invite`** *offers the next action*: no dashed box (there is nothing to
+  outline — the surface itself is what you are being invited into) and it
+  centres in whatever block space it is given. Use it for a surface the user is
+  meant to fill.
+
+```html
+<div class="ui-empty-state ui-empty-state--invite">
+  <span class="ui-empty-state__glyph" aria-hidden="true">+</span>
+  <p class="ui-empty-state__lead">Nothing pinned yet</p>
+  <p class="ui-empty-state__hint">Drop a file here, or press ⌘K</p>
+</div>
+```
+
+Without the slots, every empty surface in an app re-invents these three parts
+under a different name and they drift — one has a glyph, the next has two
+sentences at the same weight, a third is a bare `<p>`.
+
 ## Link vs link--cta
 
 Plain `ui-link` for in-flow links. `ui-link--cta` is the eyebrow-faced
@@ -278,6 +313,31 @@ without it these widgets are unlabelled or unannounced:
 - **Icon-only buttons** (`ui-button--icon` and any glyph-only control) carry no
   text node, so they're nameless to AT — give them an `aria-label`
   (`<button class="ui-button ui-button--icon" aria-label="Delete">`).
+  Prefer `ui-button__label` when the same control also appears with its word
+  visible, or when a test reads the button by its text. Wrap the text in the
+  slot and let `--icon` decide whether it is painted — the markup does not
+  change, the accessible name survives, and no `aria-label` can drift out of
+  sync with the visible wording:
+
+  ```js
+  // The mask comes from renderGlyph(..., { render: 'mask' }) — there is no
+  // --glyph-* token.
+  const mask = renderGlyph('trash', { render: 'mask' });
+  el.innerHTML =
+    `<button class="ui-button ui-button--icon">` +
+    `<span class="ui-icon" style="--icon-mask: ${mask}"></span>` +
+    `<span class="ui-button__label">Delete</span>` +
+    `</button>`;
+  ```
+
+  Drop `--icon` and the same markup renders glyph + word. The slot also
+  ellipsises rather than wrapping, so a labelled button in a width-constrained
+  bar shrinks instead of pushing its neighbours out.
+- **`ui-button--dense`** is for bars whose height is the constraint — a pane
+  title bar, a packed toolbar, a table row's actions. It lowers only the
+  *visual* floor, to the WCAG 2.5.8 24px minimum. The coarse-pointer block
+  still floats it to the full `--tap-target`, so a control you shrink for a
+  mouse is never shrunk for a finger.
 - **`ui-sitenav` / `ui-app-nav`** — signal the current link with
   `aria-current="page"` (both honour it; `ui-app-nav` also accepts the
   visual-only `.is-active`, but prefer `aria-current`).

package/docs/workbench.md

@@ -1,4 +1,4 @@
-# Workbench — split panes, toolstrips, inspector, properties, selection bar
+# Workbench — panes, split panes, toolstrips, inspector, properties, selection bar
 
 `@ponchia/ui/css/workbench.css` is an opt-in set of primitives for **real
 tools**: resizable split panes, compact toolstrips, button-mode segmented
@@ -52,6 +52,29 @@ hiding, and placement.
 </header>
 ```
 
+### Pane-scale — `.ui-toolstrip--pane`
+
+The app has one toolstrip; a workbench full of panes has one *per pane*, and
+those are a different thing. The difference is framing, not density: a pane bar
+is a row inside a surface that already has a border, so it drops its own frame
+and corners and rules off from the content below.
+
+It also refuses to wrap. A pane bar usually sits directly above content that may
+be a live terminal, an editor, or a video — and a second row would resize that
+content every time a control appears. The row scrolls instead, and
+`.ui-toolstrip__fill` marks the one element that absorbs slack and gives it back
+first (a title, a path, a filter input), so nothing else is pushed out of reach.
+
+```html
+<div class="ui-toolstrip ui-toolstrip--pane">
+  <button class="ui-button ui-button--subtle ui-button--dense" type="button">Run</button>
+  <span class="ui-toolstrip__fill ui-mono">src/server/routes/reports.ts</span>
+  <button class="ui-button ui-button--ghost ui-button--icon ui-button--dense" type="button">
+    <span class="ui-button__label">Close</span>
+  </button>
+</div>
+```
+
 ## Button segmented control — `.ui-segmented-buttons`
 
 Use `.ui-segmented-buttons` when each option is a real command button and the
@@ -170,11 +193,67 @@ A raised bar of actions on the current selection: a `__count` on one side,
 </div>
 ```
 
+### Anchoring a floating bar
+
+Both `--floating` bars are raised but position-less, so every consumer
+re-derives the same thing — including the `max(offset, inset)` shape, which is
+the part people get wrong by writing a bare offset that a phone then swallows
+under the home indicator. `--anchored` centres the bar against its positioned
+ancestor and clears the safe area:
+
+```html
+<div class="ui-selectionbar ui-selectionbar--anchored">…</div>
+
+<!-- The bar that must NOT sit under the thumb: recovery, destructive actions. -->
+<div class="ui-selectionbar ui-selectionbar--anchor-block-start">…</div>
+```
+
+`--anchored` alone means bottom. Override the gap with `--anchor-offset`. The
+host still owns `z-index`, because only it knows what else is on the canvas.
+
+## Pane — `.ui-pane`
+
+`.ui-panel` is a padded card and `.ui-inspector` is head-plus-body; neither is a
+*window*. A pane is what a canvas node, a floating tool window, or a dockable
+panel needs: a header you can drag, a title that renames in place, an actions
+slot that survives a narrow pane, and a body that owns the rest.
+
+```html
+<article class="ui-pane">
+  <header class="ui-pane__head">
+    <strong class="ui-pane__title">deploy.log</strong>
+    <span class="ui-pane__actions">
+      <button class="ui-button ui-button--subtle ui-button--icon ui-button--dense" type="button">
+        <span class="ui-button__label">Focus</span>
+      </button>
+    </span>
+  </header>
+  <div class="ui-pane__body">…</div>
+</article>
+```
+
+Two behaviours are worth knowing, because both come from a real failure:
+
+- **The title gives up space first.** It is the only thing in the header that
+  can be truncated without losing a function.
+- **`__actions` scrolls rather than pushing.** Sized `flex: 0 1 auto` with
+  `overflow-x: auto`, so a pane narrow enough to run out of room scrolls its
+  controls instead of pushing the last one past the clipped edge — which is how
+  an app ends up with a Focus or Disconnect button that exists, is in the a11y
+  tree, and cannot be reached.
+
+Swap the title for `.ui-pane__title-input` to rename in place. It inherits the
+type it replaces, so the swap moves no layout; only the accent border says you
+are typing a name now. The host owns dragging, z-order, focus policy and
+persistence — this leaf has no behavior.
+
 ## Scope
 
-No recipes — these are structural containers and rows; apply the classes
-directly (or read them from `cls.toolstrip`, `cls.splitter`, `cls.inspector`,
-`cls.property`, …). Pair the selection bar with the cross-cutting
+No recipes for the structural containers and rows; apply the classes directly
+(or read them from `cls.toolstrip`, `cls.pane`, `cls.splitter`, `cls.inspector`,
+`cls.property`, …). `ui.toolstrip()` and `ui.selectionbar()` exist only to
+compose the variant/anchor modifiers. Pair the selection bar with the
+cross-cutting
 [`ui-sel`](./selection.md) states on the selected items themselves. Bronto styles
 the chrome and wires the splitter affordance; the host owns hit-testing,
 persistence, pane contents, viewport semantics, and commands.

package/llms.txt

@@ -45,7 +45,7 @@ the path changes from source `css/` to built `dist/css/`:
 <!-- installed locally -->
 <link rel="stylesheet" href="./node_modules/@ponchia/ui/dist/css/<leaf>.css" />
 <!-- or from a CDN; pin the version (pre-1.0, breaking changes ship in the minor) -->
-<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui@0.7.0/dist/css/<leaf>.css" />
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui@0.8.1/dist/css/<leaf>.css" />
 ```
 
 The flattened default bundle is `dist/bronto.css` (bundler shorthand

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ponchia/ui",
-  "version": "0.7.0",
+  "version": "0.8.1",
   "type": "module",
   "description": "CSS-first identity and UI layer for services, tools, sites, and reports — works in HTML, every framework, and PDF, no component runtime. Shared app shell, forms, tables, workflow chrome, plus opt-in analytical/report primitives. Monochrome with one rationed accent. Zero runtime dependencies.",
   "keywords": [
@@ -113,6 +113,7 @@
     "docs/migrations/0.4-to-0.5.md",
     "docs/migrations/0.5-to-0.6.md",
     "docs/migrations/0.6-to-0.7.md",
+    "docs/migrations/0.7-to-0.8.md",
     "docs/adr/0001-color-system.md",
     "docs/adr/0002-scope-and-2026-baseline.md",
     "docs/adr/0003-theme-model.md",
@@ -213,24 +214,24 @@
     "prepublishOnly": "npm run build:artifacts && npm run check"
   },
   "devDependencies": {
-    "@arethetypeswrong/cli": "^0.18.4",
+    "@arethetypeswrong/cli": "^0.18.5",
     "@axe-core/playwright": "^4.11.3",
     "@builder.io/qwik": "^1.20.0",
     "@playwright/test": "1.60.0",
     "github-actionlint": "^1.7.12",
-    "jsdom": "^29.1.1",
-    "knip": "^6.23.0",
-    "pdfjs-dist": "^6.1.200",
-    "prettier": "^3.9.1",
-    "publint": "^0.3.21",
-    "react": "^19.2.7",
-    "react-dom": "^19.2.7",
-    "solid-js": "^1.9.13",
-    "stylelint": "^17.14.0",
+    "jsdom": "^30.0.1",
+    "knip": "^6.32.1",
+    "pdfjs-dist": "^6.2.108",
+    "prettier": "^3.9.6",
+    "publint": "^0.3.23",
+    "react": "^19.2.8",
+    "react-dom": "^19.2.8",
+    "solid-js": "^1.9.14",
+    "stylelint": "^17.14.1",
     "stylelint-config-standard": "^40.0.0",
     "stylelint-use-logical": "^2.1.3",
     "typescript": "^6.0.3",
-    "vega": "^6.2.0",
+    "vega": "^6.3.1",
     "vega-lite": "^6.4.3"
   },
   "peerDependencies": {

package/tokens/figma.variables.json

@@ -1906,6 +1906,62 @@
           },
           "unit": "px"
         },
+        {
+          "name": "safe/area/bottom",
+          "type": "STRING",
+          "sourceCssVariable": "--safe-area-bottom",
+          "valuesByMode": {
+            "global": "env(safe-area-inset-bottom, 0px)"
+          },
+          "$extensions": {
+            "com.ponchia.css": {
+              "variable": "--safe-area-bottom",
+              "value": "env(safe-area-inset-bottom, 0px)"
+            }
+          }
+        },
+        {
+          "name": "safe/area/left",
+          "type": "STRING",
+          "sourceCssVariable": "--safe-area-left",
+          "valuesByMode": {
+            "global": "env(safe-area-inset-left, 0px)"
+          },
+          "$extensions": {
+            "com.ponchia.css": {
+              "variable": "--safe-area-left",
+              "value": "env(safe-area-inset-left, 0px)"
+            }
+          }
+        },
+        {
+          "name": "safe/area/right",
+          "type": "STRING",
+          "sourceCssVariable": "--safe-area-right",
+          "valuesByMode": {
+            "global": "env(safe-area-inset-right, 0px)"
+          },
+          "$extensions": {
+            "com.ponchia.css": {
+              "variable": "--safe-area-right",
+              "value": "env(safe-area-inset-right, 0px)"
+            }
+          }
+        },
+        {
+          "name": "safe/area/top",
+          "type": "STRING",
+          "sourceCssVariable": "--safe-area-top",
+          "valuesByMode": {
+            "global": "env(safe-area-inset-top, 0px)"
+          },
+          "$extensions": {
+            "com.ponchia.css": {
+              "variable": "--safe-area-top",
+              "value": "env(safe-area-inset-top, 0px)"
+            }
+          }
+        },
         {
           "name": "sans",
           "type": "STRING",
@@ -2025,6 +2081,34 @@
           },
           "unit": "rem"
         },
+        {
+          "name": "tap/target",
+          "type": "STRING",
+          "sourceCssVariable": "--tap-target",
+          "valuesByMode": {
+            "global": "max(44px, 2.9rem)"
+          },
+          "$extensions": {
+            "com.ponchia.css": {
+              "variable": "--tap-target",
+              "value": "max(44px, 2.9rem)"
+            }
+          }
+        },
+        {
+          "name": "tap/target/min",
+          "type": "STRING",
+          "sourceCssVariable": "--tap-target-min",
+          "valuesByMode": {
+            "global": "max(24px, 1.6rem)"
+          },
+          "$extensions": {
+            "com.ponchia.css": {
+              "variable": "--tap-target-min",
+              "value": "max(24px, 1.6rem)"
+            }
+          }
+        },
         {
           "name": "text/2xs",
           "type": "FLOAT",

package/tokens/index.d.ts

@@ -3,7 +3,7 @@
 
 export type ThemeName = 'light' | 'dark';
 
-export type GlobalTokenName = '--radius-xl' | '--radius-lg' | '--radius-md' | '--radius-sm' | '--radius-pill' | '--space-2xs' | '--space-xs' | '--space-sm' | '--space-md' | '--space-lg' | '--space-xl' | '--space-2xl' | '--mono' | '--sans' | '--dot-font' | '--display' | '--display-weight' | '--display-weight-strong' | '--text-2xs' | '--text-xs' | '--text-sm' | '--text-base' | '--text-lg' | '--text-xl' | '--tracking-wide' | '--tracking-wider' | '--ease-standard' | '--ease-spring' | '--ease-out' | '--duration-fast' | '--duration-base' | '--duration-slow' | '--dot-size' | '--dot-gap' | '--z-base' | '--z-raised' | '--z-sticky' | '--z-overlay' | '--z-popover' | '--z-toast' | '--accent-1' | '--accent-2' | '--accent-3' | '--accent-4' | '--accent-5' | '--accent-6' | '--surface-1' | '--surface-2' | '--surface-3' | '--surface-4' | '--surface-5' | '--surface-6' | '--bronto-color-bg' | '--bronto-color-surface' | '--bronto-color-surface-raised' | '--bronto-color-border' | '--bronto-color-border-strong' | '--bronto-color-text' | '--bronto-color-text-muted' | '--bronto-color-action' | '--bronto-color-on-action' | '--bronto-color-focus' | '--bronto-color-success' | '--bronto-color-warning' | '--bronto-color-danger' | '--bronto-color-info' | '--surface' | '--surface-raised' | '--surface-muted' | '--border' | '--border-strong';
+export type GlobalTokenName = '--radius-xl' | '--radius-lg' | '--radius-md' | '--radius-sm' | '--radius-pill' | '--space-2xs' | '--space-xs' | '--space-sm' | '--space-md' | '--space-lg' | '--space-xl' | '--space-2xl' | '--tap-target' | '--tap-target-min' | '--safe-area-top' | '--safe-area-right' | '--safe-area-bottom' | '--safe-area-left' | '--mono' | '--sans' | '--dot-font' | '--display' | '--display-weight' | '--display-weight-strong' | '--text-2xs' | '--text-xs' | '--text-sm' | '--text-base' | '--text-lg' | '--text-xl' | '--tracking-wide' | '--tracking-wider' | '--ease-standard' | '--ease-spring' | '--ease-out' | '--duration-fast' | '--duration-base' | '--duration-slow' | '--dot-size' | '--dot-gap' | '--z-base' | '--z-raised' | '--z-sticky' | '--z-overlay' | '--z-popover' | '--z-toast' | '--accent-1' | '--accent-2' | '--accent-3' | '--accent-4' | '--accent-5' | '--accent-6' | '--surface-1' | '--surface-2' | '--surface-3' | '--surface-4' | '--surface-5' | '--surface-6' | '--bronto-color-bg' | '--bronto-color-surface' | '--bronto-color-surface-raised' | '--bronto-color-border' | '--bronto-color-border-strong' | '--bronto-color-text' | '--bronto-color-text-muted' | '--bronto-color-action' | '--bronto-color-on-action' | '--bronto-color-focus' | '--bronto-color-success' | '--bronto-color-warning' | '--bronto-color-danger' | '--bronto-color-info' | '--surface' | '--surface-raised' | '--surface-muted' | '--border' | '--border-strong';
 export type LightTokenName = '--bg' | '--bg-elevated' | '--bg-accent' | '--panel' | '--panel-strong' | '--panel-soft' | '--line' | '--line-strong' | '--text' | '--text-soft' | '--text-dim' | '--accent' | '--accent-ramp-end' | '--accent-strong' | '--accent-text' | '--on-accent' | '--accent-soft' | '--success' | '--success-soft' | '--warning' | '--warning-soft' | '--danger' | '--danger-soft' | '--info' | '--info-soft' | '--code-bg' | '--button-text' | '--field-dot' | '--field-dot-hot' | '--field-dot-accent' | '--focus-ring' | '--shadow' | '--shadow-raised';
 export type DarkTokenName = '--bg' | '--bg-elevated' | '--bg-accent' | '--panel' | '--panel-strong' | '--panel-soft' | '--line' | '--line-strong' | '--text' | '--text-soft' | '--text-dim' | '--accent' | '--accent-ramp-end' | '--accent-strong' | '--accent-text' | '--on-accent' | '--accent-soft' | '--success' | '--success-soft' | '--warning' | '--warning-soft' | '--danger' | '--danger-soft' | '--info' | '--info-soft' | '--code-bg' | '--button-text' | '--field-dot' | '--field-dot-hot' | '--field-dot-accent' | '--focus-ring' | '--shadow' | '--shadow-raised';
 
@@ -14,7 +14,7 @@ export declare const cssVars: {
   dark: Record<DarkTokenName, string>;
 };
 
-export type ScaleKey = 'radius-xl' | 'radius-lg' | 'radius-md' | 'radius-sm' | 'radius-pill' | 'space-2xs' | 'space-xs' | 'space-sm' | 'space-md' | 'space-lg' | 'space-xl' | 'space-2xl' | 'mono' | 'sans' | 'dot-font' | 'display' | 'display-weight' | 'display-weight-strong' | 'text-2xs' | 'text-xs' | 'text-sm' | 'text-base' | 'text-lg' | 'text-xl' | 'tracking-wide' | 'tracking-wider' | 'ease-standard' | 'ease-spring' | 'ease-out' | 'duration-fast' | 'duration-base' | 'duration-slow' | 'dot-size' | 'dot-gap' | 'z-base' | 'z-raised' | 'z-sticky' | 'z-overlay' | 'z-popover' | 'z-toast' | 'accent-1' | 'accent-2' | 'accent-3' | 'accent-4' | 'accent-5' | 'accent-6' | 'surface-1' | 'surface-2' | 'surface-3' | 'surface-4' | 'surface-5' | 'surface-6' | 'bronto-color-bg' | 'bronto-color-surface' | 'bronto-color-surface-raised' | 'bronto-color-border' | 'bronto-color-border-strong' | 'bronto-color-text' | 'bronto-color-text-muted' | 'bronto-color-action' | 'bronto-color-on-action' | 'bronto-color-focus' | 'bronto-color-success' | 'bronto-color-warning' | 'bronto-color-danger' | 'bronto-color-info' | 'surface' | 'surface-raised' | 'surface-muted' | 'border' | 'border-strong';
+export type ScaleKey = 'radius-xl' | 'radius-lg' | 'radius-md' | 'radius-sm' | 'radius-pill' | 'space-2xs' | 'space-xs' | 'space-sm' | 'space-md' | 'space-lg' | 'space-xl' | 'space-2xl' | 'tap-target' | 'tap-target-min' | 'safe-area-top' | 'safe-area-right' | 'safe-area-bottom' | 'safe-area-left' | 'mono' | 'sans' | 'dot-font' | 'display' | 'display-weight' | 'display-weight-strong' | 'text-2xs' | 'text-xs' | 'text-sm' | 'text-base' | 'text-lg' | 'text-xl' | 'tracking-wide' | 'tracking-wider' | 'ease-standard' | 'ease-spring' | 'ease-out' | 'duration-fast' | 'duration-base' | 'duration-slow' | 'dot-size' | 'dot-gap' | 'z-base' | 'z-raised' | 'z-sticky' | 'z-overlay' | 'z-popover' | 'z-toast' | 'accent-1' | 'accent-2' | 'accent-3' | 'accent-4' | 'accent-5' | 'accent-6' | 'surface-1' | 'surface-2' | 'surface-3' | 'surface-4' | 'surface-5' | 'surface-6' | 'bronto-color-bg' | 'bronto-color-surface' | 'bronto-color-surface-raised' | 'bronto-color-border' | 'bronto-color-border-strong' | 'bronto-color-text' | 'bronto-color-text-muted' | 'bronto-color-action' | 'bronto-color-on-action' | 'bronto-color-focus' | 'bronto-color-success' | 'bronto-color-warning' | 'bronto-color-danger' | 'bronto-color-info' | 'surface' | 'surface-raised' | 'surface-muted' | 'border' | 'border-strong';
 export type ColorKey = 'bg' | 'bg-elevated' | 'bg-accent' | 'panel' | 'panel-strong' | 'panel-soft' | 'line' | 'line-strong' | 'text' | 'text-soft' | 'text-dim' | 'accent' | 'accent-ramp-end' | 'accent-strong' | 'accent-text' | 'on-accent' | 'accent-soft' | 'success' | 'success-soft' | 'warning' | 'warning-soft' | 'danger' | 'danger-soft' | 'info' | 'info-soft' | 'code-bg' | 'button-text' | 'field-dot' | 'field-dot-hot' | 'field-dot-accent' | 'focus-ring' | 'shadow' | 'shadow-raised';
 
 /** Ergonomic view derived from {@link cssVars} (`--` prefix stripped). */

package/tokens/index.js

@@ -33,6 +33,29 @@ export const cssVars = {
     '--space-lg': '1.35rem',
     '--space-xl': '1.75rem',
     '--space-2xl': '2.5rem',
+    // Tap targets. Both floors are clamped in px against the rem so they cannot
+    // shrink below the standard when a host re-points the root font size —
+    // Bronto's own base sets `html { font-size: 0.9375rem }`, under which a bare
+    // 2.9rem is 43.5px, half a pixel short of the target floor.
+    // `--tap-target` is the WCAG 2.5.5 (AAA) / iOS-HIG / Material 44px target
+    // every coarse-pointer control floats to. `--tap-target-min` is the WCAG
+    // 2.5.8 (AA) 24px minimum, for controls that only have to clear the smaller
+    // bar (standalone CTA links, disclosure carets).
+    '--tap-target': 'max(44px, 2.9rem)',
+    '--tap-target-min': 'max(24px, 1.6rem)',
+    // Display cutouts and system gesture areas. Every viewport-anchored surface
+    // Bronto ships — the app rail and topbar, a sticky site header, the skip
+    // link, the toast stacks, the drawer and the lightbox — reads these instead
+    // of calling env() at the point of use. The indirection is the point: env()
+    // cannot be emulated by a desktop browser runner, so routing every inset
+    // through an overrideable custom property is what makes full-bleed framing
+    // testable, and what lets a host running inside its own chrome (an embedded
+    // webview, a kiosk frame) declare the real insets. They resolve to 0px off
+    // a notched device, so every consuming rule is a no-op on desktop.
+    '--safe-area-top': 'env(safe-area-inset-top, 0px)',
+    '--safe-area-right': 'env(safe-area-inset-right, 0px)',
+    '--safe-area-bottom': 'env(safe-area-inset-bottom, 0px)',
+    '--safe-area-left': 'env(safe-area-inset-left, 0px)',
     '--mono': "'JetBrains Mono', 'Fira Code', 'Cascadia Code', 'SF Mono', ui-monospace, monospace",
     '--sans':
       "'Inter', 'SF Pro Text', -apple-system, BlinkMacSystemFont, 'Segoe UI', system-ui, sans-serif",

package/tokens/index.json

@@ -14,6 +14,12 @@
       "--space-lg": "1.35rem",
       "--space-xl": "1.75rem",
       "--space-2xl": "2.5rem",
+      "--tap-target": "max(44px, 2.9rem)",
+      "--tap-target-min": "max(24px, 1.6rem)",
+      "--safe-area-top": "env(safe-area-inset-top, 0px)",
+      "--safe-area-right": "env(safe-area-inset-right, 0px)",
+      "--safe-area-bottom": "env(safe-area-inset-bottom, 0px)",
+      "--safe-area-left": "env(safe-area-inset-left, 0px)",
       "--mono": "'JetBrains Mono', 'Fira Code', 'Cascadia Code', 'SF Mono', ui-monospace, monospace",
       "--sans": "'Inter', 'SF Pro Text', -apple-system, BlinkMacSystemFont, 'Segoe UI', system-ui, sans-serif",
       "--dot-font": "'Doto', var(--mono)",
@@ -159,6 +165,12 @@
       "space-lg": "1.35rem",
       "space-xl": "1.75rem",
       "space-2xl": "2.5rem",
+      "tap-target": "max(44px, 2.9rem)",
+      "tap-target-min": "max(24px, 1.6rem)",
+      "safe-area-top": "env(safe-area-inset-top, 0px)",
+      "safe-area-right": "env(safe-area-inset-right, 0px)",
+      "safe-area-bottom": "env(safe-area-inset-bottom, 0px)",
+      "safe-area-left": "env(safe-area-inset-left, 0px)",
       "mono": "'JetBrains Mono', 'Fira Code', 'Cascadia Code', 'SF Mono', ui-monospace, monospace",
       "sans": "'Inter', 'SF Pro Text', -apple-system, BlinkMacSystemFont, 'Segoe UI', system-ui, sans-serif",
       "dot-font": "'Doto', var(--mono)",

package/tokens/resolved.json

@@ -141,6 +141,12 @@
     "--space-lg": "1.35rem",
     "--space-xl": "1.75rem",
     "--space-2xl": "2.5rem",
+    "--tap-target": "max(44px, 2.9rem)",
+    "--tap-target-min": "max(24px, 1.6rem)",
+    "--safe-area-top": "env(safe-area-inset-top, 0px)",
+    "--safe-area-right": "env(safe-area-inset-right, 0px)",
+    "--safe-area-bottom": "env(safe-area-inset-bottom, 0px)",
+    "--safe-area-left": "env(safe-area-inset-left, 0px)",
     "--mono": "'JetBrains Mono', 'Fira Code', 'Cascadia Code', 'SF Mono', ui-monospace, monospace",
     "--sans": "'Inter', 'SF Pro Text', -apple-system, BlinkMacSystemFont, 'Segoe UI', system-ui, sans-serif",
     "--dot-font": "'Doto', 'JetBrains Mono', 'Fira Code', 'Cascadia Code', 'SF Mono', ui-monospace, monospace",