@ponchia/ui 0.7.0 → 0.8.0

package/CHANGELOG.md

@@ -5,6 +5,139 @@
 |> `^0` / `*` wildcard does **not** protect you. See README → Versioning, and
 |> the deprecation policy in CONTRIBUTING.md.
 
+## 0.8.0 — 2026-08-11
+
+A single-consumer release. A full-surface audit of the largest downstream
+consumer — a Yjs-collaborative spatial canvas workspace with roughly ten
+thousand lines of its own CSS — found it using 26 of the 646 published classes
+and hand-rebuilding much of the rest. Everything here comes from what that
+consumer had to write because the framework did not provide it, or got wrong.
+
+### BREAKING
+
+- **A colorway now re-points the neutral canvas, so every skinned surface
+  changes appearance.** No class, token, attribute, or export was removed or
+  renamed, and `bronto-ui-check` will report nothing — the break is *visual*,
+  which is why it is called out here rather than left in Changed. Until 0.7,
+  `data-bronto-skin` moved `--accent` and nothing else, and ADR-0001 step 4 said
+  so explicitly; a consumer could reasonably have relied on the canvas staying
+  neutral. From 0.8 the ten `SKIN_CANVAS_TOKENS` (`--bg`, `--bg-elevated`,
+  `--panel`, `--panel-strong`, `--panel-soft`, `--line`, `--line-strong`,
+  `--text`, `--text-soft`, `--text-dim`) are re-pointed per skin per theme.
+  - **If you want the old look**, re-declare those ten tokens after the skin
+    import; they are ordinary custom properties on `:root[data-bronto-skin=…]`
+    and un-layered app CSS wins.
+  - **If you already hand-wrote a canvas** for a skin — the case this change
+    exists to serve — delete it and check the result; yours was almost certainly
+    not contrast-gated, and this one is.
+  - **Contrast is not a regression risk.** Each neutral keeps the core token's
+    OKLCH lightness exactly, and `check-contrast` re-measures all 21 gated
+    pairings per skin per theme. Status colours are untouched by design.
+
+### Fixed
+
+- **The coarse-pointer tap target was 43.5px, not 44px.** The floor was written
+  as a bare `2.9rem` at 23 sites across 8 stylesheets, and `css/base.css` sets
+  `html { font-size: 0.9375rem }` — so every control the framework floats on
+  touch landed half a pixel under WCAG 2.5.5 and both platform HIGs, and drifted
+  further under any host that shrank the root. Several comments asserted
+  "≈ 44px". Both floors are now published tokens clamped in px
+  (`--tap-target: max(44px, 2.9rem)`, `--tap-target-min: max(24px, 1.6rem)`) —
+  the same `max()` shape the 24px floor already used correctly in five places.
+  The e2e that should have caught this was derived from the token (`2.9 * rem`),
+  so it agreed with the bug; it now asserts the external 44px standard, and a
+  unit gate walks every `@media (pointer: coarse)` block and fails on any floor
+  written as a bare length. That gate immediately found one more:
+  `.ui-table__sort`.
+
+### Added
+
+- **`.ui-button__label`** — the label slot for icon buttons. Wrap a button's
+  text in it and `--icon` decides whether the words are painted; they stay in
+  the accessible name and in text-based test selectors either way. One markup
+  shape serves both the labelled and icon-only forms, and no `aria-label` can
+  drift out of sync with the visible wording. The slot also ellipsises rather
+  than wrapping, so a labelled button in a tight bar shrinks instead of pushing
+  its neighbours out. `ui.button()` is unchanged; `cls.buttonLabel` is new.
+- **`.ui-button--dense`** — a size tier 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 `--tap-target-min`; the coarse-pointer block
+  still floats it to the full `--tap-target`, so a control shrunk for a mouse is
+  never shrunk for a finger. `ui.button({ size: 'dense' })`.
+- **A canonical severity ladder** (`css/state.css`, opt-in). Bronto shipped the
+  *tones* long ago but never the *scale* — the tier names, their order, and the
+  attribute carrying them — so every consumer invented the ladder and it drifted
+  inside a single app: one surface saying `critical|error|warning|note`, the
+  next `bad|warn`, a third `critical|warning|info|ok`, under two different
+  attribute names, so findings did not sort against alerts. The ladder is
+  `critical` › `error` › `warning` › `notice` › `ok`, carried on **one**
+  attribute (`data-level`) across `.ui-severity`, `.ui-severity-dot` and
+  `.ui-severity-row`, with `SEVERITY_LEVELS` and `severity()` exported so a host
+  drives filters and sorts from the same list the CSS paints. `unknown` sits
+  deliberately *outside* the ordering: it means "not measured", and collapsing
+  it into `ok` is how a dead collector reads as a healthy system.
+- **`.ui-pane`** (`css/workbench.css`, opt-in) — the window that `.ui-panel`
+  (a padded card) and `.ui-inspector` (head plus body) are not: a grab header,
+  a title that renames in place via `__title-input` without moving layout, and
+  an `__actions` slot that **scrolls rather than pushing** its last control past
+  the pane's clipped edge — the failure that leaves a Focus or Disconnect button
+  present, in the a11y tree, and unreachable.
+- **`.ui-toolstrip--pane`** — the app has one toolstrip; a workbench full of
+  panes has one *per pane*, and those need different framing (no frame of their
+  own, a rule against the content below) and must not wrap, since a second row
+  would resize live content on every state change. `.ui-toolstrip__fill` marks
+  the element that absorbs slack and gives it back first.
+- **`--anchored` / `--anchor-block-start` / `--anchor-block-end`** on
+  `.ui-selectionbar` and `.ui-toolstrip`. Both `--floating` bars were raised but
+  position-less, so every consumer re-derived the placement — including the
+  `max(offset, inset)` shape that keeps a bar out from under the home indicator.
+- **Empty-state slots and an invite variant.** `.ui-empty-state` was a dashed
+  box that styled a `<p>`, so every empty surface in an app re-invented the same
+  three parts under a different name and they drifted. `__glyph` / `__lead` /
+  `__hint` name them, and `--invite` is the different job: an empty state
+  *reports absence*, an invite *offers the next action*, so it drops the dashed
+  frame and centres in the space it is given.
+- **Safe-area tokens** — `--safe-area-top / -right / -bottom / -left`, defaulting
+  to `env(safe-area-inset-*, 0px)`. The framework had **no** `env()` awareness
+  while shipping eight viewport-anchored surfaces; all eight now read them: the
+  app rail and topbar, a sticky site header, the skip link, both toast stacks,
+  the drawer modal and the lightbox. Every rule uses
+  `max(<authored>, var(--safe-area-*))`, so desktop rendering is unchanged. The
+  values are indirected through custom properties rather than called at the
+  point of use because `env()` cannot be emulated by a desktop test runner —
+  and because a host inside its own chrome (embedded webview, kiosk frame) needs
+  to declare the real insets.
+
+### Changed
+
+- **ADR-0001 step 4 amended** to permit the canvas re-point above (see
+  BREAKING). "Amber CRT" used to leave the surface grey, which is what drove the
+  consumer to hand-write an amber canvas in raw hex — dark theme only, outside
+  OKLCH, outside the contrast gate, with `e-ink` silently un-tinted. The canvas
+  is **derived rather than picked**: every neutral keeps the core token's OKLCH
+  *lightness* exactly and moves only hue and a small role-scaled chroma.
+  `check-skins` now rejects a partial canvas and a one-theme-only canvas, the
+  two shapes the hand-written version had.
+- **`check:recipe-types` no longer mis-attributes options.** It sliced the
+  factory body to end-of-file, so the *last* recipe's chunk swallowed everything
+  declared after the `ui` object — an unrelated helper exported below it had its
+  string branches blamed on whichever recipe happened to be last. It now stops
+  at the object's own closing brace.
+- `docs/stability.md` records the audit and the correction it forces on this
+  project's adoption model: "no inspected consumer imports the surface" has been
+  measuring **discoverability, not demand**. Those thirteen zero-use primitives
+  were never rejected; they were never found. Non-adoption of a leaf the
+  consumer never imported is not evidence for retiring it at 1.0.
+
+### Notes
+
+- Anything that reads `tokens.dtcg.json` should know that six new scale tokens
+  are **deliberately absent** from it, listed in the root extension's
+  `omittedCssVariables`: the two tap-target floors are `max()` comparisons and
+  the four safe-area insets are `env()` reads, neither of which has a conforming
+  DTCG shape. `tokens.json` carries the authored CSS. This is the same treatment
+  `--shadow` and the em trackings already get.
+
 ## 0.7.0 — 2026-07-20
 
 A consumer-first contract-hardening release. Ten real applications and tools,

package/README.md

@@ -3,7 +3,7 @@
 [![npm](https://img.shields.io/npm/v/@ponchia/ui?logo=npm)](https://www.npmjs.com/package/@ponchia/ui)
 [![npm provenance](https://img.shields.io/badge/npm-provenance-blue?logo=npm)](https://www.npmjs.com/package/@ponchia/ui#provenance)
 [![runtime deps](https://img.shields.io/badge/runtime%20deps-0-brightgreen)](https://github.com/Ponchia/bronto-ui/blob/main/package.json)
-[![default CSS](https://img.shields.io/badge/default%20CSS-~90kB%20%2F%20~15kB%20gzip-informational)](https://github.com/Ponchia/bronto-ui/blob/main/scripts/check-dist.mjs)
+[![default CSS](https://img.shields.io/badge/default%20CSS-~92kB%20%2F%20~16kB%20gzip-informational)](https://github.com/Ponchia/bronto-ui/blob/main/scripts/check-dist.mjs)
 [![CI](https://github.com/Ponchia/bronto-ui/actions/workflows/ci.yml/badge.svg)](https://github.com/Ponchia/bronto-ui/actions/workflows/ci.yml)
 [![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/Ponchia/bronto-ui/badge)](https://scorecard.dev/viewer/?uri=github.com/Ponchia/bronto-ui)
 [![license: MIT](https://img.shields.io/badge/license-MIT-blue)](https://github.com/Ponchia/bronto-ui/blob/main/LICENSE)
@@ -81,12 +81,12 @@ Or drop it in with no build step, straight from a CDN (replace the version only
 when deliberately upgrading across a breaking pre-1.0 minor):
 
 ```html
-<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui@0.7.0/dist/bronto.css">
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui@0.8.0/dist/bronto.css">
 ```
 
 ## Quick start
 
-**1. Load the CSS.** One flattened, minified default CSS bundle — the standard component set, one request (~90 kB raw / ~15 kB gzip) — that is `dist/bronto.css`, not the whole package tarball:
+**1. Load the CSS.** One flattened, minified default CSS bundle — the standard component set, one request (~92 kB raw / ~16 kB gzip) — that is `dist/bronto.css`, not the whole package tarball:
 
 ```css
 @import '@ponchia/ui';            /* via a bundler */

package/classes/classes.json

@@ -1,8 +1,8 @@
 {
   "$comment": "@ponchia/ui class vocabulary as language-neutral data — validate emitted markup without executing the ESM cls map or parsing the .d.ts. Generated from classes/index.js — do not edit by hand; run `npm run classes:json:build`. Drift-checked in CI. `groups[].base` is null for a parts-only namespace (no standalone base class — do NOT emit it). A modifier whose name contains `__` (e.g. `ui-spark__bar--pos`) attaches to THAT part, not the base host. `states` is the author-applied `is-*` hooks (runtime/behavior-managed hooks are excluded); `behaviorAttributes` are the `data-bronto-*` wiring hooks the optional behaviors delegate on; `requiredAria` is the role/aria a generator must emit per component. `states` + `customProperties` are documented in docs/reference.md and ship outside `cls` by design.",
   "counts": {
-    "classes": 644,
-    "groups": 179
+    "classes": 669,
+    "groups": 183
   },
   "groups": {
     "ui-accordion": {
@@ -242,13 +242,16 @@
       "base": "ui-button",
       "modifiers": [
         "ui-button--danger",
+        "ui-button--dense",
         "ui-button--ghost",
         "ui-button--icon",
         "ui-button--lg",
         "ui-button--sm",
         "ui-button--subtle"
       ],
-      "parts": []
+      "parts": [
+        "ui-button__label"
+      ]
     },
     "ui-card": {
       "base": "ui-card",
@@ -545,8 +548,14 @@
     },
     "ui-empty-state": {
       "base": "ui-empty-state",
-      "modifiers": [],
-      "parts": []
+      "modifiers": [
+        "ui-empty-state--invite"
+      ],
+      "parts": [
+        "ui-empty-state__glyph",
+        "ui-empty-state__hint",
+        "ui-empty-state__lead"
+      ]
     },
     "ui-error-summary": {
       "base": "ui-error-summary",
@@ -910,6 +919,17 @@
         "ui-pagination__item"
       ]
     },
+    "ui-pane": {
+      "base": "ui-pane",
+      "modifiers": [],
+      "parts": [
+        "ui-pane__actions",
+        "ui-pane__body",
+        "ui-pane__head",
+        "ui-pane__title",
+        "ui-pane__title-input"
+      ]
+    },
     "ui-panel": {
       "base": "ui-panel",
       "modifiers": [],
@@ -1104,12 +1124,34 @@
     },
     "ui-selectionbar": {
       "base": "ui-selectionbar",
-      "modifiers": [],
+      "modifiers": [
+        "ui-selectionbar--anchor-block-end",
+        "ui-selectionbar--anchor-block-start",
+        "ui-selectionbar--anchored"
+      ],
       "parts": [
         "ui-selectionbar__actions",
         "ui-selectionbar__count"
       ]
     },
+    "ui-severity": {
+      "base": "ui-severity",
+      "modifiers": [],
+      "parts": []
+    },
+    "ui-severity-dot": {
+      "base": "ui-severity-dot",
+      "modifiers": [],
+      "parts": []
+    },
+    "ui-severity-row": {
+      "base": "ui-severity-row",
+      "modifiers": [],
+      "parts": [
+        "ui-severity-row__meta",
+        "ui-severity-row__title"
+      ]
+    },
     "ui-shortcut": {
       "base": "ui-shortcut",
       "modifiers": [],
@@ -1447,13 +1489,18 @@
     "ui-toolstrip": {
       "base": "ui-toolstrip",
       "modifiers": [
+        "ui-toolstrip--anchor-block-end",
+        "ui-toolstrip--anchor-block-start",
+        "ui-toolstrip--anchored",
         "ui-toolstrip--compact",
-        "ui-toolstrip--floating"
+        "ui-toolstrip--floating",
+        "ui-toolstrip--pane"
       ],
       "parts": [
         "ui-toolstrip__actions",
         "ui-toolstrip__brand",
         "ui-toolstrip__context",
+        "ui-toolstrip__fill",
         "ui-toolstrip__group",
         "ui-toolstrip__search"
       ]
@@ -1610,11 +1657,13 @@
     "ui-bullet__target",
     "ui-button",
     "ui-button--danger",
+    "ui-button--dense",
     "ui-button--ghost",
     "ui-button--icon",
     "ui-button--lg",
     "ui-button--sm",
     "ui-button--subtle",
+    "ui-button__label",
     "ui-card",
     "ui-card--accent",
     "ui-card--interactive",
@@ -1748,6 +1797,10 @@
     "ui-dotspinner--lg",
     "ui-dotspinner--sm",
     "ui-empty-state",
+    "ui-empty-state--invite",
+    "ui-empty-state__glyph",
+    "ui-empty-state__hint",
+    "ui-empty-state__lead",
     "ui-error-summary",
     "ui-error-summary__list",
     "ui-error-summary__title",
@@ -1907,6 +1960,12 @@
     "ui-pagehead__title",
     "ui-pagination",
     "ui-pagination__item",
+    "ui-pane",
+    "ui-pane__actions",
+    "ui-pane__body",
+    "ui-pane__head",
+    "ui-pane__title",
+    "ui-pane__title-input",
     "ui-panel",
     "ui-panel__head",
     "ui-popover",
@@ -1994,8 +2053,16 @@
     "ui-sel--on",
     "ui-select",
     "ui-selectionbar",
+    "ui-selectionbar--anchor-block-end",
+    "ui-selectionbar--anchor-block-start",
+    "ui-selectionbar--anchored",
     "ui-selectionbar__actions",
     "ui-selectionbar__count",
+    "ui-severity",
+    "ui-severity-dot",
+    "ui-severity-row",
+    "ui-severity-row__meta",
+    "ui-severity-row__title",
     "ui-shortcut",
     "ui-shortcut__sep",
     "ui-sidebar",
@@ -2124,11 +2191,16 @@
     "ui-tool-call__status",
     "ui-tool-log",
     "ui-toolstrip",
+    "ui-toolstrip--anchor-block-end",
+    "ui-toolstrip--anchor-block-start",
+    "ui-toolstrip--anchored",
     "ui-toolstrip--compact",
     "ui-toolstrip--floating",
+    "ui-toolstrip--pane",
     "ui-toolstrip__actions",
     "ui-toolstrip__brand",
     "ui-toolstrip__context",
+    "ui-toolstrip__fill",
     "ui-toolstrip__group",
     "ui-toolstrip__search",
     "ui-tooltip",

package/classes/index.d.ts

@@ -21,6 +21,8 @@ export declare const cls: {
   readonly buttonIcon: 'ui-button--icon';
   readonly buttonSm: 'ui-button--sm';
   readonly buttonLg: 'ui-button--lg';
+  readonly buttonDense: 'ui-button--dense';
+  readonly buttonLabel: 'ui-button__label';
   readonly card: 'ui-card';
   readonly cardHead: 'ui-card__head';
   readonly cardAccent: 'ui-card--accent';
@@ -54,6 +56,10 @@ export declare const cls: {
   readonly linkCta: 'ui-link--cta';
   readonly keyValue: 'ui-key-value';
   readonly emptyState: 'ui-empty-state';
+  readonly emptyStateInvite: 'ui-empty-state--invite';
+  readonly emptyStateGlyph: 'ui-empty-state__glyph';
+  readonly emptyStateLead: 'ui-empty-state__lead';
+  readonly emptyStateHint: 'ui-empty-state__hint';
   readonly dot: 'ui-dot';
   readonly dotAccent: 'ui-dot--accent';
   readonly dotSuccess: 'ui-dot--success';
@@ -560,6 +566,11 @@ export declare const cls: {
   readonly jobBlocked: 'ui-job--blocked';
   readonly jobFailed: 'ui-job--failed';
   readonly jobComplete: 'ui-job--complete';
+  readonly severity: 'ui-severity';
+  readonly severityDot: 'ui-severity-dot';
+  readonly severityRow: 'ui-severity-row';
+  readonly severityRowTitle: 'ui-severity-row__title';
+  readonly severityRowMeta: 'ui-severity-row__meta';
   readonly generated: 'ui-generated';
   readonly generatedLabel: 'ui-generated__label';
   readonly originLabel: 'ui-origin-label';
@@ -577,11 +588,22 @@ export declare const cls: {
   readonly toolstrip: 'ui-toolstrip';
   readonly toolstripFloating: 'ui-toolstrip--floating';
   readonly toolstripCompact: 'ui-toolstrip--compact';
+  readonly toolstripPane: 'ui-toolstrip--pane';
+  readonly toolstripAnchored: 'ui-toolstrip--anchored';
+  readonly toolstripAnchorBlockStart: 'ui-toolstrip--anchor-block-start';
+  readonly toolstripAnchorBlockEnd: 'ui-toolstrip--anchor-block-end';
   readonly toolstripBrand: 'ui-toolstrip__brand';
   readonly toolstripContext: 'ui-toolstrip__context';
   readonly toolstripGroup: 'ui-toolstrip__group';
   readonly toolstripActions: 'ui-toolstrip__actions';
+  readonly toolstripFill: 'ui-toolstrip__fill';
   readonly toolstripSearch: 'ui-toolstrip__search';
+  readonly pane: 'ui-pane';
+  readonly paneHead: 'ui-pane__head';
+  readonly paneTitle: 'ui-pane__title';
+  readonly paneTitleInput: 'ui-pane__title-input';
+  readonly paneActions: 'ui-pane__actions';
+  readonly paneBody: 'ui-pane__body';
   readonly segmentedButtons: 'ui-segmented-buttons';
   readonly segmentedButtonsButton: 'ui-segmented-buttons__button';
   readonly property: 'ui-property';
@@ -590,6 +612,9 @@ export declare const cls: {
   readonly selectionbar: 'ui-selectionbar';
   readonly selectionbarCount: 'ui-selectionbar__count';
   readonly selectionbarActions: 'ui-selectionbar__actions';
+  readonly selectionbarAnchored: 'ui-selectionbar--anchored';
+  readonly selectionbarAnchorBlockStart: 'ui-selectionbar--anchor-block-start';
+  readonly selectionbarAnchorBlockEnd: 'ui-selectionbar--anchor-block-end';
   readonly splitter: 'ui-splitter';
   readonly splitterVertical: 'ui-splitter--vertical';
   readonly splitterHorizontal: 'ui-splitter--horizontal';
@@ -666,7 +691,17 @@ export declare function cx(...parts: readonly ClassValue[]): string;
 export interface ButtonOpts {
   variant?: 'ghost' | 'subtle' | 'danger';
   icon?: boolean;
-  size?: 'sm' | 'lg';
+  size?: 'sm' | 'lg' | 'dense';
+}
+export interface EmptyStateOpts {
+  invite?: boolean;
+}
+export interface ToolstripOpts {
+  variant?: 'floating' | 'compact' | 'pane';
+  anchor?: 'block-start' | 'block-end';
+}
+export interface SelectionbarOpts {
+  anchor?: 'block-start' | 'block-end';
 }
 export interface CardOpts {
   accent?: boolean;
@@ -952,11 +987,28 @@ export interface Ui {
   state(opts?: StateOpts): string;
   job(opts?: JobOpts): string;
   originLabel(opts?: OriginLabelOpts): string;
+  emptyState(opts?: EmptyStateOpts): string;
+  toolstrip(opts?: ToolstripOpts): string;
+  selectionbar(opts?: SelectionbarOpts): string;
 }
 
 export declare const ui: Ui;
 export default ui;
 
+/** The canonical severity ladder, worst to best. `unknown` is deliberately not
+ *  a member: it means "not measured", not "nearly ok". */
+export declare const SEVERITY_LEVELS: readonly ['critical', 'error', 'warning', 'notice', 'ok'];
+
+export type SeverityLevel = (typeof SEVERITY_LEVELS)[number];
+
+/** Bundles `data-level` with the severity class so the attribute that carries
+ *  the meaning cannot be forgotten. An unrecognised level resolves to
+ *  `'unknown'`, which paints the neutral tone. */
+export declare function severity(
+  level: SeverityLevel | (string & {}) | null | undefined,
+  opts?: { part?: 'chip' | 'dot' | 'row' },
+): { class: string; 'data-level': string };
+
 /** Min/max for the value-bearing fills; defaults to 0–100. */
 export interface ValueRangeOpts {
   min?: number;

package/classes/index.js

@@ -25,6 +25,8 @@ export const cls = Object.freeze({
   buttonIcon: 'ui-button--icon',
   buttonSm: 'ui-button--sm',
   buttonLg: 'ui-button--lg',
+  buttonDense: 'ui-button--dense',
+  buttonLabel: 'ui-button__label',
   card: 'ui-card',
   cardHead: 'ui-card__head',
   cardAccent: 'ui-card--accent',
@@ -58,6 +60,10 @@ export const cls = Object.freeze({
   linkCta: 'ui-link--cta',
   keyValue: 'ui-key-value',
   emptyState: 'ui-empty-state',
+  emptyStateInvite: 'ui-empty-state--invite',
+  emptyStateGlyph: 'ui-empty-state__glyph',
+  emptyStateLead: 'ui-empty-state__lead',
+  emptyStateHint: 'ui-empty-state__hint',
   // dots
   dot: 'ui-dot',
   dotAccent: 'ui-dot--accent',
@@ -597,6 +603,12 @@ export const cls = Object.freeze({
   jobBlocked: 'ui-job--blocked',
   jobFailed: 'ui-job--failed',
   jobComplete: 'ui-job--complete',
+  // severity ladder — the second axis of state (css/state.css)
+  severity: 'ui-severity',
+  severityDot: 'ui-severity-dot',
+  severityRow: 'ui-severity-row',
+  severityRowTitle: 'ui-severity-row__title',
+  severityRowMeta: 'ui-severity-row__meta',
   // generated content / AI-trust surfaces (css/generated.css)
   generated: 'ui-generated',
   generatedLabel: 'ui-generated__label',
@@ -616,11 +628,22 @@ export const cls = Object.freeze({
   toolstrip: 'ui-toolstrip',
   toolstripFloating: 'ui-toolstrip--floating',
   toolstripCompact: 'ui-toolstrip--compact',
+  toolstripPane: 'ui-toolstrip--pane',
+  toolstripAnchored: 'ui-toolstrip--anchored',
+  toolstripAnchorBlockStart: 'ui-toolstrip--anchor-block-start',
+  toolstripAnchorBlockEnd: 'ui-toolstrip--anchor-block-end',
   toolstripBrand: 'ui-toolstrip__brand',
   toolstripContext: 'ui-toolstrip__context',
   toolstripGroup: 'ui-toolstrip__group',
   toolstripActions: 'ui-toolstrip__actions',
+  toolstripFill: 'ui-toolstrip__fill',
   toolstripSearch: 'ui-toolstrip__search',
+  pane: 'ui-pane',
+  paneHead: 'ui-pane__head',
+  paneTitle: 'ui-pane__title',
+  paneTitleInput: 'ui-pane__title-input',
+  paneActions: 'ui-pane__actions',
+  paneBody: 'ui-pane__body',
   segmentedButtons: 'ui-segmented-buttons',
   segmentedButtonsButton: 'ui-segmented-buttons__button',
   property: 'ui-property',
@@ -629,6 +652,9 @@ export const cls = Object.freeze({
   selectionbar: 'ui-selectionbar',
   selectionbarCount: 'ui-selectionbar__count',
   selectionbarActions: 'ui-selectionbar__actions',
+  selectionbarAnchored: 'ui-selectionbar--anchored',
+  selectionbarAnchorBlockStart: 'ui-selectionbar--anchor-block-start',
+  selectionbarAnchorBlockEnd: 'ui-selectionbar--anchor-block-end',
   splitter: 'ui-splitter',
   splitterVertical: 'ui-splitter--vertical',
   splitterHorizontal: 'ui-splitter--horizontal',
@@ -934,6 +960,7 @@ export const ui = {
       icon && cls.buttonIcon,
       size === 'sm' && cls.buttonSm,
       size === 'lg' && cls.buttonLg,
+      size === 'dense' && cls.buttonDense,
     ),
   card: ({ accent, interactive } = {}) =>
     j(cls.card, accent && cls.cardAccent, interactive && cls.cardInteractive),
@@ -1092,8 +1119,41 @@ export const ui = {
   state: ({ state, busy } = {}) => j(cls.state, stateTone(state), busy && cls.stateBusy),
   job: ({ state, compact } = {}) => j(cls.job, jobTone(state), compact && cls.jobCompact),
   originLabel: ({ ai } = {}) => j(cls.originLabel, ai && cls.originLabelAi),
+  emptyState: ({ invite } = {}) => j(cls.emptyState, invite && cls.emptyStateInvite),
+  toolstrip: ({ variant, anchor } = {}) =>
+    j(
+      cls.toolstrip,
+      variant === 'floating' && cls.toolstripFloating,
+      variant === 'compact' && cls.toolstripCompact,
+      variant === 'pane' && cls.toolstripPane,
+      anchor && cls.toolstripAnchored,
+      anchor === 'block-start' && cls.toolstripAnchorBlockStart,
+      anchor === 'block-end' && cls.toolstripAnchorBlockEnd,
+    ),
+  selectionbar: ({ anchor } = {}) =>
+    j(
+      cls.selectionbar,
+      anchor && cls.selectionbarAnchored,
+      anchor === 'block-start' && cls.selectionbarAnchorBlockStart,
+      anchor === 'block-end' && cls.selectionbarAnchorBlockEnd,
+    ),
 };
 
+/** The canonical severity ladder, worst to best. `unknown` is deliberately NOT
+ *  in the ordering — it means "not measured", not "nearly ok", and sorting it
+ *  next to `ok` is how a dead collector reads as a healthy system. Exported as
+ *  data so a host can drive filters and sorts from the same list the CSS
+ *  paints, instead of re-typing the tiers. */
+export const SEVERITY_LEVELS = Object.freeze(['critical', 'error', 'warning', 'notice', 'ok']);
+
+/** `data-level` + the severity class, bundled so the attribute that carries the
+ *  meaning cannot be forgotten — the class alone paints the neutral tone and
+ *  silently loses the level. Unknown/absent levels resolve to `unknown`. */
+export const severity = (level, { part = 'chip' } = {}) => ({
+  class: part === 'dot' ? cls.severityDot : part === 'row' ? cls.severityRow : cls.severity,
+  'data-level': SEVERITY_LEVELS.includes(level) ? level : 'unknown',
+});
+
 // Attribute + style bundle for the data-bearing fills (`ui-meter`/`ui-progress`).
 // The class string alone paints a 0-width, unannounced bar: the fill width is a
 // UNITLESS `--value` (0–100) and AT needs role + aria-valuenow/min/max. This sets

package/classes/vscode.css-custom-data.json

@@ -257,6 +257,22 @@
       "name": "--radius-xl",
       "description": "Global scale token. Value: `4px`"
     },
+    {
+      "name": "--safe-area-bottom",
+      "description": "Global scale token. Value: `env(safe-area-inset-bottom, 0px)`"
+    },
+    {
+      "name": "--safe-area-left",
+      "description": "Global scale token. Value: `env(safe-area-inset-left, 0px)`"
+    },
+    {
+      "name": "--safe-area-right",
+      "description": "Global scale token. Value: `env(safe-area-inset-right, 0px)`"
+    },
+    {
+      "name": "--safe-area-top",
+      "description": "Global scale token. Value: `env(safe-area-inset-top, 0px)`"
+    },
     {
       "name": "--sans",
       "description": "Global scale token. Value: `'Inter', 'SF Pro Text', -apple-system, BlinkMacSystemFont, 'Segoe UI', system-ui, sans-serif`"
@@ -341,6 +357,14 @@
       "name": "--surface-raised",
       "description": "Global scale token. Value: `var(--panel-strong)`"
     },
+    {
+      "name": "--tap-target",
+      "description": "Global scale token. Value: `max(44px, 2.9rem)`"
+    },
+    {
+      "name": "--tap-target-min",
+      "description": "Global scale token. Value: `max(24px, 1.6rem)`"
+    },
     {
       "name": "--text",
       "description": "Theme token. Light: `#0a0a0a` · Dark: `#e6e6e6`"

package/css/app.css

@@ -21,7 +21,15 @@
   display: flex;
   flex-direction: column;
   gap: var(--space-md);
-  padding: var(--space-md);
+
+  /* The rail runs the full viewport height, so on a notched device its top and
+     bottom sit under the status bar and the home indicator. Grow the padding to
+     clear them; `max()` keeps the desktop value exactly as authored, since the
+     insets resolve to 0px there. The inline-start inset covers a landscape
+     rotation that puts the cutout on the rail's side. */
+  padding: max(var(--space-md), var(--safe-area-top)) var(--space-md)
+    max(var(--space-md), var(--safe-area-bottom))
+    max(var(--space-md), var(--safe-area-left));
   position: sticky;
   inset-block-start: 0;
   block-size: 100svh;
@@ -108,7 +116,7 @@
 
 @media (pointer: coarse) {
   .ui-app-nav a {
-    min-block-size: 2.9rem;
+    min-block-size: var(--tap-target);
     padding-inline: 0.9rem;
   }
 }
@@ -178,7 +186,10 @@
   display: flex;
   gap: var(--space-md);
   justify-content: space-between;
-  padding: 0.75rem var(--space-lg);
+
+  /* Sticks to the very top, so the bar's own background must bleed under the
+     status bar while its CONTENT clears it — pad, do not offset. */
+  padding: max(0.75rem, var(--safe-area-top)) var(--space-lg) 0.75rem;
   position: sticky;
   inset-block-start: 0;
   z-index: var(--z-raised);