@ponchia/ui 0.7.0 → 0.8.0

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.0/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.0",
   "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": [

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",

package/tokens/skins.js

@@ -5,8 +5,26 @@
  * A skin is NOT a second brand colour — it *re-points the one accent* (and the
  * Tier-3 dot-matrix display knobs) to a different single hue, so the
  * one-accent-per-scope discipline holds while the palette gains creative range
- * *across* skins. The neutral canvas, status palette, and every component stay
- * exactly as they are.
+ * *across* skins. The status palette and every component stay exactly as they
+ * are.
+ *
+ * Since 0.8.0 a skin ALSO re-points the neutral canvas (ADR-0001 step 4,
+ * amended). Accent-only colorways were the original rule, and a downstream
+ * consumer proved it surprising in the worst way: a workspace offering these
+ * three as pickable looks found that "Amber CRT" left the surface grey, so it
+ * hand-wrote a full amber canvas in raw hex — dark theme only, outside OKLCH,
+ * outside the contrast gate, and with e-ink left un-tinted because nobody
+ * noticed it was missing. Shipping the canvas here makes it governed instead.
+ *
+ * THE NEUTRALS ARE DERIVED, NOT PICKED. Each one keeps the core token's OKLCH
+ * *lightness* exactly, adopts the skin accent's *hue*, and takes a small
+ * role-scaled chroma — surfaces least, lines most, text near-neutral so it
+ * never competes with the accent. Because WCAG contrast is a function of
+ * relative luminance, which OKLCH L tracks closely, holding L fixed means every
+ * gated pairing keeps essentially its core ratio: the colorway gains a canvas,
+ * not a contrast problem. `check-contrast.mjs` audits the FULL pairing table
+ * for any skin that moves the canvas — not just the accent subset — so that
+ * claim is proven on every run rather than asserted here.
  *
  * Accents are authored in **OKLCH** (ADR-0001 step 5 — "OKLCH for new work
  * first"): perceptually-uniform lightness makes the light/dark pair easy to
@@ -41,22 +59,68 @@ export const skins = {
     // bright with a warm bloom in dark theme (the classic CRT glow). The glow
     // and a deeper --pulse breath (`--dotmatrix-pulse-min`) are the Tier-3
     // "display expression" knobs the colorway is allowed to re-point.
-    light: { '--accent': 'oklch(52% 0.11 67deg)', '--dotmatrix-pulse-min': '0.35' },
+    light: {
+      '--accent': 'oklch(52% 0.11 67deg)',
+      '--dotmatrix-pulse-min': '0.35',
+      '--bg': 'oklch(96.66% 0.02 67deg)',
+      '--bg-elevated': 'oklch(98.781% 0.022 67deg)',
+      '--panel': 'oklch(100% 0.024 67deg)',
+      '--panel-strong': 'oklch(100% 0.026 67deg)',
+      '--panel-soft': 'oklch(94.253% 0.026 67deg)',
+      '--line': 'oklch(88.11% 0.035 67deg)',
+      '--line-strong': 'oklch(72.983% 0.04 67deg)',
+      '--text': 'oklch(14.479% 0.03 67deg)',
+      '--text-soft': 'oklch(32.825% 0.03 67deg)',
+      '--text-dim': 'oklch(51.571% 0.028 67deg)',
+    },
     dark: {
       '--accent': 'oklch(82% 0.15 82deg)',
       '--dotmatrix-glow': '0.4em',
       '--dotmatrix-pulse-min': '0.3',
+      '--bg': 'oklch(18.22% 0.02 82deg)',
+      '--bg-elevated': 'oklch(20.904% 0.022 82deg)',
+      '--panel': 'oklch(22.645% 0.024 82deg)',
+      '--panel-strong': 'oklch(25.196% 0.026 82deg)',
+      '--panel-soft': 'oklch(26.032% 0.026 82deg)',
+      '--line': 'oklch(34.07% 0.035 82deg)',
+      '--line-strong': 'oklch(44.953% 0.04 82deg)',
+      '--text': 'oklch(92.494% 0.03 82deg)',
+      '--text-soft': 'oklch(83.279% 0.03 82deg)',
+      '--text-dim': 'oklch(70.576% 0.028 82deg)',
     },
   },
   'phosphor-green': {
     label: 'Phosphor Green',
     // P1-phosphor green. Same light=dark-ink / dark=bright-glow split, with the
     // same deeper phosphor breath as Amber CRT.
-    light: { '--accent': 'oklch(52% 0.13 150deg)', '--dotmatrix-pulse-min': '0.35' },
+    light: {
+      '--accent': 'oklch(52% 0.13 150deg)',
+      '--dotmatrix-pulse-min': '0.35',
+      '--bg': 'oklch(96.66% 0.02 150deg)',
+      '--bg-elevated': 'oklch(98.781% 0.022 150deg)',
+      '--panel': 'oklch(100% 0.024 150deg)',
+      '--panel-strong': 'oklch(100% 0.026 150deg)',
+      '--panel-soft': 'oklch(94.253% 0.026 150deg)',
+      '--line': 'oklch(88.11% 0.035 150deg)',
+      '--line-strong': 'oklch(72.983% 0.04 150deg)',
+      '--text': 'oklch(14.479% 0.03 150deg)',
+      '--text-soft': 'oklch(32.825% 0.03 150deg)',
+      '--text-dim': 'oklch(51.571% 0.028 150deg)',
+    },
     dark: {
       '--accent': 'oklch(84% 0.19 150deg)',
       '--dotmatrix-glow': '0.4em',
       '--dotmatrix-pulse-min': '0.3',
+      '--bg': 'oklch(18.22% 0.02 150deg)',
+      '--bg-elevated': 'oklch(20.904% 0.022 150deg)',
+      '--panel': 'oklch(22.645% 0.024 150deg)',
+      '--panel-strong': 'oklch(25.196% 0.026 150deg)',
+      '--panel-soft': 'oklch(26.032% 0.026 150deg)',
+      '--line': 'oklch(34.07% 0.035 150deg)',
+      '--line-strong': 'oklch(44.953% 0.04 150deg)',
+      '--text': 'oklch(92.494% 0.03 150deg)',
+      '--text-soft': 'oklch(83.279% 0.03 150deg)',
+      '--text-dim': 'oklch(70.576% 0.028 150deg)',
     },
   },
   'e-ink': {
@@ -64,12 +128,58 @@ export const skins = {
     // The opposite move: drop the hue almost entirely → a near-monochrome
     // ink/paper accent, no glow. The most restrained look in the set — and the
     // --reveal scan snaps on instantly (`--dotmatrix-reveal-step: 0ms`), since
-    // e-ink panels don't sweep, they flip.
-    light: { '--accent': 'oklch(34% 0.012 250deg)', '--dotmatrix-reveal-step': '0ms' },
-    dark: { '--accent': 'oklch(84% 0.008 250deg)', '--dotmatrix-reveal-step': '0ms' },
+    // e-ink panels don't sweep, they flip. Its canvas takes a QUARTER of the
+    // chroma the other two do, for the same reason: near-monochrome is the
+    // whole point, so the tint should be felt rather than seen.
+    light: {
+      '--accent': 'oklch(34% 0.012 250deg)',
+      '--dotmatrix-reveal-step': '0ms',
+      '--bg': 'oklch(96.66% 0.005 250deg)',
+      '--bg-elevated': 'oklch(98.781% 0.006 250deg)',
+      '--panel': 'oklch(100% 0.006 250deg)',
+      '--panel-strong': 'oklch(100% 0.007 250deg)',
+      '--panel-soft': 'oklch(94.253% 0.007 250deg)',
+      '--line': 'oklch(88.11% 0.009 250deg)',
+      '--line-strong': 'oklch(72.983% 0.01 250deg)',
+      '--text': 'oklch(14.479% 0.008 250deg)',
+      '--text-soft': 'oklch(32.825% 0.008 250deg)',
+      '--text-dim': 'oklch(51.571% 0.007 250deg)',
+    },
+    dark: {
+      '--accent': 'oklch(84% 0.008 250deg)',
+      '--dotmatrix-reveal-step': '0ms',
+      '--bg': 'oklch(18.22% 0.005 250deg)',
+      '--bg-elevated': 'oklch(20.904% 0.006 250deg)',
+      '--panel': 'oklch(22.645% 0.006 250deg)',
+      '--panel-strong': 'oklch(25.196% 0.007 250deg)',
+      '--panel-soft': 'oklch(26.032% 0.007 250deg)',
+      '--line': 'oklch(34.07% 0.009 250deg)',
+      '--line-strong': 'oklch(44.953% 0.01 250deg)',
+      '--text': 'oklch(92.494% 0.008 250deg)',
+      '--text-soft': 'oklch(83.279% 0.008 250deg)',
+      '--text-dim': 'oklch(70.576% 0.007 250deg)',
+    },
   },
 };
 
+/** The canvas tokens a colorway may re-point (ADR-0001 step 4, amended). Status
+ *  colours are deliberately NOT here: a warning must look like a warning in
+ *  every skin. The gates read this — check-skins allows these keys, and
+ *  gen-contrast widens a skin's audit to the full pairing table when any of
+ *  them is set. */
+export const SKIN_CANVAS_TOKENS = Object.freeze([
+  '--bg',
+  '--bg-elevated',
+  '--panel',
+  '--panel-strong',
+  '--panel-soft',
+  '--line',
+  '--line-strong',
+  '--text',
+  '--text-soft',
+  '--text-dim',
+]);
+
 /** Skin names, frozen + sorted. */
 export const SKIN_NAMES = Object.freeze(Object.keys(skins).sort());
 

package/tokens/tokens.dtcg.json

@@ -10,7 +10,13 @@
         "--tracking-wide",
         "--tracking-wider",
         "--shadow",
-        "--shadow-raised"
+        "--shadow-raised",
+        "--tap-target",
+        "--tap-target-min",
+        "--safe-area-top",
+        "--safe-area-right",
+        "--safe-area-bottom",
+        "--safe-area-left"
       ]
     }
   },