@ksp-gonogo/ui-kit 0.1.0 → 0.2.0-rc.10

package/dist/tokens.css

@@ -1,13 +1,231 @@
+/*
+ * Every box measures its padding and border INSIDE the width it was given.
+ *
+ * Without this, a rule pairing `width: 100%` with horizontal padding resolves
+ * to 100% plus that padding and hangs over its parent's edge by exactly the
+ * inset. The panel toolbar measured 542px inside a 510px row, at every tile
+ * width and in every widget that drew one, and a fill empty state was 32px
+ * wider than the panel it was centred in, so its sentence was sliced by the
+ * border in four widgets at once. Neither is visible from the source: the rule
+ * that overflows reads as if it asks for exactly the space it has.
+ *
+ * It lives here because this file is what a page loads to be a gonogo page:
+ * the app imports it, and every render probe injects it verbatim. A page that
+ * draws kit primitives without it draws them at a size their authors never
+ * measured.
+ */
+*,
+*::before,
+*::after {
+  box-sizing: border-box;
+}
+
+/*
+ * Native form controls take their font, colour and background from the UA
+ * stylesheet rather than from the page, so a bare `<button>` draws in the
+ * browser's sans-serif with black words on a light grey box, and a bare input
+ * is a white box, on a dark panel. Every control takes the theme's type, text
+ * colour and raised surface instead, a pair that clears the text floor on
+ * its own, so a control no kit rule has styled is still readable. Kit
+ * controls set their own colours over it. The root carries the theme's text
+ * colour for the same reason: an inherited colour always ends at the theme
+ * and never at a browser default.
+ *
+ * It lives here for the same reason as the reset above: this file is what
+ * every page, render probe and Uplink docs page loads.
+ */
+html {
+  color: var(--color-text-primary);
+}
+
+button,
+input,
+select,
+textarea {
+  font: inherit;
+  color: var(--color-text-primary);
+  background-color: var(--color-surface-raised);
+}
+
 :root {
+  /*
+   * NAMING ACROSS FAMILIES. A convention, not a rule: a new token need not
+   * declare a category, and a name in one family needs no counterpart in
+   * another. The categories describe what the families already are.
+   *
+   *   container externals   --z-*, --color-* (boundary and ground), --radius-*
+   *   container internals   --color-* (content), --line-height-*, --gap-*,
+   *                         --inset-*
+   *   animation             --duration-*, --ease-*
+   *
+   * `--color-*` sits in both of the first two: a colour is either what a
+   * container is against what lies behind it (border, ground) or the
+   * treatment of what it holds (text, marks). It is one family because the
+   * names are not separable by prefix, not because the jobs are the same.
+   *
+   * A modifier such as `status` varies a token of an existing category and is
+   * never a category of its own. The set of three is closed: a fourth is a
+   * structural claim about the whole system and is made deliberately, not by
+   * adding a token.
+   *
+   * Reusing a term across families is the part with teeth. A shared word
+   * promises a pairing: `--radius-floating` names the corner of the boxes that
+   * sit on the `--z-*` rungs above the app (modal, fab), so a reader who reaches
+   * for one should reach for the other, and the two must actually belong
+   * together. Where that does not hold, use a different word
+   * rather than a familiar one borrowed by coincidence, because a coincidental
+   * match teaches a pairing nobody checked.
+   *
+   * This sits beside the bar for whether a name is earned at all (it must
+   * resolve differently by context or express a shape the rung ladder cannot),
+   * and governs only how names relate across families.
+   */
   --font-family-mono:
     "JetBrains Mono", ui-monospace, "IBM Plex Mono", Menlo, Consolas, monospace;
+  /*
+   * Type scale. `2xs` is the one step the census added: 103 of the 394
+   * hardcoded px font-sizes sit BELOW the old 11px floor (69 at 10px, 34
+   * at 9px), so the scale had no rung for the micro-labels this dense
+   * mission-control UI is built out of. Everything else maps onto the
+   * four rungs that were already here.
+   *
+   * The scale deliberately stops at `lg`. Every hardcoded size above
+   * 16px in the codebase (18/19/20/22/23/24/28) is either a fluid
+   * `clamp()`, a JS-computed fit, or a value comment-locked to a
+   * specific box width. A fixed display rung would freeze behaviour
+   * those widgets depend on, so they stay literal.
+   */
+  --font-size-2xs: 10px;
   --font-size-xs: 11px;
   --font-size-sm: 12px;
   --font-size-base: 14px;
   --font-size-lg: 16px;
 
   /*
-   * Colour tokens — names match `theme.colors.*` paths in
+   * SEMANTIC TYPE, over the rungs above. One name per JOB, where a job
+   * is what the text IS rather than how big it is.
+   *
+   * `caption` The annotation that names a value it does not contain.
+   *           Small caps and tracked, set apart from the reading it
+   *           points at. 165 sites, and the job has a ceiling the rung
+   *           ladder never described: it reaches 2xs, xs and sm and
+   *           never base or lg.
+   * `compact` The working text of a surface: rows, cells, control
+   *           labels, and the commentary beside them. 297 sites, 53% of
+   *           the whole population, so this is the app's real default
+   *           and the document's own 14px never was.
+   * `value`   What the caption points at. The name of a row or a card,
+   *           the reading in a labelled line, the text a form control
+   *           holds.
+   * `prose`   Consecutive sentences, read start to finish.
+   * `figure`  The number a widget exists to show.
+   *
+   * COMPACT AND PROSE ARE REGISTERS, NOT SIZES. The test is not length,
+   * it is whether a person reads the words in order or picks one out at
+   * a glance. The boundary is disjoint rather than a judgement at the
+   * margin: of the 297 compact sites, 2 set a max-width in em or ch and
+   * none sets `--line-height-prose`, so almost nothing outside `prose`
+   * holds a wrapped sentence at all.
+   *
+   * CAPTION AND VALUE ARE A PAIR, and colour says so independently of
+   * size: 85% of captions sit on a muted, faint or dim text colour and
+   * 69% of values on `--color-text-primary`. Reach for one and you are
+   * reaching for the other.
+   *
+   * THERE IS NO SIXTH NAME FOR SUPPORTING TEXT, and the reason is here
+   * because the question comes back. Split `compact` by what its
+   * declarations are called and the four strands (supporting text,
+   * control labels, small readings, the rest) come out at 11.22, 11.47,
+   * 10.71 and 11.24 mean px, which is one size. Supporting text IS a
+   * real job, and the design already marks it with COLOUR: 68% muted
+   * against 2% primary, where the rest of `compact` is 37% and 18%. A
+   * second size name would invent a distinction the design does not
+   * make and say a second time what `--color-text-muted` already says.
+   *
+   * NOT NAMED, and each absence is a decision:
+   *   a glyph's box   14 sites size an icon glyph THROUGH `font-size`
+   *                   rather than sizing text: a dismiss cross, a
+   *                   caret, a chevron centred in a button. That is a
+   *                   box dimension wearing a type property, it belongs
+   *                   to an icon family, and a type name offered for it
+   *                   would be reached for as text.
+   *   a display tier  Every size above 16px is a fluid `clamp()`, a
+   *                   JS-computed fit or a value locked to a box width,
+   *                   as the scale's own note above records. `figure`
+   *                   is the top of the type scale, not the bottom of a
+   *                   display one.
+   */
+  --font-size-caption: var(--font-size-2xs);
+  --font-size-compact: var(--font-size-xs);
+  --font-size-value: var(--font-size-sm);
+  --font-size-prose: var(--font-size-base);
+  --font-size-figure: var(--font-size-lg);
+
+  /*
+   * ICON SIZE. A separate family from the type scale on purpose: an icon's
+   * size is a BOX dimension, and a name offered on the type scale for it
+   * gets reached for as text.
+   *
+   * `control`    The glyph inside a control the operator presses. 46 of the
+   *              63 icon sites, and the number is not arbitrary: both
+   *              control tokens below already do their arithmetic against a
+   *              14px glyph, in writing. `--inset-control-compact` derives
+   *              an 18px header from 2 inset + 2 border + a 14px glyph, and
+   *              `--control-height` derives its 28 from 12 + 2 + 14. Sizing
+   *              icons at anything else falsifies both.
+   * `standalone` The glyph that IS its control: no label, nothing beside it,
+   *              on a target hit at a glance. Every `Fab`, and the
+   *              processor picker.
+   *
+   * THESE STEP ON A COARSE POINTER and a raw `size={14}` cannot. The step
+   * is the reason the family is custom properties rather than constants: a
+   * prop is a JS number and a number cannot read a media query, so today
+   * the two halves of one population disagree on a touch screen. A `×`
+   * drawn with `font-size` grows and the `<CloseIcon>` beside it does not.
+   *
+   * REACHED THROUGH THE `size` PROP, not through a CSS rule, because a
+   * `var()` resolves inside an SVG presentation attribute. Measured in
+   * chromium, firefox and webkit, with the negative controls that make the
+   * measurement worth having: `width="banana"` is rejected in all three and
+   * `width="var(--absent, 33px)"` renders at 33, so the probe can tell a
+   * failure from a success. Anyone tempted to "fix" a `size="var(...)"`
+   * back to a number should reverse that reasoning, not the code.
+   *
+   * NOT NAMED:
+   *   an overlay tier  A dismiss on a surface that covers the screen is a
+   *                    real candidate and its own population disagrees:
+   *                    16, 16, 14 and 18 across four instances of one job.
+   *                    Naming it would write one of the three down and call
+   *                    it a decision.
+   *   a 12px tier      The observed mode, and not a job. It appears on
+   *                    `--inset-control-compact` AND on the 28px control
+   *                    floor, and sits beside a 14 in the same row twice.
+   */
+  --icon-size-control: 14px;
+  --icon-size-standalone: 20px;
+
+  /*
+   * Line height, unitless, named by ROLE rather than by number. The
+   * census showed the values split cleanly by job, not by size: all 25
+   * `line-height: 1` sites are single-line chrome and glyph buttons that
+   * collapse the glyph box, and all 16 `1.5` sites are prose blocks with
+   * no vertical padding. Four roles cover 55 of the 68 declarations
+   * exactly.
+   *
+   * `flush`  glyph and single-line chrome. Collapses the line box so an
+   *          icon or a one-character button centres in a fixed height.
+   *          Never use on anything that can wrap.
+   * `tight`  dense multi-line readouts, label-over-value stacks.
+   * `body`   default for widget text.
+   * `prose`  running paragraphs, help text, banners.
+   */
+  --line-height-flush: 1;
+  --line-height-tight: 1.2;
+  --line-height-body: 1.4;
+  --line-height-prose: 1.5;
+
+  /*
+   * Colour tokens: names match `theme.colors.*` paths in
    * `packages/ui-kit/src/defaultDarkTheme.ts`. The CSS-variable layer is
    * the single source of truth; the JS theme object is a typed handle
    * that reads from these vars (e.g. `var(--color-text-primary)`).
@@ -15,8 +233,8 @@
    */
   --color-text-primary: #ccc;
   --color-text-muted: #888;
-  --color-text-dim: #808080;
-  --color-text-faint: #7a7a7a;
+  --color-text-dim: #858585;
+  --color-text-faint: #838383;
   --color-text-inverse: #050505;
 
   --color-surface-app: #050505;
@@ -30,41 +248,103 @@
   --color-accent-fg: #00ff88;
   --color-accent-bg: #00ff88;
 
-  --color-status-go-fg: #cfe;
-  --color-status-go-bg: #2e5a2e;
-  --color-status-nogo-fg: #ffdede;
-  --color-status-nogo-bg: #ff4d4d;
-  --color-status-warning-fg: #1a1a1a;
-  --color-status-warning-bg: #ff8c00;
-  --color-status-info-fg: #7cf;
-  --color-status-info-bg: #0d0d0d;
-
   /*
-   * Muted variants for status surfaces — used when the alert/warning
-   * state needs a *darker* fill (e.g. error-button background, banner
-   * inset). Distinct from the primary status colours, which are full-
-   * brightness. `alert-muted` covers nogo-tone darks; `warning-bg-muted`
-   * covers warning-tone darks (warm browns / olives).
+   * The tone hues. A palette rung is named nowhere but this file: everything
+   * else reaches a hue through the role token below that says what it is for.
    */
-  --color-status-alert-muted: #4a0e0e;
-  --color-status-warning-bg-muted: #3a2a0a;
+  --palette-green-100: #cfe;
+  --palette-green-500: #3c8050;
+  --palette-green-700: #2e5a2e;
+  --palette-green-900: #0d180d;
+  --palette-red-100: #ffdede;
+  --palette-red-400: #ff4d4d;
+  --palette-red-900: #4a0e0e;
+  --palette-amber-200: #ffd68a;
+  --palette-amber-400: #ff8c00;
+  --palette-amber-600: #8a6a28;
+  --palette-amber-900: #3a2a0a;
+  --palette-blue-300: #7cf;
+  --palette-ink: #1a1a1a;
+
   /*
-   * Warning text + border for warning chips on a *dark* surface — the
-   * `-fg` and `-bg` pair above is for bright orange chips (dark text on
-   * orange); these are the inverse case (light cream text on dark amber).
+   * One tone scale, five roles per tone, so a colour is chosen by the job it
+   * does rather than by which token happened to look right:
+   *
+   *   -text       the tone's words on a surface or on its own muted ground
+   *   -mark       a dot, fill, edge or stroke standing alone, with no text of
+   *               its own: held to 3:1 on the surfaces
+   *   -status     a fill that carries its own text, which is -on-status
+   *   -on-status  the text on that fill
+   *   -muted      a quiet ground under ordinary text
+   *
+   * Text takes the pale tint of a hue and marks the saturated one, since a
+   * saturated hue that clears 3:1 as a mark is too loud to read as prose, and
+   * the pale tint is too faint to carry meaning as a lone dot. go's mark is a
+   * mid green, distinct from both its muted fill and the accent, which means
+   * focus and interaction and never state.
    */
-  --color-status-warning-fg-muted: #ffd68a;
-  --color-status-warning-border-muted: #8a6a28;
+  --color-neutral-text: var(--color-text-primary);
+  --color-neutral-mark: var(--color-text-dim);
+  --color-neutral-status: var(--color-surface-raised);
+  --color-neutral-on-status: var(--color-text-primary);
+  --color-neutral-muted: var(--color-surface-raised);
+
+  --color-info-text: var(--palette-blue-300);
+  --color-info-mark: var(--palette-blue-300);
+  --color-info-status: var(--palette-blue-300);
+  --color-info-on-status: var(--palette-ink);
+  --color-info-muted: var(--color-surface-panel);
+
+  --color-go-text: var(--palette-green-100);
+  --color-go-mark: var(--palette-green-500);
+  --color-go-status: var(--palette-green-700);
+  --color-go-on-status: var(--palette-green-100);
+  /* Kept this dark so --color-text-dim body text stays above 4.5:1 on it; a go card's green is carried by its edge. */
+  --color-go-muted: var(--palette-green-900);
+
+  --color-caution-text: var(--palette-amber-200);
+  --color-caution-mark: var(--palette-amber-200);
+  --color-caution-status: var(--palette-amber-200);
+  --color-caution-on-status: var(--palette-ink);
+  --color-caution-muted: var(--palette-amber-900);
+
+  --color-warn-text: var(--palette-amber-200);
+  --color-warn-mark: var(--palette-amber-400);
+
+  /* The mark of a figure a model carried: held keeps the warn square, a modelled figure draws this blue as a triangle, so the two differ by shape and by hue. */
+  --color-modelled-mark: var(--palette-blue-300);
+  /* The apsides, on an orbit drawing and beside their readouts. Neither is the held amber nor the modelled blue, so an apsis never reads as a mark about how current a figure is. */
+  --color-apoapsis-mark: var(--color-data-12);
+  --color-periapsis-mark: var(--color-data-15);
+  /* The mark of a figure measured now, but of something other than what its label names. Not the held amber, the modelled blue or a go green, so it says nothing about how current the figure is. */
+  --color-elsewhere-mark: var(--color-data-15);
+  --color-warn-status: var(--palette-amber-400);
+  --color-warn-on-status: var(--palette-ink);
+  --color-warn-muted: var(--palette-amber-900);
+  /* The edge of a warn box drawn on its muted ground: decorative, the box's text carries the tone. */
+  --color-warn-muted-edge: var(--palette-amber-600);
+
+  --color-nogo-text: var(--palette-red-100);
+  --color-nogo-mark: var(--palette-red-400);
+  --color-nogo-status: var(--palette-red-400);
+  --color-nogo-on-status: var(--palette-ink);
+  --color-nogo-muted: var(--palette-red-900);
+
+  --color-offline-text: var(--color-text-dim);
+  --color-offline-mark: var(--color-text-dim);
+  --color-offline-status: var(--color-surface-raised);
+  --color-offline-on-status: var(--color-text-dim);
+  --color-offline-muted: var(--color-surface-sunken);
 
   /*
-   * Tag palette — used for *labeled state* with a paired fg / bg /
+   * Tag palette: used for *labeled state* with a paired fg / bg /
    * border surface. Examples: a purple "prediction" chip, a blue
    * station-link badge. Each tag has a fg / bg / border triple.
    *
    * Not for categorical data (chart series, telemetry rows, body
-   * markers) — use the `--color-data-*` palette below for that.
+   * markers): use the `--color-data-*` palette below for that.
    *
-   * Not currently typed in the theme schema — promote when a widely-
+   * Not currently typed in the theme schema, promote when a widely-
    * shared widget begins consuming them programmatically.
    */
   --color-tag-blue-fg: #4488ff;
@@ -83,7 +363,28 @@
   --color-tag-red-fg: #ff4466;
 
   /*
-   * Categorical data palette — used for chart series, telemetry rows,
+   * Attitude and manoeuvre marker palette: the hue KSP paints each navball
+   * marker, so an operator who knows a marker by its colour is not retrained.
+   * These are FACTS about the game, not a design choice, and are not to be
+   * tuned for the surface: the marker glyphs in `@ksp-gonogo/ui-kit`
+   * (`MarkerIcons.tsx`) carry a `currentColor` keyline that supplies the
+   * luminance contrast against either ground, so the hue is free to be the
+   * game's. Stock ships the glyph atlas as a white alpha mask
+   * (`Squad/Props/IVANavBallNoBase/navBall_vectors_IVA.png`) and tints it from
+   * the NavBall prefab; the values here are RasterPropMonitor's stock-matching
+   * tints (`JSIPrimaryFlightDisplay.cs`), converted from Unity `Color` floats.
+   * A pair (prograde/retrograde, normal/anti-normal, radial in/out,
+   * target/anti-target) shares one hue in game and shares one token here:
+   * within a pair, SHAPE carries the distinction.
+   */
+  --color-marker-prograde: #d6fa00;
+  --color-marker-normal: #ed00ff;
+  --color-marker-radial: #00fff4;
+  --color-marker-maneuver: #001dff;
+  --color-marker-target: #ff00ff;
+
+  /*
+   * Categorical data palette: used for chart series, telemetry rows,
    * body markers, and anything where the role is "make this category
    * visually distinct from neighbours". Cycle by index (see
    * packages/components/src/shared/dataPalette.ts).
@@ -92,7 +393,7 @@
    * ~70%+ HSL lightness with high saturation so it reads on
    * `--color-surface-app` through `--color-surface-raised`. Hues span
    * ~360° with adjacent pairs visually distinct. None overlap the
-   * semantic palette (accent green, status orange/red/nogo) — a chart
+   * semantic palette (accent green, status orange/red/nogo): a chart
    * series should never be mistaken for a state indicator.
    */
   --color-data-1: #6cb4ff; /* steel blue */
@@ -121,13 +422,746 @@
   --color-data-24: #f5e07c; /* canary */
 
   --color-focus: #00ff88;
+
+  /*
+   * SPACING LADDER. One ladder for padding, margin AND gap, on a 2px grid
+   * with a 1px `hair` step below it.
+   *
+   * The rungs are raw material for the semantic names below and for nothing
+   * else. Only this file reads them, and only to define a name; every other
+   * file in the repo reads the name, which is enforced by the spacing gate in
+   * packages/core/src/styleguide-widget-spacing.test.ts. A rung says how many
+   * pixels. A name says which job, and the job is what a reader needs and
+   * what a container can change.
+   */
+  --space-hair: 1px;
+  --space-2: 2px;
+  --space-4: 4px;
+  --space-6: 6px;
+  --space-8: 8px;
+  --space-10: 10px;
+  --space-12: 12px;
+  --space-16: 16px;
+  --space-24: 24px;
+
+  /*
+   * SEMANTIC SPACING. Every gap, inset, offset, indent and spacing-derived
+   * size in the app, named for its job.
+   *
+   * A site whose job has no name here gets one: add it to the right family,
+   * defined from the rungs or from another name, and read it. Two sites share
+   * a name only when they do the same job at the same size, so a name is safe
+   * to change for everything that reads it.
+   *
+   * Families, by the axis the space sits on:
+   *   --gap-*     between siblings, as a `gap` or as the margin that stands
+   *               in for one in flow layout
+   *   --inset-*   inside an edge, as `padding`. Two- and three-value insets
+   *               are ordered vertical/horizontal and belong in the
+   *               `padding` shorthand, never `padding-inline`
+   *   --outset-*  outside an edge, as `margin`, where the box and not its
+   *               siblings decides the distance
+   *   --gutter-*  one axis of an inset that several boxes share so their
+   *               content lines up down a column
+   *   --indent-*  a leading inset nesting a child under its parent
+   *   --offset-*  the distance an absolutely positioned box keeps from the
+   *               edge it is pinned to
+   *   --size-*    a box dimension that sits on the spacing grid
+   *
+   * The two context names, --gap-related and --gap-section, STEP: a
+   * container re-declares them from its tier (`Card` is compact, `Panel`
+   * and `Notice` comfortable) and everything inside inherits the new value.
+   * The related tiers run comfortable, compact, dense and packed.
+   * Every other name is a constant. A tier constant read directly
+   * (--gap-related-compact) is the related gap of that tier wherever it
+   * sits, which is how a widget spaces blocks in flow without inheriting a
+   * card's step.
+   *
+   * Every name is declared HERE, at `:root`, and a container only ever
+   * overrides. A name that resolves nowhere computes to nothing and the
+   * declaration is dropped, which for a gap is a silently collapsed layout.
+   */
+
+  /* Context gaps, and the tiers a container steps them to. */
+  --gap-related-comfortable: var(--space-8);
+  --gap-related-compact: var(--space-6);
+  --gap-related-dense: var(--space-4);
+  --gap-related-packed: var(--space-2);
+  --gap-section-comfortable: var(--space-16);
+  --gap-section-compact: var(--space-12);
+  /* Items of the same kind. THE DEFAULT gap. */
+  --gap-related: var(--gap-related-comfortable);
+  /* Groups of different kinds. */
+  --gap-section: var(--gap-section-comfortable);
+
+  /* Lines and readouts. */
+  /* The seam that stops two stacked lines, rows or glyph boxes touching. */
+  --gap-line: var(--space-hair);
+  /* Stacked rows that each carry their own inset. */
+  --gap-rows: var(--space-2);
+  /* A caption, note, detail or wrapped second line directly under its owner. */
+  --gap-caption: var(--space-2);
+  /* A subordinate readout, chip or line under a figure, one step looser. */
+  --gap-sub-readout: var(--space-4);
+  /* Row seam in a label/value readout grid. */
+  --gap-readout-row: var(--space-2);
+  /* Column gap between a label and its value. */
+  --gap-label-value: var(--space-8);
+  /* The same, in a readout squeezed to fit a narrow tile. */
+  --gap-label-value-tight: var(--space-6);
+  /* A value and the tag, chip, unit or caption running beside it. */
+  --gap-value-tag: var(--space-6);
+  /* A label and the figure, separator or suffix it runs straight into. */
+  --gap-lead-figure: var(--space-2);
+  /* A unit symbol set off the figure it qualifies. */
+  --gap-unit-suffix: var(--space-2);
+  /* The parts of one figure: value and unit, or both ends of a range. */
+  --gap-figure-parts: var(--space-4);
+  /* Text and a trailing count, value or distance. */
+  --gap-trailing-figure: var(--space-4);
+  /* Text and a trailing unit, dot, bullet or pill. */
+  --gap-trailing-mark: var(--space-6);
+  /* The horizontal margin either side of a hairline rule between fields. */
+  --gap-rule: var(--space-4);
+  /* A title and the hairline rule drawn under it. */
+  --gap-title-rule: var(--space-4);
+  /* A title or caption and the block it heads. */
+  --gap-under-title: var(--space-4);
+  /* A row's name and its trailing content. */
+  --gap-row: var(--space-8);
+  /* The lines of a row allowed to wrap. */
+  --gap-row-wrap: var(--space-4);
+  /* A headline name and the figure or meta beside it. */
+  --gap-headline: var(--space-10);
+  /* Consecutive readout groups, each already carrying its own section seam. */
+  --gap-readout-groups: var(--space-10);
+  /* Lines of the centred content a tiny tile shows, and a hero value's caption. */
+  --gap-tiny-content: var(--space-4);
+  /* A row meter group stacked on one MeterStack's columns. */
+  --gap-meter-rows: var(--space-2);
+  /* A meter's label, bar and figure columns. */
+  --gap-meter-columns: var(--space-8);
+  /* The four bars of one signal-strength glyph. */
+  --gap-signal-bars: var(--space-2);
+  /* A data line: wrapped rows, then label to value. */
+  --gap-data-line: var(--space-4) var(--space-6);
+  /* A delay legend: wrapped rows, then entries. */
+  --gap-legend: var(--space-4) var(--space-12);
+  /* A contract's reward chips: wrapped rows, then chips. */
+  --gap-rewards: var(--space-2) var(--space-12);
+  /* The two columns of a tag suggestion. */
+  --gap-suggestion-columns: var(--space-12);
+
+  /* Glyphs and controls. */
+  /* A glyph and its label in a compact control, a legend or a tick. */
+  --gap-glyph: var(--space-4);
+  /* A glyph and its label in a full-size control. */
+  --gap-glyph-control: var(--space-6);
+  /* A glyph and its text inside a bordered status or message box. */
+  --gap-glyph-box: var(--space-8);
+  /* Adjacent glyph buttons in a tile header's tray. */
+  --gap-glyph-tray: var(--space-2);
+  /* A pill's glyph and label, and a FAB's label and button. */
+  --gap-pill: var(--space-10);
+  /* A file or screenshot and the name or caption beside it. */
+  --gap-attachment: var(--space-10);
+  /* Controls side by side in a row: form actions, a toolbar, a modal footer. */
+  --gap-control-row: var(--space-8);
+  /* Buttons packed into a grid. */
+  --gap-chips: var(--space-4);
+  /* A stepper's minus, value and plus. */
+  --gap-stepper: var(--space-4);
+  /* A cluster set apart from the cluster before it on one line. */
+  --gap-inline-cluster: var(--space-6);
+  /* A tab strip's tabs. */
+  --gap-tab: var(--space-2);
+  /* A tab strip and the panel it switches. */
+  --gap-tabs-panel: var(--space-12);
+  /* A disclosure trigger and the panel it opens. */
+  --gap-disclosure: var(--space-2);
+  /* A record's lead-in and its name. */
+  --gap-record-lead: var(--space-6);
+  /* The lines inside a free-standing card on a sheet. */
+  --gap-card-lines: var(--space-4);
+
+  /* Forms. */
+  /* A field's label and its input, stacked. */
+  --gap-field-label: var(--space-6);
+  /* The same in a compact field. */
+  --gap-field-label-compact: var(--space-4);
+  /* A label, input and suffix laid out in a row. */
+  --gap-field-label-inline: var(--space-8);
+  /* A read-only field's term and its value. */
+  --gap-field-term: var(--space-12);
+  /* The fields of a form section. */
+  --gap-form-field: var(--space-16);
+  /* The fields of a boxed form. */
+  --gap-form-field-boxed: var(--space-6);
+  /* An extra row hung under a field: a tag list, a screenshot, a listening state. */
+  --gap-under-field: var(--space-6);
+  /* A unit input's stepped parts. */
+  --gap-unit-parts: var(--space-6);
+  /* A heading and the hint line under it. */
+  --gap-heading-hint: var(--space-6);
+
+  /* Blocks in flow. */
+  /* A row of actions closing the block above it. */
+  --gap-actions: var(--space-4);
+  /* The actions at the foot of a card. */
+  --gap-card-actions: var(--space-6);
+  /* A control row closing a list or an editor. */
+  --gap-list-footer: var(--space-2);
+  /* A heading opening the next group in a list. */
+  --gap-list-heading: var(--space-4);
+  /* The next section of the maneuver planner. */
+  --gap-planner-section: var(--space-4);
+  /* A graph series' configuration group. */
+  --gap-config-group: var(--space-4);
+  /* A crew row's contributed meters and the next row. */
+  --gap-crew-meters: var(--space-4);
+  /* A toolbar's rule and the table under it. */
+  --gap-toolbar: var(--space-4);
+  /* A section opening below a rule inside a popover. */
+  --gap-popover-section: var(--space-12);
+  /* A footnote below the list it closes. */
+  --gap-footnote: var(--space-10);
+  /* The mission bar and the screen under it. */
+  --gap-mission-bar: var(--space-8);
+  /* Prose blocks. */
+  --gap-prose: var(--space-10);
+  /* Items of a prose list. */
+  --gap-prose-item: var(--space-4);
+
+  /* Panels. */
+  /* A panel's horizontal gutter, shared by its title, toolbar, body, sidebar
+     and footer so their content lines up down one column. */
+  --gutter-panel: var(--space-16);
+  /* How far a horizontal strip (a tab bar, a wide table) may reach past its
+     box to the panel's edge. A context name: a panel body steps it to its
+     gutter, and a bordered block inside resets it, so nothing bleeds out of a
+     card. */
+  --bleed-inline: 0px;
+  --inset-panel-top: var(--space-8);
+  --inset-panel-bottom: var(--space-12);
+  --inset-panel-body: var(--inset-panel-top) var(--gutter-panel)
+    var(--inset-panel-bottom);
+  /* The inset a panel steps down to when it has little room to give: a lone
+     framed drawing under a narrow container (a hairline of panel surface
+     either side of the frame's own border, so the panel's edge and the
+     frame's read as two lines rather than one thick one), and the tiny
+     hover-title panel's own edge (the same narrow-panel case; it is always
+     that narrow, so it takes the step unconditionally rather than under a
+     container query). */
+  --inset-tiny: var(--space-6);
+  /* A sidebar's top inset when it sits UNDER the body: the body's bottom
+     inset is already above it, so the full panel top would double the gap
+     between a drawing and the readouts that annotate it. */
+  --inset-panel-sidebar-under: var(--space-4);
+  /* No bottom inset: the body's own gap is the only space between the header and the content. */
+  --inset-panel-header: 0 var(--gutter-panel);
+  /* Above a hand-composed header row; inside a Panel the rail band is that inset. */
+  --inset-panel-header-top: var(--space-6);
+  --inset-panel-toolbar: var(--space-6) var(--gutter-panel) 0;
+  --inset-panel-footer: var(--space-6) var(--gutter-panel) var(--space-8);
+  /* A panel header's title and its aside. */
+  --gap-panel-header: var(--space-8);
+  /* Items in a panel header's aside. */
+  --gap-panel-aside: var(--space-4);
+  /* Sections side by side in a panel body. */
+  --gap-panel-columns: var(--space-16);
+  /* Sections stacked in a panel body's grid. */
+  --gap-panel-sections: var(--space-12);
+  /* The height of a panel's full-bleed trend strip along its bottom edge. */
+  --size-panel-trend: var(--space-24);
+  /* The least height a filling Section keeps when its siblings take the rest; the panel body scrolls past it. */
+  --size-section-fill-floor: calc(var(--space-24) * 4);
+  /* The band every panel reserves at its top edge for the delay rail. */
+  --panel-rail-band: var(--space-16);
+
+  /* Command delay. */
+  /* The strips around a panel's commands, on the panel gutter. */
+  --outset-command-strip: var(--space-4) var(--gutter-panel);
+  /* The delay stream's legend, on the panel gutter. */
+  --outset-delay-legend: 0 var(--gutter-panel) var(--space-4);
+  --gap-delay-stream: var(--space-4);
+  --gap-delay-rail: var(--space-8);
+  --gap-rail-summaries: var(--space-8);
+  --offset-rail-hint: var(--space-4);
+  /* How far the collapse hint's click target reaches past its glyph. */
+  --outset-rail-hint-target: var(--space-8);
+  --gap-message-stack: var(--space-4);
+  --inset-command-list: var(--space-4) var(--space-8);
+  --gap-command-list-column: var(--space-8);
+  --gap-command-list-row: var(--space-2);
+  --gap-command-row: var(--space-6);
+
+  /* Surfaces. */
+  /* A bordered or filled box that holds content: a card, a record, a popover body. */
+  --inset-surface: var(--space-6) var(--space-8);
+  /* A card that IS its screen, holding its own controls. */
+  --inset-surface-standalone: var(--space-10) var(--space-12);
+  /* A label sized by its text: a badge, a pill, an inline code span. */
+  --inset-chip: var(--space-hair) var(--space-6);
+  /* The same on a larger badge. */
+  --inset-chip-roomy: var(--space-hair) var(--space-8);
+  /* A chip that carries a live reading. */
+  --inset-chip-readout: var(--space-2) var(--space-8);
+  /* A single-token status pill, and a message pill that shares its shape. */
+  --inset-pill: var(--space-6) var(--space-12);
+  /* A floating or full-width banner on the 16px gutter. */
+  --inset-banner: var(--space-8) var(--space-16);
+  /* An alert band that spans the app or a menu. */
+  --inset-alert-band: var(--space-10) var(--space-16);
+  /* A bordered status box sized to --control-height. */
+  --inset-status-box: var(--space-4) var(--space-8);
+  /* A popover's content. */
+  --inset-popover: var(--space-8);
+  /* A tooltip's content. */
+  --inset-tooltip: var(--space-4) var(--space-8);
+  /* The drop between an anchor and the popover it opens. */
+  --offset-popover: var(--space-4);
+  /* A popover shadow's offset and blur. */
+  --shadow-popover-drop: 0 var(--space-4) var(--space-12);
+  /* Visual content held inside a FramedDisplay. */
+  --inset-framed-display: var(--space-4);
+  /* A panel sharing a FramedDisplay slot, whose frame draws the edge. */
+  --inset-frame-panel: var(--space-8) var(--space-10);
+  /* A box pinned into its container's corner. */
+  --offset-corner: var(--space-4);
+  /* A graph notice pinned over the plot's bottom-left corner, and its inset. */
+  --offset-graph-notice-bottom: var(--space-4);
+  --offset-graph-notice-left: var(--space-8);
+  --inset-notice-pill: var(--space-2) var(--space-4);
+  /* A caption inlaid on a FramedDisplay's own top-left corner. */
+  --offset-frame-caption-top: var(--space-6);
+  --offset-frame-caption-left: var(--space-8);
+  /* A footer line inlaid on a FramedDisplay's own bottom-left corner. */
+  --offset-frame-footer-bottom: var(--space-6);
+  --offset-frame-footer-left: var(--space-8);
+
+  /* Controls. */
+  /* A box you press or type into, on the --control-height floor. */
+  --inset-control: var(--space-6) var(--space-12);
+  /* The same class in a box that cannot reach the floor. */
+  --inset-control-compact: var(--space-hair) var(--space-4);
+  /* The same class standing on its own, one tier above the floor. */
+  --inset-control-prominent: var(--space-8) var(--space-12);
+  /* A small button, toggle or chip control. */
+  --inset-control-small: var(--space-2) var(--space-8);
+  /* The coarse-pointer widening of a control. */
+  --inset-control-touch: var(--space-8) var(--space-16);
+  /* The coarse-pointer widening of a small control. */
+  --inset-control-small-touch: var(--space-6) var(--space-10);
+  /* A chromeless glyph button. */
+  --inset-glyph-button: var(--space-2) var(--space-4);
+  /* A glyph button in a row, padded across only. */
+  --inset-glyph: 0 var(--space-4);
+  /* The same, packed tight against the row's text. */
+  --inset-glyph-tight: 0 var(--space-2);
+  /* A square icon-only button. */
+  --inset-icon-button: var(--space-6);
+  --inset-icon-button-compact: var(--space-4);
+  --inset-icon-button-tight: var(--space-2);
+  --inset-icon-button-touch: var(--space-8);
+  /* A command group's commit button. */
+  --inset-commit-button: var(--space-4) var(--space-12);
+  /* A compact button in a form's footer. */
+  --inset-form-footer-button: var(--space-4) var(--space-10);
+  /* A glyph button in a dense grid, taller than wide. */
+  --inset-warp-button: var(--space-6) var(--space-4);
+  /* A text button inside a FAB prompt. */
+  --inset-prompt-button: 0 var(--space-12);
+  /* A file picker's button on a coarse pointer. */
+  --inset-file-button-touch: var(--space-10) var(--space-16);
+  /* A momentary button on the virtual pad. */
+  --inset-pad-button: var(--space-10) 0;
+  /* A stepper's buttons and value. */
+  --inset-stepper: var(--space-4) var(--space-8);
+  --size-stepper-button: var(--space-24);
+  /* A switch label's touch target. */
+  --inset-switch-touch: 0 var(--space-6);
+  /* A segmented control's track. */
+  --inset-segment-track: var(--space-2);
+  /* A tab strip's track, and the selection blob inside it. */
+  --inset-tab-track: var(--space-4);
+  --inset-tab-compact: var(--space-4) var(--space-6);
+  --inset-tab-compact-touch: var(--space-4) var(--space-8);
+  /* A jog wheel's content, and its value label. */
+  --inset-jog-wheel: var(--space-4);
+  --inset-jog-wheel-compact: var(--space-2);
+  --inset-jog-wheel-label: 0 var(--space-2);
+  /* The room a Meter figure keeps for the held mark drawn outside it. */
+  --inset-meter-mark: var(--space-6);
+
+  /* Fields. */
+  --inset-field: var(--space-6) var(--space-8);
+  --inset-field-compact: var(--space-4) var(--space-6);
+  --inset-field-touch: var(--space-10) var(--space-12);
+  /* The trailing room a search field keeps for its clear control. */
+  --inset-field-clearable-end: calc(var(--icon-size-control) + var(--space-12));
+  /* The trailing room a select keeps for its drawn arrow. */
+  --inset-field-select-end: var(--space-24);
+  /* The two strokes of a select's arrow: each one's size, and how far each sits from the field's end. */
+  --size-select-arrow: var(--space-4);
+  --offset-select-arrow-near: var(--space-12);
+  --offset-select-arrow-far: var(--space-16);
+  /* A boxed form's surface. */
+  --inset-form-box: var(--space-8) var(--space-10);
+  /* A search input flush in its band. */
+  --inset-search-input: var(--space-4) 0;
+
+  /* Menus, lists and tables. */
+  --inset-menu-list: var(--space-4) 0;
+  --inset-menu-item: var(--space-6) var(--space-8);
+  /* A group label, hugging the items under it. */
+  --inset-menu-group-label: var(--space-8) var(--space-8) var(--space-4);
+  --inset-empty-menu: var(--space-12) var(--space-8);
+  --inset-row: var(--space-2) 0;
+  --inset-row-pressable: var(--space-4) var(--space-6);
+  /* A row picked from a select-one list. */
+  --inset-selectable-row: var(--space-2) var(--space-4);
+  /* A nested row under its parent. */
+  --indent-row: var(--space-12);
+  /* A line of text flush in its container, given a little vertical room. */
+  --inset-line: var(--space-2) 0;
+  /* A part row in a dense parts list. */
+  --inset-part-row: var(--space-hair) 0;
+  /* A label/value row in an expanded detail. */
+  --inset-detail-row: var(--space-4) 0;
+  /* A section header lined up with the toggles beside it. */
+  --inset-list-heading: var(--space-2) var(--space-4);
+  --gutter-table-cell: var(--space-8);
+  --inset-table-cell: var(--space-4) var(--gutter-table-cell);
+  --inset-table-section: var(--space-6) var(--gutter-table-cell);
+  --inset-table-detail: 0 var(--gutter-table-cell) var(--space-6);
+  --inset-table-empty: var(--space-8);
+  --inset-table-footer: var(--space-10) var(--gutter-table-cell) var(--space-4);
+  /* A narrow column header, taller than wide. */
+  --inset-table-narrow-header: var(--space-6) var(--space-4);
+  /* A reach table's cells. */
+  --inset-reach-cell: var(--space-2) var(--space-4);
+  /* A fleet roster cell, and the contributed lines hung under its row. */
+  --gutter-roster-cell: var(--space-6);
+  --inset-roster-cell: 0 var(--gutter-roster-cell);
+  /* A transfer window row and the expander under it, sharing one gutter. */
+  --gutter-window-row: var(--space-12);
+  --inset-window-row: var(--space-8) var(--gutter-window-row);
+  --inset-window-expander: var(--space-8) var(--gutter-window-row)
+    var(--space-4);
+  /* A tech node's expanded body, under the node row's own inset. */
+  --inset-node-body: var(--space-4) var(--space-10) var(--space-8);
+  /* A tech-graph card, sized against its fixed card height. */
+  --inset-graph-card: var(--space-4) var(--space-8);
+  /* The vessel switch panel. */
+  --inset-switch-panel: var(--space-2);
+  /* The spacing around a reveal toggle at a list header. */
+  --outset-reveal-toggle: var(--space-2) var(--space-2) var(--space-4);
+
+  /* Rules. */
+  /* Content opening below a divider rule. */
+  --inset-below-rule: var(--space-6);
+  /* A footnote below its rule. */
+  --inset-footnote-rule: var(--space-8);
+  /* A toolbar above its bottom rule. */
+  --inset-toolbar-bottom: var(--space-10);
+
+  /* Messages and empty states. */
+  /* A message that fills its container. */
+  --inset-empty-state: var(--space-16);
+  /* A message that fills a tile: an error, a placeholder, a no-data note. */
+  --inset-tile-message: var(--space-12);
+  /* A one-line "nothing here" note in a list. */
+  --inset-empty-note: var(--space-8) 0;
+  --inset-empty-roster: var(--space-6) 0;
+  --inset-empty-modal-list: var(--space-12) 0;
+  --inset-empty-popover: var(--space-16) 0;
+  --inset-chart-empty: var(--space-24) 0;
+  /* A widget's refusal to draw. */
+  --inset-refusal: var(--space-8);
+  /* A message standing in for a whole screen. */
+  --inset-screen-message: var(--space-24);
+  /* A stand-in box with no content of its own. */
+  --inset-placeholder: var(--space-8);
+  /* Contributed plots, framed by themselves. */
+  --inset-contributed-plots: var(--space-8) 0;
+  /* The maneuver planner's shortfall banner. */
+  --inset-feasibility-banner: var(--space-6) var(--space-10);
+  /* A bordered inline confirmation bar. */
+  --inset-confirm-bar: var(--space-10);
+
+  /* Screens, overlays and modals. */
+  /* A screen's outer gutter, before any safe-area inset. */
+  --gutter-screen: var(--space-24);
+  /* The gutter of a widget screen whose children draw no edge of their own; the panel pads the sides. */
+  --gutter-screen-body: var(--space-8) 0;
+  /* The dashboard grid's gutter between tiles. */
+  --gutter-dashboard: var(--space-8);
+  /* A tile's drag header. */
+  --inset-tile-header: 0 var(--space-4);
+  /* A dialog that stands alone over the app. */
+  --inset-dialog: var(--space-24);
+  --inset-modal-bar: var(--space-12) var(--space-16);
+  --inset-modal-body: var(--space-16);
+  /* The bands of a full-surface overlay, on one gutter. */
+  --gutter-overlay: var(--space-16);
+  --inset-overlay-band: var(--space-12) var(--gutter-overlay);
+  --inset-overlay-heading: var(--space-6) var(--gutter-overlay);
+  --inset-overlay-chips: var(--space-10) var(--gutter-overlay);
+  --inset-overlay-empty: var(--space-24) var(--gutter-overlay);
+  /* A reference sheet's header and body. */
+  --inset-reference-sheet: var(--space-10) var(--space-16);
+  /* The mission bar. */
+  --inset-mission-bar: 0 var(--space-2);
+  /* The Go/No-Go board. */
+  --inset-gonogo-board: var(--space-12);
+  /* A QR code's quiet zone. */
+  --inset-qr: var(--space-12);
+  /* A settings row, and a nested settings row. */
+  --inset-settings-row: var(--space-6) 0;
+  --indent-settings: var(--space-16);
+  /* The chapter editor's band. */
+  --inset-chapters-band: var(--space-10) var(--space-12) var(--space-12);
+  /* A device-picker row. */
+  --inset-picker-row: var(--space-6) 0;
+  /* A wizard, and the boxes inside it. */
+  --inset-wizard: var(--space-12);
+  --inset-wizard-box: var(--space-8);
+  /* A virtual device's frame buffer. */
+  --inset-device-display: var(--space-8);
+  /* The virtual pad's centre mark, off its track's ends. */
+  --offset-pad-mark: var(--space-4);
+  /* An inline code run in a banner. */
+  --inset-code-inline: 0 var(--space-2);
+  /* A free-standing sheet of cards, and a card on it. */
+  --inset-sheet: var(--space-12);
+  --inset-sheet-card: var(--space-8) var(--space-12);
+
+  /* Consoles and logs. */
+  /* A scrolling log's inner inset. */
+  --inset-log: var(--space-8);
+  /* A console's foot, and the chips pinned to its edges. */
+  --inset-console-foot: var(--space-8);
+  /* The foot's top when a reading straddles the composer's border. */
+  --inset-console-foot-straddled: var(--space-16);
+  --gap-console-foot: var(--space-6);
+  --gap-console-readings: var(--space-6);
+  --gap-composer: var(--space-6);
+  /* The prompt glyph and the line typed after it. */
+  --gap-prompt-glyph: var(--space-8);
+
+  /* Indents and marks. */
+  /* A contributed aside or detail under the row it belongs to. */
+  --indent-aside: var(--space-8);
+  /* The burn axis, off the row's leading edge. */
+  --indent-burn-axis: var(--space-8);
+  --size-burn-axis: var(--space-12);
+  --size-burn-mark: var(--space-6);
+  /* A short mark rather than a rule: a card's identity tab, a threshold tick. */
+  --size-mark: var(--space-24);
+  /* The height a comms hop keeps with no detail to show. */
+  --size-comms-hop: var(--space-16);
+  /* The gauge bar under a tiny tile's figure: the figure and the bar share a content box barely taller than the figure. */
+  --size-tiny-gauge: var(--space-2);
+
+  /*
+   * RADIUS. Three jobs plus two shape sentinels.
+   *
+   * The ladder was `xs`/`sm`/`md`/`lg` at 2/3/4/6px, which answered
+   * "which number" and nothing else, the same t-shirt complaint already
+   * ruled on for spacing. Measured over its 515 sites: `xs` (236) and
+   * `sm` (140) do not separate at all, buttons and inputs take both, and
+   * `md` (28) mostly joins them. One name covers all three, and every
+   * site moves by at most a pixel.
+   *
+   *   regular  Every ordinary corner in the app: chips, badges, buttons,
+   *            inputs, rows, cells, swatches, cards, menus, dropdowns.
+   *            400+ sites, and there was never a rule distinguishing
+   *            them.
+   *   floating A box that sits ABOVE the app rather than in it. Eight of
+   *            `lg`'s nine sites were already exactly that population
+   *            (`Modal`, three consent/reference modals, `Fab`,
+   *            `HostedLanding`, `GoNoGo`, the in-flight queue panel), so
+   *            this names a job the ladder was already being used for by
+   *            accident. It pairs deliberately with the `z` ladder's
+   *            floating rungs: a thing that floats wants both, and a
+   *            reader reaching for one should reach for the other.
+   *   display-frame
+   *            `FramedDisplay`'s corner, and only that. Bigger than
+   *            everything else on purpose: it is what separates a box
+   *            that is LOOKED AT from a box that is READ, which the kit
+   *            asserted in a doc comment and nowhere in its pixels while
+   *            a frame and a card were both drawn at 3px.
+   *
+   *            Named for the frame rather than for "visual", so the next
+   *            ambiguous box cannot reach for it and feel justified. It
+   *            is a container external belonging to ONE container.
+   *
+   *            It STEPS, which is what makes it a custom property rather
+   *            than a constant: `Block`'s side asides re-declare it, so
+   *            a frame holding a 40px avatar in a record's left aside
+   *            takes a corner proportioned to that box without the frame
+   *            knowing its own size. Content asks, context answers, the
+   *            same mechanism `--gap-related` uses.
+   *
+   * `pill` and `circle` are SHAPES, not sizes. 50% is a circle on a
+   * square box; 999px clamps to exactly half the shorter side, so it
+   * renders identically to a hand-computed half-height while surviving a
+   * change to that height. Every stadium in the codebase (the 7px switch
+   * track, the 10px chip, the 12px filter chip, the 20px and 24px FAB
+   * prompts) should reach for `pill` rather than recomputing the half.
+   * Neither sentinel belongs on the numeric ramp.
+   */
+  --radius-regular: 3px;
+  --radius-floating: 6px;
+  --radius-display-frame: 8px;
+  /* What `Block`'s side asides step --radius-display-frame to. */
+  --radius-display-frame-aside: 4px;
+  --radius-pill: 999px;
+  --radius-circle: 50%;
+
+  /*
+   * CONTROL HEIGHT. One rung, and one is the point of it.
+   *
+   * Every boxed control in the kit used to take its height from whatever was
+   * inside it: a small toggle around a 14px glyph came out at 20px, the same
+   * toggle around a word at 17, a bordered status readout at 27 and a default
+   * button at 30. Put four of them in a row, which is what a widget bar IS, and
+   * the row is visibly ragged with no one declaration to blame. Commcast's
+   * radio bar is where the operator finally said so.
+   *
+   * So `size` on a control chooses its type scale and its inset, never its
+   * height: a control is a control-shaped box. Read it as a `min-height` so
+   * genuinely taller content (a wrapped label, a coarse-pointer target) still
+   * grows the box rather than clipping inside it, and pair it with
+   * `--line-height-flush` so a line box's unused descender headroom is not what
+   * decides whether a control clears the floor.
+   *
+   * 28px is where the two commonest controls in the app already sat, so this
+   * lifts the small ones to meet them rather than moving everything. The check
+   * that it is high enough, worth writing down because a floor a control
+   * OVERSHOOTS is a floor that does nothing for it: a default Button is
+   * 12 inset + 2 border + a 14px glyph = 28, a small ToggleButton 4 + 2 + 14 =
+   * 20, and a StatusIndicator 8 + 2 + 11px text at a 1.4 line height = 25.4.
+   * Every one of them lands on the floor. The indicator is why its own inset
+   * came down a rung; at the old one it cleared 28 and stayed the odd box out.
+   * Coarse pointers ignore all of this and take the 44px touch target.
+   *
+   * A box that cannot reach this floor at all is a different case from one
+   * that undershoots it. Ten pressable glyphs and chips would OVERFLOW what
+   * holds them at 28: an 18px drag header, a note whose whole one-line body is
+   * about that tall, a fixed overlay with a logged history of swallowing the
+   * clicks underneath it. They take `--inset-control-compact` above, and each
+   * names the box it is stuck inside.
+   */
+  --control-height: 28px;
+
+  /*
+   * Z-INDEX, as named layers rather than a numeric ramp.
+   *
+   * Only app-global chrome belongs here. Roughly half the z-index
+   * declarations in the repo (the 0/1/2, 5/6 and 10/20 families) are
+   * LOCAL sibling ordering inside one component's own stacking context,
+   * where the absolute number is meaningless and only the relative order
+   * matters. Those stay literal; pulling them onto this ladder would
+   * collapse several independent contexts into one and can invert either
+   * pair.
+   *
+   * The order below is derived from what the app does today, with two
+   * deliberate corrections where today's numbers are already inverted:
+   *
+   *   base      0      default flow.
+   *   sticky    100    in-flow chrome that pins while content scrolls
+   *                    (the replay session bar, sticky table headers).
+   *   dropdown  200    popovers anchored to a control (combobox, tag
+   *                    autocomplete, the science-augment menu). MUST
+   *                    outrank sticky: a select opened next to a pinned
+   *                    bar has to render over it. One of these menus
+   *                    currently sits at 20 and renders BEHIND the
+   *                    sticky bar; this rung is the fix.
+   *   overlay   800    full-surface overlays that replace the dashboard
+   *                    (pushed dashboard, station overlay).
+   *   fab       900    the bottom-right floating control cluster.
+   *                    Strictly BELOW backdrop: the FAB opens the
+   *                    backdrop and must be covered by it.
+   *   backdrop  950    the scrim behind a modal. Covers the FAB, sits
+   *                    under the dialog surface.
+   *   modal     1000   dialog surfaces.
+   *   toast     1100   transient notifications. ABOVE modal on purpose:
+   *                    an alarm or offline banner has to reach the
+   *                    operator even while a dialog is open. The banner
+   *                    stack sits at 90 today, which renders it behind
+   *                    the FAB it is positioned beside.
+   *   critical  10000  consent gates. Deliberately far off the ramp;
+   *                    a consent surface may never be occluded.
+   */
+  --z-base: 0;
+  --z-sticky: 100;
+  --z-dropdown: 200;
+  --z-overlay: 800;
+  --z-fab: 900;
+  --z-backdrop: 950;
+  --z-modal: 1000;
+  --z-toast: 1100;
+  --z-critical: 10000;
+
+  /*
+   * MOTION. Durations and easings for UI transitions only.
+   *
+   * The census splits cleanly into two populations. 52 declarations are
+   * UI transitions (hover, focus, open, close) in the 60ms to 400ms
+   * band; 19 are PHYSICAL animation, where the duration encodes
+   * something real: a resource bar tied to the telemetry sample cadence,
+   * a reticle chasing a moving target, a 1Hz terminal caret, a spinner,
+   * an indicator whose 1s-versus-2s period is how the operator reads
+   * connection state. Those keep their literal values and their
+   * `linear` / `step-end` timing; folding them onto a UI scale would
+   * destroy information the widget is deliberately carrying.
+   *
+   *   instant   80ms   binary state flips, the visual echo of a press.
+   *   fast      120ms  small property changes: colour, border, opacity.
+   *   base      150ms  THE DEFAULT for a UI transition.
+   *   slow      200ms  larger moves: a panel expanding, a row sliding.
+   *   entrance  320ms  paired with `--ease-entrance`; the banner
+   *                    entrance recipe, always used together.
+   *
+   *   standard  the default curve for a UI transition.
+   *   emphasis  symmetric, for looping attention pulses.
+   *   linear    continuous physical motion. Required, not stylistic: an
+   *             eased bar fill appears to stall between samples.
+   *   entrance  an overshoot tuned to a 40px slide with
+   *             `transform-origin: right center`. Do not substitute a
+   *             generic ease-out; it changes the physical read.
+   *
+   * These tokens do NOT opt anything out of the reduced-motion damper in
+   * `packages/app/src/styles/global.css`, which clamps every duration to
+   * 0.01ms under `prefers-reduced-motion: reduce`. Indefinite animations
+   * still need their own `@media (prefers-reduced-motion: no-preference)`
+   * guard, and the `animation` shorthand must stay INSIDE that guard
+   * with its keyframes.
+   */
+  --duration-instant: 80ms;
+  --duration-fast: 120ms;
+  --duration-base: 150ms;
+  --duration-slow: 200ms;
+  --duration-entrance: 320ms;
+
+  --ease-standard: ease;
+  --ease-emphasis: ease-in-out;
+  --ease-linear: linear;
+  --ease-entrance: cubic-bezier(0.22, 1, 0.36, 1);
 }
 
 @media (pointer: coarse) {
   :root {
+    --font-size-2xs: 11px;
     --font-size-xs: 12px;
     --font-size-sm: 13px;
     --font-size-base: 15px;
     --font-size-lg: 17px;
+
+    /* The step a raw size prop cannot have. A Fab already grows its own box
+       40 -> 48 here; without this its glyph stayed behind. */
+    --icon-size-control: 15px;
+    --icon-size-standalone: 24px;
   }
 }