@apliteni/apliteni-ui 0.23.2 → 0.23.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@apliteni/apliteni-ui",
-  "version": "0.23.2",
+  "version": "0.23.3",
   "workspaces": [
     "react"
   ],

package/src/components/overlay.js

@@ -1,19 +1,12 @@
-// Overlay primitives — the page state the kit's modal surfaces share.
-//
-// Drawer and Confirm are the same problem twice: content over a scrim that owns
-// the keyboard until it is answered. Three of the questions they raise are
-// properties of the *page*, not of either component — what is inert right now,
-// which overlay Escape talks to, and where Tab may go — and an overlay that
-// answers them from its own storage gets them wrong as soon as a second one is
-// open. So they are answered here, once, from one stack per document.
-//
-// Internal — not re-exported from src/index.js.
-
-// What each overlay paints on, as its stylesheet resolves it today: a drawer at
-// `--z-overlay` (src/styles/drawer.css) and a confirm one above it
-// (src/styles/confirm.css). Absolute values, not ranks, so a sheet that moves and
-// a table that did not is a failed test rather than a keyboard on the wrong layer
-// — stories/overlay-css.test.js holds these two numbers to those two rules.
+// Overlay primitives — the page state the kit's modal surfaces share. Drawer and Confirm
+// are the same problem twice: content over a scrim that owns the keyboard until it is
+// answered. What is inert, which overlay Escape talks to and where Tab may go are
+// properties of the *page*, so they are answered here from one stack per document rather
+// than from either component's own storage. Internal — not re-exported from src/index.js.
+
+// What each overlay paints on today: a drawer at `--z-overlay` (styles/drawer.css) and a
+// confirm above it (styles/confirm.css). Absolute values, not ranks, so a sheet that moves
+// and a table that did not is a failed test — stories/overlay-css.test.js holds both.
 export const OVERLAY_LAYER = { drawer: 100, confirm: 101 };
 
 const FOCUSABLE = [
@@ -33,10 +26,9 @@ function pageOf(doc) {
   return page;
 }
 
-// Focusable to the *browser*, not merely matching the selector. A control in a
-// closed overlay, an inert subtree or a hidden ancestor is skipped by the real
-// tab order, so a trap that counts it wraps at an element focus never reaches
-// and Tab walks straight out of the modal.
+// Focusable to the *browser*, not merely matching the selector. A control in a closed
+// overlay, an inert subtree or a hidden ancestor is skipped by the real tab order, so a
+// trap that counts it wraps at an element focus never reaches.
 function reachable(el) {
   for (let n = el; n && n.nodeType === 1; n = n.parentElement) {
     if (n.inert || n.hasAttribute('inert') || n.hasAttribute('hidden')) return false;
@@ -53,10 +45,9 @@ export function focusablesIn(panel) {
   return Array.from(panel.querySelectorAll(FOCUSABLE)).filter(reachable);
 }
 
-// Hide everything *outside* `root` from AT + the tab order: walk root→body and
-// mark each ancestor's other children. The scrim and panel live inside the root
-// so they stay interactive; an overlay one layer down is outside it, so it does
-// not — a drawer under an aria-modal alertdialog must not be tabbable.
+// Hide everything *outside* `root` from AT + the tab order: walk root→body and mark each
+// ancestor's other children. Scrim and panel live inside the root so they stay
+// interactive; a drawer under an aria-modal alertdialog is outside it and must not be.
 function mark(page, doc, root) {
   let node = root;
   while (node && node.parentElement && node !== doc.body) {
@@ -81,10 +72,9 @@ function unmark(page) {
   page.marked = [];
 }
 
-// Recompute the page from the stack — never replay a snapshot taken when an
-// overlay opened, because by the time it closes that snapshot describes a page
-// that has moved on. Roots torn down while open drop out here, so the record of
-// what to give back outlives the node that hid it.
+// Recompute the page from the stack — never replay a snapshot taken when an overlay
+// opened, because by the time it closes that snapshot describes a page that has moved on.
+// Roots torn down while open drop out here.
 function sync(doc) {
   const page = pageOf(doc);
   for (let i = page.stack.length - 1; i >= 0; i--) {
@@ -128,12 +118,11 @@ function place(root, panel, dismiss, layer, where) {
   sync(doc);
 }
 
-// The layer this root actually paints on. In a browser the live z-index is the
-// truth, so a consumer who moves either overlay in their own stylesheet gets the
-// keyboard on the layer they can see. JSDOM has no cascade to resolve: it hands
-// back the declared text — `calc(var(--z-overlay) + 1)` with the kit's sheets,
-// `auto` with none — and neither is a number, so under test the passed constant
-// stands. `auto` must not read as 0; anything unparseable falls through.
+// The layer this root actually paints on. In a browser the live z-index is the truth, so
+// a consumer who moves an overlay in their own stylesheet gets the keyboard on the layer
+// they can see. JSDOM hands back declared text rather than a number, so under test the
+// passed constant stands — `auto` must not read as 0, and anything unparseable falls
+// through.
 function paintedLayer(root, layer) {
   const painted = root.ownerDocument.defaultView?.getComputedStyle(root)?.zIndex;
   const live = painted ? Number(painted) : NaN;
@@ -152,16 +141,11 @@ export function pushOverlay(root, panel, dismiss, layer) {
 }
 
 /**
- * Take on a root that arrived already open — markup rendered with `open: true`,
- * which nobody called open…() for. Without this its aria-modal is a claim the
- * page contradicts.
- *
- * It goes in by PAINT ORDER, because wiring has no history to order by. Document
- * position only separates two overlays on the same layer, and there it is the
- * right answer rather than a fallback: at equal stack levels the later root
- * paints on top (CSS 2.2 Appendix E, steps 8 and 9).
- *
- * A root that renders closed is left alone — wiring is not an opening.
+ * Take on a root that arrived already open — markup rendered with `open: true`, which
+ * nobody called open…() for. Without this its aria-modal is a claim the page contradicts.
+ * It goes in by PAINT ORDER, because wiring has no history to order by; document position
+ * separates two overlays on the same layer, where the later root paints on top (CSS 2.2
+ * Appendix E, steps 8 and 9). A root that renders closed is left alone.
  */
 export function adoptOverlay(root, panel, dismiss, layer) {
   if (!root.classList.contains('is-open')) return;

package/src/components/shell.js

@@ -10,9 +10,8 @@ import { sidebarNav, breadcrumbs } from './nav.js';
 import { prism } from '../assets/brand.js';
 import { ACCOUNT_NAV, toMenuTuple, initials } from './account-nav.js';
 
-// The one account navigation definition lives in account-nav.js, because
-// topbar.js needs it too and this file already imports topbar.js. Re-exported
-// here so the published name docs/library.md documents keeps working.
+// The one account navigation definition lives in account-nav.js because topbar.js needs
+// it too; re-exported here so the name docs/library.md publishes keeps working.
 export { ACCOUNT_NAV };
 
 const str = (v) => (v == null ? '' : String(v));
@@ -20,32 +19,24 @@ const isRecord = (v) => typeof v === 'object' && v !== null;
 
 // ---- the options bag, settled once --------------------------------------
 //
-// Every option below carries a shape, and a default parameter covers
-// `undefined` and nothing else — so `nav: null` from an /auth/me, a `maxWidth`
-// out of tenant config, a `crumbs` string written by somebody reading the
-// migration note all arrived as they were. A shell that throws mid-render takes
-// the page with it, so each is settled here, before the first sink sees it, and
-// a parameter is protected by being declared rather than by what it crashes
-// into. Adding one to appShell() means adding it to SHAPES or deciding in the
-// open that it needs nothing.
-
-// accountShell() has always taken its nav as [id, icon, label, href?, target?].
-// Accept that shape and nav.js's object shape side by side, so a consumer's
-// existing tuples and the exported ACCOUNT_NAV both work. A nav that is not a
-// list at all falls back to the default; an entry inside one that is neither
-// shape is dropped, because sideItem() reads `.items` off whatever it is given.
-// An empty list is an answer, not a mistake — it stays empty.
+// A default parameter covers `undefined` and nothing else, so `nav: null` from an
+// /auth/me and a `crumbs` string from somebody reading the migration note both arrived
+// as they were. A shell that throws mid-render takes the page with it, so each option is
+// settled here, before the first sink sees it. Adding one to appShell() means adding it
+// to SHAPES or deciding in the open that it needs nothing.
+
+// accountShell()'s tuple nav — [id, icon, label, href?, target?] — and nav.js's object
+// shape are accepted side by side. A nav that is not a list falls back to the default;
+// an entry that is neither shape is dropped. An empty list is an answer and stays.
 const toItems = (nav) => (Array.isArray(nav) ? nav : ACCOUNT_NAV)
   .filter(isRecord)
   .map((n) => (Array.isArray(n)
     ? { id: n[0], icon: n[1], label: n[2], href: n[3], target: n[4] }
     : n));
 
-// The trail is the caller's, and `crumbs` is the one option whose shape changed
-// in this release: the old API was `crumb: 'Payouts'`, a string, and the new one
-// is `crumbs: [{ label }]`. One letter apart. A value that is not a list is not
-// read as a one-crumb trail — that would draw a plausible page and hide the
-// migration mistake — so it is no trail at all, which is the visible answer. A
+// The trail is the caller's, and `crumbs` changed shape this release: `crumb: 'Payouts'`
+// became `crumbs: [{ label }]`, one letter apart. A non-list is NOT read as a one-crumb
+// trail — that hides the migration mistake — so it is no trail at all, which shows. A
 // crumb with no label would draw an empty cell, so it goes too.
 const toCrumbs = (crumbs) => (Array.isArray(crumbs) ? crumbs : [])
   .filter((c) => isRecord(c) && !Array.isArray(c) && str(c.label) !== '');
@@ -56,23 +47,16 @@ const toReader = (a) => (isRecord(a) ? { name: str(a.name), email: str(a.email)
 
 // ---- the topbar, which interpolates where the rail escapes ----------------
 //
-// brand() writes `word` straight into its markup and accountMenu() does the
-// same with the reader's name, address and menu entries. So the escaping is
-// here, on the one path into productTopbar(), and not in each caller:
-// accountShell() escaped for itself and the `topbar` option underneath it
-// escaped for nobody. The caller passes text either way.
-
-// The reader the menu draws. Both fields are always written, empty when the
-// caller gave none — accountMenu()'s own defaults are a demo identity, and a
-// key dropped here is a key its default fills in, which is how a consumer's
-// page came to name its own reader in the rail and the kit's fixture beside it.
-//
-// `initials` travels with them because it is derived, and a derived value comes
-// from what the caller passed, not from the entities made of it: `<Ada>` and
-// `&lt;Ada&gt;` do not start with the same character. The entries land in the
-// same sink and toMenuTuple() is what escapes them; it reads item objects, so
-// tuples go through toItems() first. A nav nobody passed stays unpassed, and
-// accountMenu() falls back to its own derived default rather than to nothing.
+// brand() writes `word` straight into its markup and accountMenu() does the same with
+// the reader's name, address and menu entries, so the escaping is here on the one path
+// into productTopbar() rather than in each caller. The caller passes text either way.
+
+// The reader the menu draws. Both fields are always written, empty when the caller gave
+// none: accountMenu()'s defaults are a demo identity, so a key dropped here is a key its
+// fixture fills in. `initials` is derived from what the caller passed rather than from
+// the entities made of it — `<Ada>` and `&lt;Ada&gt;` do not start with the same
+// character. toMenuTuple() escapes the entries and reads item objects, so tuples go
+// through toItems() first; a nav nobody passed stays unpassed.
 const toMenuReader = (a) => {
   const { name, email } = toReader(a);
   const rest = isRecord(a) && !Array.isArray(a) ? a : {};
@@ -89,12 +73,11 @@ const toTopbar = (t) => {
   return out;
 };
 
-// `maxWidth` lands inside a style attribute, so a length is all this accepts —
-// a number and a unit, or `none`. Anything else yields '' and the caller writes
-// no style attribute, letting layout.css fall through to --measure. It must
-// REMOVE the property rather than pass a default or a bad value on: a custom
-// property accepts any token stream, so garbage is a valid declaration that
-// drops the column to `none`, the full track.
+// `maxWidth` lands inside a style attribute, so a length is all this accepts — a number
+// and a unit, or `none`. Anything else yields '' and the caller writes no style
+// attribute, falling through to --measure. It must REMOVE the property rather than pass
+// a bad value on: a custom property accepts any token stream, so garbage is a valid
+// declaration that drops the column to `none`, the full track.
 // why: docs/specification.md#widths
 const LENGTH = /^(?:\d+|\d*\.\d+)(?:px|rem|em|ch|%|vw)$/;
 const mainMax = (v) => {
@@ -108,11 +91,9 @@ const SHAPES = {
   nav: toItems, crumbs: toCrumbs, account: toReader, maxWidth: mainMax, topbar: toTopbar,
 };
 
-// The text options settle too, by the same argument the rest of them do. A
-// default parameter covers `undefined` and not `null`, so `body: null` from a
-// record with no description drew the word "null" on the page, and `word: null`
-// left the brand link with no accessible name at all. Dropping the key is what
-// lets the declared default apply.
+// The text options settle by the same argument. `body: null` from a record with no
+// description drew the word "null" on the page and `word: null` left the brand link with
+// no accessible name; dropping the key is what lets the declared default apply.
 const TEXT = ['word', 'brandHref', 'navLabel', 'title', 'sub', 'body', 'signOutHref', 'active'];
 
 function settle(options) {
@@ -122,23 +103,18 @@ function settle(options) {
   return out;
 }
 
-// Signing out is a navigation action, so it belongs in the rail nav's footer
-// slot. Opt-in: a shell that renders it unasked puts a dead link on a page with
-// no session behind it.
+// Signing out is a navigation action, so it belongs in the rail nav's footer slot.
+// Opt-in: rendering it unasked puts a dead link on a page with no session behind it.
 const signOut = (href) =>
   `<a class="ui-nav__item is-danger" href="${esc(href)}" aria-label="Sign out">` +
   `<span class="ui-nav__ic">${icon('logout')}</span>` +
   `<span class="ui-nav__label">Sign out</span></a>`;
 
-// Who is signed in. A sibling of the <nav>, not its footer: a reader's name and
-// address are not navigation, and inside the landmark a screen reader announces
-// the address as an entry. Empty when nobody is — a shell must not invent an
-// identity for a reader it does not know.
-//
-// The initials carry the name, and the spelled-out half is aria-hidden. The
-// narrow rail folds `.ui-app__who` out of view, so a name that lived only there
-// left the initials on screen with nothing at all in the accessibility tree.
-// Naming the mark instead makes the two agree at every width, and says it once.
+// Who is signed in. A sibling of the <nav>, not its footer: a name and address are not
+// navigation, and inside the landmark a screen reader announces the address as an entry.
+// Empty when nobody is. The initials carry the name and the spelled-out half is
+// aria-hidden, because the narrow rail folds `.ui-app__who` out of view and a name that
+// lived only there left nothing in the accessibility tree.
 function railUser({ name, email }) {
   if (!name && !email) return '';
   const who = [name, email].filter(Boolean).join(', ');
@@ -179,16 +155,14 @@ export function appShell(options = {}) {
     ariaLabel: navLabel,
     footer: signOutHref ? signOut(signOutHref) : '',
   });
-  // The topbar already says the product word. Two lockups on one screen is one
-  // product word too many, so the rail head steps aside when there is a topbar.
-  // The word is the link's only text and the narrow rail folds it out of view,
-  // so the name is written out — the mark itself is aria-hidden.
+  // The topbar already says the product word, so the rail head steps aside when there is
+  // one. The word is the link's only text and the narrow rail folds it out of view, so
+  // the name is written out — the mark itself is aria-hidden.
   const brand = topbar ? '' : `<a class="ui-app__brand" href="${esc(brandHref)}" aria-label="${esc(word)}">`
     + `${prism(`appb-${++_shellUid}`, 24)}<span>${esc(word)}</span></a>`;
-  // A <div>, not an <aside>: <aside> is the `complementary` landmark — content
-  // related to the page but separable from it — and this holds the page's
-  // primary navigation and the reader who is signed in. The <nav> inside it is
-  // already the landmark that names the menu.
+  // A <div>, not an <aside>: <aside> is the `complementary` landmark, and this holds the
+  // page's primary navigation and the signed-in reader. The <nav> inside it is already
+  // the landmark that names the menu.
   const grid = `<div class="ui-app">
     <div class="ui-app__rail">
       ${brand}
@@ -225,11 +199,9 @@ export function accountShell({
   // topbar menu are handed one list rather than two readings of `nav`.
   const items = toItems(nav);
   const trail = [{ label: cap }, { label: crumb || title }];
-  // The preset hands the topbar the caller's text, exactly as it hands the rail
-  // the caller's text. toTopbar() is what escapes for the menu's raw sinks, and
-  // it runs once inside appShell() — escaping here as well would reach the menu
-  // as entities, and escaping nowhere is what the public `topbar` option used
-  // to do.
+  // The preset hands the topbar the caller's text, as it does the rail. toTopbar()
+  // escapes for the menu's raw sinks and runs once inside appShell(); escaping here as
+  // well would reach the menu as entities.
   return appShell({
     word,
     nav: items,

package/src/styles/table.css

@@ -34,14 +34,10 @@
 .ui-table tbody tr { transition: background var(--dur-fast) var(--ease); }
 
 /* Row hover: an inset, rounded fill so the highlight never sits flush against a
- * container's border (issue #71 — the full-bleed rectangle collided with a card's
- * left edge). Separate border model with zero spacing keeps the row separators
- * continuous while letting the row ends round; table padding (which only applies
- * in the separate model) insets the rows so the fill clears the container edge.
- * Zebra tables keep the original full-bleed tint (finance ledger), so they're
- * excluded here — their hover rule lives further down.
- * The inset was 6px, which is a tie between --space-1 and --space-2; it rounds
- * up, because what it buys is clearance and clearance rounds away from the edge. */
+ * container's border (#71). The separate border model with zero spacing keeps the row
+ * separators continuous while letting the row ends round, and table padding — which
+ * only applies in that model — insets the rows. Zebra keeps the original full-bleed
+ * tint (finance ledger) and is excluded here; its hover rule is below. */
 .ui-table--hover:not(.ui-table--zebra) {
   border-collapse: separate;
   border-spacing: 0;
@@ -54,9 +50,7 @@
   border-top-right-radius: var(--radius-sm); border-bottom-right-radius: var(--radius-sm); }
 
 /* Data-table modifiers, composable: .ui-table--dense --zebra --hover.
- *   --dense  --space-3 across, --space-2 down — one step in from the base
- *            table, and both round DOWN, because the modifier exists to fit
- *            more rows and rounding up spends the distinction it is for.
+ *   --dense  --space-3 across, --space-2 down — one step in from the base table
  *   --zebra  row striping; 2px header rule; the hover tint out-ranks the stripe
  * Cell helpers: .ui-table__num (right, tabular), .ui-table__code.
  * why: docs/specification.md#spacing-and-rhythm
@@ -71,15 +65,11 @@
 .ui-table--zebra th { border-bottom-width: 2px; }
 .ui-table--zebra td { border-bottom: 0; }
 .ui-table--zebra tbody tr:nth-child(even) td { background: var(--surface-2); }
-/* The stripe is full-bleed on purpose — the hover note above inset the hover fill for
- * #71 and deliberately left the ledger stripe alone. But full-bleed only reads right if
- * the end cells are inset from the tint's own edge, and the base rhythm does not inset
- * them: `.ui-table td` sets `padding-left: 0`. Only `--dense` supplied the inset, so a
- * `--zebra` table composed WITHOUT `--dense` put the first cell's content at exactly
- * x=0 of the stripe. `DataTable` is that composition — it writes `ui-table
- * ui-table--hover ui-table--zebra` and no `--dense` — so its select-all and per-row
- * checkboxes sat flush against the tint with a measured 0px gap.
- * Header and body are inset together, or the columns stop lining up. */
+/* The stripe stays full-bleed (the #71 inset above is hover only), but it only reads right
+ * if the end cells are inset from the tint's own edge, and `.ui-table td` sets
+ * `padding-left: 0`. Only `--dense` supplied that inset, so `--zebra` without `--dense` —
+ * `DataTable`'s composition — sat its checkboxes at x=0 of the stripe. Head and body are
+ * inset together, or the columns stop lining up. */
 .ui-table--zebra th:first-child,
 .ui-table--zebra td:first-child { padding-left: var(--space-3); }
 .ui-table--zebra th:last-child,

package/src/tokens/accents.css

@@ -62,25 +62,15 @@
   --purple: #1156b8;
   --purple-light: #1568d6;
   --purple-mid: #1560c8;
-  /* Deepened for WCAG AA on the raised grey panel and its wash: #1568d6 read
-     4.54:1 on --surface-3 and 3.98:1 on --glow-purple over it; #005bc8 clears
-     both at 5.43:1 and 4.76:1. Both washed figures are at the 0.10 alpha below,
-     which is what this cell ships — an earlier version of this comment quoted
-     them at the 0.05 the wash briefly carried, which flattered both inks.
-     Light Ocean is the one light accent #96 never deepened, because it happened
-     to clear plain white. Same kind of move, smaller: hue and chroma unchanged
-     in OKLCH (H 258, C 0.185) and four points of lightness down, where #96's
-     two took about ten points and gave up 15.9% of the chroma on Phoenix and
-     17.6% on Emerald. See issues #96 and #157. */
+  /* Deepened for WCAG AA on the raised grey panel and its wash — hue and chroma held
+     in OKLCH (H 258, C 0.185), four points of lightness down. The washed figures are
+     read at the 0.10 alpha below, which is what this cell ships. See issues #96, #157. */
   --accent: #005bc8;
   --accent-strong: var(--accent);
   --accent-contrast: #ffffff;
-  /* Back to 0.10, the alpha this cell carried before #157. #157 thinned it to
-     0.05 while --accent was still #1568d6, because no alpha could carry that
-     blue over the grey panel. Deepening the ink is what closed the pair, so the
-     wash does not have to be the thing that gives. The rgb stays --purple-light
-     rather than the accent — in light a glow tints --purple-light, which
-     stories/signal-contrast.test.js holds. See issue #157. */
+  /* Back to the 0.10 this cell carried before #157: deepening the ink closed the pair,
+     so the wash does not have to give. The rgb stays --purple-light rather than the
+     accent — in light a glow tints --purple-light, which signal-contrast.test.js holds. */
   --glow-purple: rgba(21, 104, 214, 0.10);
   --grad-from: #1568d6;
   --grad-to: #17a2c0;

package/src/tokens/tokens.css

@@ -1,14 +1,8 @@
 /* ============================================================================
- * apliteni-ui — design tokens
- * Single source of truth for the Apliteni deck theme.
- *
- * Colour semantics are identical to viz/ (deck index.html, account.mjs):
- *   purple accent, near-black surfaces, green = live, cyan = link/flag.
- * Two themes: dark (default) and light. Toggle with `data-theme` on <html>.
- *
- * Everything downstream references the SEMANTIC tokens (--bg, --surface,
- * --accent, --text…), never the raw ramp. Swap a ramp value once, and every
- * component follows.
+ * apliteni-ui — design tokens. Single source of truth for the Apliteni deck theme,
+ * with viz/'s colour semantics: purple accent, near-black surfaces, green = live,
+ * cyan = link/flag. Two themes, dark (default) and light, toggled with `data-theme`
+ * on <html>. Everything downstream references the SEMANTIC tokens, never the ramp.
  * ========================================================================== */
 
 :root {
@@ -44,7 +38,6 @@
   /* -- Measure ------------------------------------------------------------
    * --container is the page, gutter to gutter; --measure is the reading column
    * INSIDE a track, beside a sidebar. Different axes, never interchangeable.
-   * Below --measure are --panel-* and --prose-*, at the end of this file (#208).
    * why: docs/specification.md#widths */
   --container: 1120px;
   --measure: 860px;
@@ -79,13 +72,12 @@
   --tracking-caps: 0.14em;
 
   /* -- Motion -------------------------------------------------------------
-   * Durations + easings are the Apliteni brand's motion vocabulary, synced
-   * from design-system into brand.generated.css (--duration-*, --easing-*).
-   * The kit's legacy --dur-* and --ease names alias onto them, so every existing
-   * component transitively consumes the brand primitives — one vocabulary,
-   * zero drift. Fallbacks keep tokens.css self-sufficient when imported
-   * without brand.generated.css. Delays are the kit's own (not a brand
-   * concern). The reusable effect layer lives in styles/motion.css. */
+   * The kit's legacy --dur-* and --ease names alias onto the brand's
+   * --duration-* and --easing-* primitives, so every component consumes one
+   * vocabulary; the fallbacks keep tokens.css self-sufficient when imported
+   * without brand.generated.css. Delays are the kit's own, and the reusable
+   * effect layer lives in styles/motion.css.
+   * why: CONTRIBUTING.md#brand-tokens-synced-from-design-system */
   --ease: var(--easing-ease-in-out, cubic-bezier(0.4, 0, 0.2, 1));
   --ease-out: var(--easing-ease-out, cubic-bezier(0, 0, 0.2, 1));
   --ease-in: var(--easing-ease-in, cubic-bezier(0.4, 0, 1, 1));
@@ -119,22 +111,16 @@
   color-scheme: dark;
 
   --purple: #6a2dcc;
-  /* The ramp moves up one step so --accent is --purple-light again, which is
-     the shape light Nebula and light Ocean already ship and which dark Nebula
-     held until #157 lifted the accent onto the old --purple-mid. Left alone,
-     the two tokens would resolve to one colour and the ramp would carry a
-     duplicate step. #bd8cff is the value docs/specification.md#colour-and-contrast reasons about and
-     rejects as the accent; it becomes the ramp's top step instead. Light
-     Nebula's ramp does not move. See issue #157. */
+  /* The ramp moves up one step so --accent is --purple-light again, the shape light
+     Nebula and light Ocean already ship; left alone the two tokens would resolve to
+     one colour. #bd8cff becomes the ramp's top step instead. See issue #157. */
   --purple-light: #b479ff;
   --purple-mid: #bd8cff;
   --cyan: #20dcf5;
   --green: #98ff8f;
-  /* Lighter than it looks like it should be, and deliberately so: --pink is read
-     mostly ON its own 16% glow, and that wash lifts the ground faster than the
-     hue lifts the ink. #e35b8f measured 3.82:1 on --glow-pink over a card —
-     under AA — so danger moved AWAY from the canvas, not toward it. Light moves
-     the opposite way for the same reason. See issue #131. */
+  /* Lighter than it looks like it should be: --pink is read mostly ON its own 16%
+     glow, and that wash lifts the ground faster than the hue lifts the ink, so danger
+     moved AWAY from the canvas. Light moves the opposite way. See issue #131. */
   --pink: #e97ca5;
   --amber: #ffcf6a;
 
@@ -144,9 +130,8 @@
   --surface-2: #1b1927;
   --surface-3: #2a2739;
   --seg-active-bg: #34314a; /* raised pill — clearly above the inset track in dark */
-  /* The raised handle on a control track (switch knob). Stays white in both
-     themes and under every accent: it has to read on the plain track AND on
-     the accent fill the track takes when the control is on. */
+  /* The raised handle on a control track (switch knob). White in both themes and under
+     every accent: it reads on the plain track AND on the accent fill of an on control. */
   --control-knob: #ffffff;
   --border: #332f45;
   --border-strong: #453f5c;
@@ -156,53 +141,40 @@
   --dim: #c6c2d6;
   --muted: #948fa8;
 
-  /* The paint of a control that is off. NOT an opacity: `opacity` is a group
-     property, so it fades a label and the box under it toward the ground
-     TOGETHER and the pair a reader is left with is whatever that composite
-     lands on — a disabled primary button measured 1.48:1 that way, white on a
-     faded accent. These three composite predictably instead: the ink is read on
-     the surface beside it, and both are opaque. They are aliases, not new
-     colours — the ramp gains nothing to keep in sync. A disabled control drops
-     its accent, which is most of what makes it read as inert; the ink going
-     quiet is the rest. Held by stories/guidelines/accessibility-floor.test.js.
+  /* The paint of a control that is off. NOT an opacity: `opacity` is a group property,
+     so it fades label and box toward the ground TOGETHER — a disabled primary button
+     measured 1.48:1 that way. These three are aliases that composite predictably, the
+     ink read on the surface beside it. Held by guidelines/accessibility-floor.test.js.
      why: docs/specification.md#colour-and-contrast */
   --disabled-ink: var(--muted);
   --disabled-surface: var(--surface-2);
   --disabled-border: var(--border);
 
-  /* Lifted from #9b5dff, which cleared the flat surfaces and failed on its own
-     wash over a card. This value was already in the ramp as --purple-mid, so no
-     new colour entered it; the ramp then moved up a step above so --accent is
-     --purple-light, which is how every other Nebula and Ocean cell is written.
-     --glow-purple follows it down the file; --ring is written as var(--accent)
-     and so follows it by reference. Held by
-     stories/accent-contrast.test.js. See issue #157.
+  /* Lifted from #9b5dff, which cleared the flat surfaces and failed on its own wash over
+     a card; the value was already in the ramp. --ring is var(--accent) and follows by
+     reference. Held by stories/accent-contrast.test.js. #157.
      why: docs/specification.md#colour-and-contrast */
   --accent: #b479ff;
   --accent-strong: #7c3aed; /* button bg — white text clears WCAG AA at 5.70:1 */
   --accent-contrast: #ffffff;
   --ink: #e9e7f0;
 
-  /* Ink that reads on a SIGNAL colour once that colour becomes a fill — the
-     glyph in a success circle, the glyph on a toast's status circle. One
-     near-black ink clears all five in dark; danger keeps a token of its own
-     because LIGHT still needs one.
+  /* Ink that reads on a SIGNAL colour once that colour becomes a fill — the glyph in a
+     success circle, or on a toast's status circle. One near-black ink clears all five in
+     dark; danger keeps its own token because LIGHT still needs one.
      why: docs/specification.md#colour-and-contrast */
   --signal-contrast: #0c0c0c;
   --danger-contrast: var(--signal-contrast);
 
   --glow-green: rgba(152, 255, 143, 0.16);
-  /* Dropped from 0.18: the wash, not the surface beneath it, is what put --accent
-     under AA — it lifts the ground toward the ink faster than the ink lifts off
-     it. Re-tinted from the new --accent, which signal-contrast.test.js requires.
-     See issue #157. */
+  /* Dropped from 0.18: the wash, not the surface beneath it, is what put --accent under
+     AA. Re-tinted from the new --accent, which signal-contrast.test.js requires. #157. */
   --glow-purple: rgba(180, 121, 255, 0.12);
   --glow-cyan: rgba(32, 220, 245, 0.14);
   --glow-pink: rgba(233, 124, 165, 0.16);
 
-  /* Status-chip paint — the ink + fill of a badge / pill. Dark tints with the
-     signal's own glow; light needs a solid, deepened pair (the glows wash out
-     on white), which is why these are a token pair and not just --green etc. */
+  /* Status-chip paint — the ink + fill of a badge / pill. Dark tints with the signal's
+     own glow; light needs a solid, deepened pair, which is why these are a token pair. */
   --chip-success-ink: var(--green);
   --chip-success-fill: var(--glow-green);
   --chip-warn-ink: var(--amber);
@@ -212,14 +184,10 @@
   --chip-info-ink: var(--cyan);
   --chip-info-fill: var(--glow-cyan);
 
-  /* Solid signal surfaces — a status that has stopped being ink and become the
-     FILL (a solid toast). The fill and its ink are ONE pair, never two
-     independent picks: the fill is the status at this theme's extreme, and the
-     ink is the pole opposite it, so a single ink clears all five. Dark fills are
-     the bright signals, so the ink is near-black — it measures 15.87 on --green,
-     7.35 on --pink, 13.40 on --amber, 11.75 on --cyan and 6.29 on --muted.
-     Neutral needs no chip pair to take part: --muted is already its
-     fill-strength form. See issues #131 and #149. */
+  /* Solid signal surfaces — a status that has stopped being ink and become the FILL (a
+     solid toast). Fill and ink are ONE pair, never two independent picks: the fill is the
+     status at this theme's extreme and the ink the pole opposite it, so a single ink
+     clears all five. --muted is already its own fill-strength form. See #131, #149. */
   --signal-solid-ink: var(--signal-contrast);
   --signal-solid-success: var(--green);
   --signal-solid-danger: var(--pink);
@@ -232,19 +200,18 @@
   --shadow-lg: 0 18px 50px rgba(0, 0, 0, 0.5);
   /* Tight elevation for the active segmented pill — stays contained in its track. */
   --shadow-seg: 0 1px 2px rgba(0, 0, 0, 0.45), 0 2px 4px rgba(0, 0, 0, 0.3);
-  /* Resting elevation for a card. Dark cards are borderless — the surface does
-     the grouping on its own — so they cast nothing. */
+  /* Resting elevation for a card. Dark cards are borderless — the surface groups on
+     its own — so they cast nothing. */
   --shadow-card: none;
-  /* THE ONLY --ring in the kit — light and every data-accent sub-theme declare
-     an --accent and inherit this line. Opaque because a translucent ring is a
-     glow: the eight rgba() literals this replaced all missed the 3:1 of WCAG
-     1.4.11, at 1.35:1 worst. Held at 4.22:1 worst by
-     stories/guidelines/accessibility-floor.test.js. See issue #218.
+  /* THE ONLY --ring in the kit — light and every data-accent sub-theme declare an
+     --accent and inherit this line. Opaque because a translucent ring is a glow, and the
+     eight rgba() literals it replaced all missed WCAG 1.4.11's 3:1 (#218). Held by
+     stories/guidelines/accessibility-floor.test.js.
      why: docs/specification.md#the-focus-ring */
   --ring: 0 0 0 3px var(--accent);
 
-  /* The ink a cast shadow is made of, and the specular white that reads as
-     gloss on a raised surface. Effects mix these instead of writing rgba(). */
+  /* The ink a cast shadow is made of, and the specular white that reads as gloss on a
+     raised surface. Effects mix these instead of writing rgba(). */
   --shadow-ink: #000000;
   --sheen: #ffffff;
 
@@ -252,10 +219,8 @@
   --scrim: rgba(0, 0, 0, 0.58);
 
   /* Accent gradient stops (hero headline, marketing) — overridden per sub-theme.
-     --grad-from is pinned to the literal rather than tracking --purple-light,
-     which #157 moved up a step: following it would lighten the hero gradient's
-     first stop, a visible change nobody asked for. Every --grad-from in
-     src/tokens/accents.css is already written as a literal for the same reason. */
+     --grad-from is pinned to a literal rather than tracking --purple-light, which #157
+     moved up a step; every --grad-from in accents.css is a literal for the same reason. */
   --grad-from: #9b5dff;
   --grad-to: var(--cyan);
 }
@@ -271,15 +236,13 @@
   --purple-mid: #7a3be0;
   --cyan: #0c8fa8;
   --green: #1c8a2c;
-  /* Deeper than the dark pink for the same reason dark's is lighter: the wash
-     under it is white, so the ink has to come down to meet it. #d63c72 measured
-     3.87:1 on --glow-pink over white and 4.42:1 on plain white — the required
-     marker and the form error missed AA on nothing at all. See issue #131. */
+  /* Deeper than the dark pink for the same reason dark's is lighter: the wash under it
+     is white, so the ink has to come down to meet it. See issue #131. */
   --pink: #b63361;
   --amber: #b5730a;
 
-  /* A WHITE app: the page and cards are both white; cards are delineated by a
-     hairline border + soft shadow (see card.css), not a grey canvas. */
+  /* A WHITE app: page and cards are both white, and cards are delineated by a hairline
+     border + soft shadow (see card.css), not a grey canvas. */
   --bg: #ffffff;
   --bg-elevated: #ffffff;
   --surface: #ffffff;
@@ -295,9 +258,8 @@
   --dim: #3a404b;
   --muted: #5c6270;
 
-  /* Same three aliases as dark, same reasoning. Light moves the disabled
-     surface AWAY from white for the same reason dark moves it away from the
-     card: a control that is off should sink, not rise. */
+  /* Same three aliases as dark. Light moves the disabled surface AWAY from white for the
+     same reason dark moves it away from the card: a control that is off should sink. */
   --disabled-ink: var(--muted);
   --disabled-surface: var(--surface-2);
   --disabled-border: var(--border);
@@ -310,45 +272,33 @@
   --signal-contrast: #0c0c0c;
   --danger-contrast: #ffffff;
 
-  /* Re-tinted from --green. It was rgba(30, 150, 50, .1) — a colour that exists
-     nowhere else in the kit, carried unedited since the initial commit while the
-     other three light glows are exact tints of their own token. The wash over
-     white moves #e9f5eb -> #e8f3ea, at most two levels on a channel, which is
-     0.86 of a deltaE — under the 1.0 that is normally called imperceptible. No
-     verdict moves with it: body copy on the success wash goes 9.29 -> 9.15
-     against the 4.5 AA bar, and the --green icon on it 3.97 -> 3.91 against the
-     3.0 bar WCAG 1.4.11 sets for a graphic. The success chips are untouched —
-     light's --chip-success-fill is the solid #dff3e4, not this. Gated for all
-     four glows in stories/signal-contrast.test.js. See issue #131. */
+  /* Re-tinted from --green; it was rgba(30, 150, 50, .1), a colour that exists nowhere
+     else in the kit while the other three light glows are exact tints of their own token.
+     The wash over white moves at most two levels on a channel and no verdict moves with
+     it. Gated for all four glows in stories/signal-contrast.test.js. */
   --glow-green: rgba(28, 138, 44, 0.1);
   --glow-purple: rgba(106, 45, 204, 0.09);
   --glow-cyan: rgba(12, 143, 168, 0.1);
   --glow-pink: rgba(182, 51, 97, 0.1);
 
-  /* Solid chip pairs for the white app. Each ink is deepened past its signal
-     hue so 10px uppercase text clears WCAG AA on its own pale fill —
-     e.g. --pink (#b63361) on #fbe0ea is 4.66:1, #b7295f is 4.85:1. */
+  /* Solid chip pairs for the white app. Each ink is deepened past its signal hue so 10px
+     uppercase text clears WCAG AA on its own pale fill. */
   --chip-success-ink: #1f7a38;
   --chip-success-fill: #dff3e4;
   --chip-warn-ink: #8a5e00;
   --chip-warn-fill: #fbedd2;
   --chip-danger-ink: #b7295f;
   --chip-danger-fill: #fbe0ea;
-  /* Info was the one signal family without a pair, so the info badge was still
-     painting --cyan (#0c8fa8) on --glow-cyan over white, which is 3.39:1 —
-     under AA. #0a7286 on #ddeff3 is 4.71:1, inside the 4.64–4.93 band the other
-     three pairs already sit in. See issue #131. */
+  /* Info was the one signal family without a pair, so the info badge painted --cyan on
+     --glow-cyan over white and missed AA. This pair sits in the band the other three
+     already occupy. See issue #131. */
   --chip-info-ink: #0a7286;
   --chip-info-fill: #ddeff3;
 
-  /* Light runs the same rule the other way. The signals are mid-tone here — a
-     solid --green fill measures 4.40 against near-black and 4.45 against white,
-     so NO ink rescues it and the fill is what has to move. It moves to the
-     deepened form the chip pair already carries, and the pole above it, white,
-     clears every one: #ffffff measures 5.39 on --chip-success-ink, 6.01 on
-     --chip-danger-ink, 5.70 on --chip-warn-ink, 5.58 on --chip-info-ink and 6.11
-     on --muted. A future status supplies one --signal-solid-* value dark enough
-     for white and inherits the ink. See issues #131 and #149. */
+  /* Light runs the same rule the other way. The signals are mid-tone here, so NO ink
+     rescues them and the fill is what has to move: it takes the deepened form the chip
+     pair already carries, and white clears every one. A future status supplies one
+     --signal-solid-* value dark enough for white and inherits the ink. See #131, #149. */
   --signal-solid-ink: #ffffff;
   --signal-solid-success: var(--chip-success-ink);
   --signal-solid-danger: var(--chip-danger-ink);
@@ -361,8 +311,8 @@
   --shadow-lg: 0 18px 50px rgba(30, 30, 50, 0.16);
   /* Tight elevation for the active segmented pill — stays contained in its track. */
   --shadow-seg: 0 1px 2px rgba(30, 30, 50, 0.12), 0 2px 4px rgba(30, 30, 50, 0.1);
-  /* A white card on a white page needs its own, flatter-than-sm elevation:
-     a hairline contact shadow plus a wide soft one (see card.css). */
+  /* A white card on a white page needs its own flatter-than-sm elevation: a hairline
+     contact shadow plus a wide soft one (see card.css). */
   --shadow-card: 0 1px 2px rgba(20, 25, 45, 0.04), 0 4px 14px rgba(20, 25, 45, 0.05);
   /* No --ring here. :root's is var(--accent), and light re-points --accent. */
 
@@ -376,42 +326,32 @@
 }
 
 /* ============================================================================
- * WIDTHS BELOW THE PAGE — the box, and the line
- *
- * --container is the page and --measure the reading column inside it (both
- * above). Underneath them the kit has two scales and one rule for choosing
- * between them: THE UNIT SAYS WHICH SCALE YOU ARE ON.
+ * WIDTHS BELOW THE PAGE — the box, and the line. Two scales, and one rule for
+ * choosing between them: THE UNIT SAYS WHICH SCALE YOU ARE ON.
  *
  *   a box that holds a COMPONENT   ->  --panel-*   (px)
  *   a box that holds a LINE        ->  --prose-*   (ch)
  *
- * Both are theme-invariant, which is why they sit outside the palette blocks.
+ * Both are theme-invariant, so they sit outside the palette blocks.
  * why: docs/specification.md#boxes-below-the-page
  * ========================================================================== */
 :root {
   /* -- Panel widths -------------------------------------------------------
-   * Not a new scale: the drawer has shipped sm/md/lg at exactly these three
-   * values since it was written, and confirm, the auth card and the toast each
-   * wrote one of them out again on their own. --panel-md answers the question
-   * #208 asked — the two 420s were three (--confirm-w, --drawer-w md and
-   * .ui-auth__card), and they are one measure now. */
+   * Not a new scale: the drawer has shipped sm/md/lg at these three values, and
+   * confirm, the auth card and the toast each wrote one out again (#208). */
   --panel-sm: 320px;
   --panel-md: 420px;
   --panel-lg: 560px;
 
   /* -- Prose measures -----------------------------------------------------
-   * ch resolves against the font-size of the element it is DECLARED on, so a
-   * step goes on the paragraph itself — never on a wrapper holding two type
-   * sizes, where the same token would mean two different widths.
-   *
-   * The four steps are the reading band (44–72ch), named for what is being
-   * read rather than sized s/m/l, so the choice is made by the writer:
+   * ch resolves against the font-size of the element it is DECLARED on, so a step
+   * goes on the paragraph itself, never on a wrapper holding two type sizes. The
+   * four steps are the reading band (44–72ch), named for what is being read:
    *   caption  one or two sentences under a glyph, centred
    *   lede     the line under a title
    *   body     a left-aligned column of copy
    *   dense    reference prose set below 13px, where the band runs wider
-   * --prose-display is NOT a measure. It is where a display headline rags, and
-   * it is far under the band on purpose. */
+   * --prose-display is NOT a measure — it is where a display headline rags. */
   --prose-display: 14ch;
   --prose-caption: 44ch;
   --prose-lede: 54ch;