@appinternalleads/ui 0.2.0

package/src/tokens/tokens.ts

@@ -0,0 +1,1180 @@
+import { Platform as RNPlatform, type BackgroundImageValue } from 'react-native';
+
+/**
+ * Design tokens — **WARM PAPER**, ported from the design project's
+ * `tokens/colors.css` and `tokens/materials.css` (August 2026).
+ *
+ * This replaced a pine-green-on-glass system. If you are reading a comment that mentions
+ * substrates, specular rims, blur, five user accents or a dark scope, it predates the
+ * shift and is wrong.
+ *
+ * **The one rule: the page is paper and objects sit ON it.** Depth is a soft drop shadow
+ * plus a hairline — never a fill that differs from the page, never transparency, never
+ * blur. Three consequences, and they are the whole material system:
+ *
+ * 1. **All surfaces are the same white.** A card tinted away from the page reads as a
+ *    highlight, and once everything is highlighted nothing is. Separation is shadow.
+ * 2. **A field is a hole, not an object.** Inputs never lift. Focus darkens the hairline;
+ *    there is no colour ring anywhere.
+ * 3. **Nothing is translucent, so nothing needs a fallback.** The reduced-transparency
+ *    path is gone because it is now the only path — a simplification, not a loss.
+ *
+ * Two things did NOT survive the shift, and both are real feature losses:
+ * **dark mode** (warm neutrals do not invert — the result is muddy khaki, not a dark
+ * theme) and **the five user accents**. Both are recorded as open gaps upstream.
+ */
+
+/**
+ * Kept as a type so call sites compile, but there is exactly one mode. A dark theme here
+ * needs its own ramp, not a transform of this one; until it exists, a dark system setting
+ * is answered by staying light.
+ */
+export type Mode = 'light';
+export type Surface = 'ios' | 'android';
+
+/**
+ * **Which palette an app is painted in.**
+ *
+ * `paper` is the warm-paper system every screen was built against. `solarium` is the reskin
+ * specified by `design_handoff_ambi` — the Canvas OS system from the `solarium` repo, whose
+ * values are transcribed here from its `globals.css` `:root` block.
+ *
+ * A THEME rather than a replacement, and that is forced by the constraint
+ * `design/AMBI-SURFACES.md` states in its own words: *Ambi does not own its design system —
+ * `@comppack/ds` is shared with Key and Build. A change to a token is a change to all three.*
+ * Overwriting the palette would silently reskin the keyboard app and app 3, neither of which
+ * asked for it. Selecting it per app is the only way to reskin one.
+ *
+ * `paper` stays the default, so an app that says nothing keeps exactly what it has.
+ */
+export type Theme = 'paper' | 'solarium';
+
+/** The four shortcut kinds. Kind colour is allowed ONLY inside the leading chip. */
+export type Kind = 'text' | 'action' | 'flow' | 'media';
+/**
+ * Status always carries a word. The dot beside it is redundant by design.
+ *
+ * **`needsUser`, added for the KeyShort revamp (D3, 11 Sep 2026).** Everything else here is a
+ * report — what a run did. This one is a request — what a run is waiting on the user for — and
+ * reads as a fourth semantic rather than a shade of `error`, because nothing failed. CLAUDE.md's
+ * old "one red, no warning tone" rule is now "one red, one warning": `error` stays the only red,
+ * `needsUser` is the warning.
+ */
+export type Status = 'executed' | 'running' | 'queued' | 'error' | 'needsUser';
+
+export type KindPair = { bg: string; fg: string };
+
+/** A tinted chip: a ground and the ink that reads on it. */
+export type TonePair = { bg: string; fg: string };
+
+export type Colors = {
+  /**
+   * Terracotta. Alias of the accent — they are the same colour now. It survives so
+   * components written against the pine system keep working; read nothing more into it.
+   */
+  brandPrimary: string;
+  brandOnPrimary: string;
+  brandSubtle: string;
+
+  /** The primary button, the active tab, step badges. One hue, one job. */
+  accentFill: string;
+  accentOnFill: string;
+  /**
+   * Accent TEXT is always this, never `accentFill`. The fill measures 4.71:1 on pure
+   * white but 4.19:1 on the page and 3.92:1 on its own tint — safe only as a background.
+   */
+  accentInk: string;
+  /** Behind an active glyph, a binding chip, a selected state. */
+  accentTint: string;
+  accentPressed: string;
+  /**
+   * **`--alert-soft` — the ground of a terminal failure. C7, decided 2026-09-18.**
+   *
+   * The pair that finally gives "Failed" a token of its own. Until C7 every failure fell back to
+   * apricot (`status.needsUser`), whose meaning is "needs attention, nothing is broken" — an overload
+   * that blurred the one distinction this system otherwise keeps. `alertSoft` is a GROUND;
+   * `alertInk` is its INK and the only legal text colour on it. Global, not output-scoped:
+   * this is the one place the values are defined. Measured (see `tests/alertTokens.test.tsx`):
+   * ink on soft 6.44:1, on card 7.85:1, on page 7.5:1.
+   */
+  alertSoft: string;
+  /** `--alert-ink`. Text, glyph or 1px border for a failure — never a fill. */
+  alertInk: string;
+
+  textPrimary: string;
+  textSecondary: string;
+  /**
+   * **The one deliberate contrast exemption in the system, and it is a knowing one.**
+   *
+   * 2.63:1 on the page, 2.96:1 on white — under the 3.0 floor for even large or incidental
+   * text. The Dashboard handoff states that failure in its own accessibility section, adopts
+   * the value anyway, and scopes it: *"permitted only for 13pt+ day headers, counters and
+   * timestamps"*. It asks for the discrepancy to be flagged to design, not overruled here.
+   *
+   * So: eyebrows, timestamps, roll-ups, hints, day labels. **Never anything a user must read
+   * to act** — those take `textSecondary` at 4.89:1.
+   *
+   * This was briefly `#8A8279` on a miscount of mine. Counting hexes across the whole design
+   * bundle put `#8A8279` ahead 143 to 71, but 127 of those came from `CANVAS2099.dc.html` —
+   * the *composite* document, which re-renders every frame from the shared token sheet. It
+   * double-counts the same screens. The per-screen frames are unambiguous: the Dashboard file
+   * uses `#9C958C` 32 times and `#8A8279` zero times.
+   */
+  textTertiary: string;
+  /**
+   * A glyph that is present but unavailable — the run row's caret, a disabled chevron.
+   *
+   * 1.57:1 on the page, so it is **never** legible text and must never carry a word. The
+   * Dashboard handoff names it for exactly one job: *"disabled glyphs (the row caret)"*.
+   */
+  textDisabled: string;
+  textOnAccent: string;
+
+  /** The flat stop the page gradient ends on. Anything that must match the page uses it. */
+  surfacePage: string;
+  /** Rows, cards, sheets. */
+  surface1: string;
+  /** Tab bar, nav bar. */
+  surface2: string;
+  /** Dialogs. */
+  surface3: string;
+  /**
+   * The host tray, read-only value boxes, chip grounds, **and skeleton fills**.
+   *
+   * A skeleton painted in this reads as loading only when it sits **inside a white shell** —
+   * on the page it is within 3% of the ground and disappears. That is a structural rule, not
+   * a colour one: a loading row keeps its card and skeletonises the contents.
+   */
+  surfaceSunken: string;
+  /**
+   * §17's `band` — the **unknown-state** tone, and the keyboard's bar.
+   *
+   * One step darker than `surfaceSunken`, which is what separates *we do not know* from the
+   * settled quiet of skipped and cancelled. It exists because §12 needs a tone that is neither
+   * success green nor error red: a step that timed out after its request had left may well have
+   * landed, and a red pill would say "nothing happened".
+   */
+  band: string;
+
+  hairline: string;
+  hairlineStrong: string;
+  /**
+   * **`--control-border` — the outline of a control you operate, not of a surface you read.**
+   *
+   * Checkbox and radio rims, a switch's off track, a dropzone's dashes, a pending step node.
+   * `hairline`/`hairlineStrong` are 1.1–1.3:1 by design — they separate surfaces, and a control
+   * drawn in them fails WCAG 1.4.11's 3:1 for "the visual information required to identify" it.
+   * This is the slot that clears it. Added by `design_handoff_solarium_blocks_case_studies`
+   * (2026-09-23); see `docs/HANDOFF-SOLARIUM-BLOCKS.md` §2. Measured in
+   * `tests/solariumTokens.test.ts`. Never text — it is a rim, and it only just clears 3:1.
+   */
+  controlBorder: string;
+  /**
+   * The automation rail. `bound` marks the segment above a step that reads from an
+   * earlier one — terracotta, because a binding is the thing the user authored.
+   */
+  rail: { default: string; bound: string };
+  /** "Add a step" and other additive outlines. */
+  dashed: string;
+
+  kind: Record<Kind, KindPair>;
+  /** A connector slug, an API constant, a run id — any string the machine owns. */
+  reference: TonePair;
+  /** A skill or named ability, as distinct from a connector. */
+  capability: TonePair;
+  status: Record<Status, string>;
+  /** The ground each status word sits on when it is rendered as a chip. */
+  statusBg: Record<Status, string>;
+};
+
+/* ── The one palette ─────────────────────────────────────────────────────── */
+
+const ios: Colors = {
+  brandPrimary: '#C1502E',
+  brandOnPrimary: '#FFFFFF',
+  brandSubtle: '#F7E7DE',
+
+  accentFill: '#C1502E',
+  accentOnFill: '#FFFFFF',
+  accentInk: '#A8421F',
+  accentTint: '#F7E7DE',
+  alertSoft: '#FBE3E5',
+  alertInk: '#9C2229',
+  accentPressed: '#7E2F14',
+
+  // Warm charcoal, never neutral grey — against paper a true grey reads blue and dirties
+  // the whole page.
+  textPrimary: '#2A2724',
+  textSecondary: '#6E6862',
+  textTertiary: '#9C958C',
+  textDisabled: '#C9C2B8',
+  textOnAccent: '#FFFFFF',
+
+  surfacePage: '#F6F1E9',
+  surface1: '#FFFFFF',
+  surface2: '#FFFFFF',
+  surface3: '#FFFFFF',
+  surfaceSunken: '#F3F0EA',
+  band: '#EFE9E0',
+
+  hairline: 'rgba(42, 39, 36, 0.08)',
+  hairlineStrong: 'rgba(42, 39, 36, 0.14)',
+  /* Paper names no control border. `#8A8279` is not invented: it is the paper design bundle's
+     own second-tier grey (see `textTertiary`'s note), and the lightest of paper's warm greys that
+     clears 3:1 on every paper ground — 3.78 white, 3.37 page, 3.33 sunken, 3.14 band. */
+  controlBorder: '#8A8279',
+  rail: { default: 'rgba(42, 39, 36, 0.08)', bound: 'rgba(193, 80, 46, 0.40)' },
+  dashed: 'rgba(42, 39, 36, 0.14)',
+
+  // None of the four is terracotta and none is green, so a kind can never be misread as
+  // the accent or as a completion state.
+  kind: {
+    text: { bg: '#F3F0EA', fg: '#6E6862' },
+    action: { bg: '#FBF3D8', fg: '#8A6D12' },
+    flow: { bg: '#EFEBF9', fg: '#6B5BA8' },
+    media: { bg: '#E6E0FB', fg: '#3F6296' },
+  },
+  // Periwinkle is the same family as kind-media on purpose: both mean "not your words".
+  reference: { bg: '#E6E0FB', fg: '#3F6296' },
+  capability: { bg: '#EFEBF9', fg: '#6B5BA8' },
+
+  // Green lives here and ONLY here. In the pine system it was the identity colour AND the
+  // completion colour, so it could never be spent freely. Giving the accent its own hue is
+  // what lets green mean exactly one thing.
+  status: {
+    executed: '#2C7247',
+    running: '#8A6D12',
+    queued: '#6E6862',
+    error: '#A33224',
+    // Paper has no apricot family — never has (see `solariumHues`'s own note on this). Rather
+    // than invent one for a semantic paper's own handoffs have never asked for, this aliases
+    // `running`: paper's existing "warm, not alarming" tone is the nearest thing it already
+    // owns to a warning, and reusing it is honest about paper having no dedicated rung here.
+    //
+    // `design_handoff_output_blockers` (2026-09-17) fixes `--apricot-deep` from `#A75F2E` to
+    // `#94501F` — a contrast defect (4.05:1 on its own fill, below the 4.5:1 floor). That fix is
+    // scoped to the token that IS apricot-deep, which is solarium's `needsUser` below, not this
+    // one: this value was never apricot, it's `running`'s own hex, untouched by the fix.
+    needsUser: '#8A6D12',
+  },
+  // `running` here is #F8F3D8 and `kind.action` above is #FBF3D8 — one digit apart, and
+  // deliberately so. They were the same value until the Dashboard handoff listed them
+  // separately; an earlier reconciliation of mine had counted them as one token.
+  statusBg: {
+    executed: '#DEEFE2',
+    running: '#F8F3D8',
+    queued: '#F3F0EA',
+    error: '#F8E4E0',
+    needsUser: '#F8F3D8',
+  },
+};
+
+/**
+ * **Colour no longer diverges.** The pine system had to resolve Android's accent back to
+ * green, because M3 has no black-primary convention to accommodate an inversion.
+ * Terracotta is a legitimate M3 primary, so one accent rule covers both platforms now.
+ *
+ * What still diverges is elevation: M3 is tonal, so `surface2` lifts slightly off the page
+ * instead of floating, and the lift ladder collapses (see `liftFor`).
+ */
+const android: Colors = { ...ios, surface2: '#FBF9F5' };
+
+/* ── Solarium ────────────────────────────────────────────────────────────── */
+
+/**
+ * **The Canvas OS palette, transcribed from `solarium/src/app/globals.css`.**
+ *
+ * Every hex below is a Solarium token, named here by the job the design system already has
+ * a name for. Nothing is invented; where Solarium is silent the derivation is called out on
+ * the line itself, because a value nobody can trace is a value the next person re-picks.
+ *
+ * The two systems are closer than the reskin implies — warm paper's terracotta is `#C1502E`
+ * and Solarium's coral is `#C1552C`, three digits apart. What actually changes is the
+ * GROUND (a cooler, brighter porcelain), the tint family (six hues rather than four kinds),
+ * and the elevation, which loses its inset ring.
+ */
+const solariumIos: Colors = {
+  /* --coral. Alias of the accent, as in paper. */
+  brandPrimary: '#C1552C',
+  brandOnPrimary: '#FFFFFF',
+  /* --coral-soft: the bulk picker's selected row, and the disabled primary. */
+  brandSubtle: '#F6E3D7',
+
+  accentFill: '#C1552C',
+  accentOnFill: '#FFFFFF',
+  /* --coral-deep. Accent TEXT is never the fill — the same rule paper states. */
+  accentInk: '#A8461F',
+  /* --coral-tint: selected chips, your own chat bubbles, the bottom of the page gradient. */
+  accentTint: '#FBF0E8',
+  /* --alert-soft / --alert-ink — C7. The palette had no red; this pair is it. */
+  alertSoft: '#FBE3E5',
+  alertInk: '#9C2229',
+  /* Solarium names no pressed state. Derived by the same darkening paper used, held one
+     step below `--coral-deep` so a press is visible against it. */
+  accentPressed: '#7E3315',
+
+  /* --ink */
+  textPrimary: '#2C2E2A',
+  /* --muted. Solarium has ONE secondary tone and uses it for metadata as well. */
+  textSecondary: '#6B6D63',
+  /**
+   * **Solarium has no third text tone, and this is the one derived value that matters.**
+   *
+   * `--neutral` is the closest thing it names and is a fill, not an ink. Paper's tertiary is
+   * a deliberate, documented contrast exemption scoped to eyebrows, timestamps and day
+   * labels; Solarium's handoff puts all of those in `--muted` instead. So tertiary resolves
+   * to `--neutral` and every call site that used it for text is expected to move to
+   * `textSecondary` as its screen is reskinned — which is what the handoff's typography
+   * table already specifies.
+   */
+  textTertiary: '#B9B7AD',
+  /* --neutral, lightened toward --line. A glyph that is present but unavailable. */
+  textDisabled: '#CFCDC4',
+  textOnAccent: '#FFFFFF',
+
+  /* --ground: the flat stop the page gradient ends on. */
+  surfacePage: '#FBFAF7',
+  /* --card */
+  surface1: '#FFFFFF',
+  surface2: '#FFFFFF',
+  surface3: '#FFFFFF',
+  /* --well: recessed rows, icon tiles, the unselected mode chip. */
+  surfaceSunken: '#F7F5EE',
+  /* --line-soft. One step past the well, for the unknown state. */
+  band: '#F1EFE7',
+
+  /* --line-soft for dividers, --line for the grabber and input-chip borders. Opaque in
+     Solarium rather than an alpha over the ground, so they are quoted as-is. */
+  hairline: '#F1EFE7',
+  /* --line, Solarium 0.2.0: `#E6E4DF`. Was `#E7E4DA` (the output handoff's value) until 2026-09-24;
+     0.2.0 states `--line` explicitly, and it is the design authority. */
+  hairlineStrong: '#E6E4DF',
+  /* --control-border, verbatim. 3.33:1 on --card, 3.19 on --ground, 3.05 on --well. Below 3:1
+     (2.89) on --line-soft, so a control never sits on `band`. */
+  controlBorder: '#8F8D84',
+  rail: { default: '#F1EFE7', bound: 'rgba(193, 85, 44, 0.40)' },
+  dashed: '#E6E4DF',
+
+  /**
+   * **The four kinds map onto four of Solarium's six hues.**
+   *
+   * Solarium's hue system is `{ --h, --hd, --hs }` per family and a tile reads *the current
+   * hue* generically. The DS models the same thing as a bg/fg pair, so each kind takes that
+   * hue's `soft` and `deep`. `action` is butter because the handoff draws the suggested
+   * shortcut's lightning tile in `--butter-soft`.
+   */
+  kind: {
+    /* `--well`, not `.h-neutral`'s soft. The handoff draws the run row's tile as `--well`
+       specifically, and a neutral tile on a white card is the one place the two differ
+       visibly — six units, but the design names one of them. */
+    text: { bg: '#F7F5EE', fg: '#6B6D63' },
+    action: { bg: '#FAF0D2', fg: '#7D5F14' },
+    flow: { bg: '#EEEBF7', fg: '#5F5099' },
+    media: { bg: '#E6EEF5', fg: '#39648A' },
+  },
+  /* Sky, matching the handoff's text-selection highlight and connector tile variety. */
+  reference: { bg: '#E6EEF5', fg: '#39648A' },
+  capability: { bg: '#EEEBF7', fg: '#5F5099' },
+
+  /**
+   * **`error` is clay, and that is design's answer to the flag this block used to carry.**
+   *
+   * The previous note here said `error` was coral because the Ambi handoff listed
+   * `did not finish` under `--coral` alongside the active tab and the primary button — so a
+   * failed run and the thing you are meant to tap were literally the same hex, and the note
+   * flagged it to design rather than overruling it. `design_handoff_ambi_chat_duplex`
+   * answers it in as many words: *"Clay carries every failed state in Ambi"*, and coral is
+   * reserved for the microphone, the primary action and the active tab. The flag is
+   * discharged; failure has its own family again, exactly as paper's `#A33224` gave it one.
+   *
+   * **Why `--clay-deep #96502F` and not `--clay #D98E73`.** This token is read as INK far more
+   * often than as a fill — 49 direct reads in this app, and all but five pass it to a
+   * `Text` colour. `--clay` measures 2.60:1 on white and 2.19:1 on its own soft ground: not
+   * legible text under any threshold, in a role whose entire job is to be read. `--clay-deep`
+   * is 6.03:1 on white and 5.06:1 on `--clay-soft`, both comfortably past 4.5. It is also an
+   * improvement on the coral it replaces, which only ever managed 4.56:1 on white and 3.83:1
+   * on a soft ground. `--clay` itself is not lost — it is `solariumHues.clay`, for the strokes
+   * and bars that are fills rather than words.
+   *
+   * The change is visible and intended: every run row, failure widget, danger button and
+   * "won't work" chip in this app moves from coral to clay. Two comments elsewhere in the
+   * codebase were written assuming this separation already existed and were silently wrong
+   * until now — `ListeningCard`'s End button calls itself *"the single red in the system. Not
+   * the accent"* while painting itself in the accent, and `TrendStrip` reasons about "a short
+   * red bar beside tall terracotta ones" when both bars were the same hex.
+   */
+  status: {
+    executed: '#2F6B4F',
+    running: '#7D5F14',
+    queued: '#6B6D63',
+    /* --clay-deep */
+    error: '#96502F',
+    /* --apricot-deep. Was `solariumHues.apricotDeep` — moved rather than duplicated, same as
+       clay above: a status word should read its colour from `status`, not from a hue export
+       that happens to hold the same hex. See D3 in `turbo-waddle-key/tasks/KEYSHORT-REVAMP.md`.
+       Corrected from `#A75F2E` to `#94501F` by `design_handoff_output_blockers` (2026-09-17,
+       TOKENS-OUTPUT.md §1.2): the original measured 4.05:1 on its own fill (`--apricot`
+       `#FBE7D3`), below the 4.5:1 floor — every low-confidence chip and error tile in the output
+       system shipped below threshold. `#94501F` measures 5.10:1 on apricot, 6.13:1 on card.
+       Global, not output-scoped — this is the one place the value is defined. */
+    needsUser: '#94501F',
+  },
+  statusBg: {
+    executed: '#DCF0E4',
+    running: '#FAF0D2',
+    queued: '#F7F5EE',
+    /* --clay-soft. Was `--coral-tint`, which is also the page gradient's bottom stop — an
+       error chip that matches the ground under the composer is not a chip. */
+    error: '#F9E8E0',
+    /* --apricot */
+    needsUser: '#FBE7D3',
+  },
+};
+
+/** Same divergence paper makes: M3 lifts the bar off the page rather than floating it. */
+const solariumAndroid: Colors = { ...solariumIos, surface2: '#FDFCFA' };
+
+/**
+ * **The Solarium tokens the `Colors` shape has nowhere to put — and nothing else.**
+ *
+ * Solarium names eight hue families of up to four rungs each. `Colors` is one shape shared by
+ * paper and Solarium, and its slots are named by JOB (`accentTint`, `kind.action`,
+ * `statusBg.executed`) rather than by hue, so most of those rungs already live somewhere
+ * above under a different name. This holds only the leftovers.
+ *
+ * **Every hex defined here is defined nowhere else in this file.** That is the rule the
+ * object exists to enforce, and it is not pedantry: the moment `--sky-soft` is also spelled
+ * `solariumHues.skySoft`, a reskin that moves `kind.media` leaves the alias behind and two
+ * things that were meant to be one colour quietly drift apart. So when the rung you want is
+ * missing here, it is missing because it is already reachable — the map is:
+ *
+ * | Solarium | already in `Colors` as |
+ * |---|---|
+ * | `--coral` / `-deep` / `-soft` / `-tint` / `--on-coral` | `accentFill` / `accentInk` / `brandSubtle` / `accentTint` / `accentOnFill` |
+ * | `--butter-soft` / `--butter-deep` | `kind.action.bg` / `.fg`, and `statusBg.running` / `status.running` |
+ * | `--sky-soft` / `--sky-deep` | `kind.media` and `reference` |
+ * | `--lilac-soft` / `--lilac-deep` | `kind.flow` and `capability` |
+ * | `--neutral` / `-deep` / `-soft` | `textTertiary` / `textSecondary` / `band` (and `hairline`) |
+ * | `--mint` / `--mint-deep` | `statusBg.executed` / `status.executed` |
+ * | `--clay-deep` / `--clay-soft` | `status.error` / `statusBg.error` — see the note there |
+ * | `--apricot` / `--apricot-deep` | `statusBg.needsUser` / `status.needsUser` — added by D3, same reasoning as clay |
+ * | `--control-border` | `controlBorder` — Building Blocks handoff, 2026-09-23, in both palettes |
+ * | `--alert-soft` / `--alert-ink` | `alertSoft` / `alertInk` — C7, decided 2026-09-18: the terminal-failure pair, in both palettes |
+ * | `--ground` / `--card` / `--well` / `--ink` / `--muted` / `--line` / `--line-soft` | `surfacePage` / `surface1` / `surfaceSunken` / `textPrimary` / `textSecondary` / `hairlineStrong` / `hairline` |
+ *
+ * Which leaves four things: the mid rung of clay, butter, sky and lilac — the four families
+ * that reached `Colors` only as a soft/deep pair, because a hue's mid tone is a stroke or a
+ * bar and no `Colors` slot is a stroke. And `--on-butter`, which is not `--butter-deep`.
+ *
+ * **Apricot entire used to be the fifth thing here** — Solarium named it and this palette had
+ * never carried it under any name — until D3 (11 Sep 2026) promoted it into `Colors.status` as
+ * `needsUser`. It is removed below for the reason `clayDeep`/`claySoft` were never added here in
+ * the first place: once a hue's pair reads through a status word, keeping a second, hue-named
+ * copy is exactly the drift this comment's second paragraph warns about.
+ *
+ * **A separate export rather than a field on `Colors`, for the reason `solariumRadii` is
+ * one:** paper has no clay and no apricot, and widening the shared shape would force it to
+ * invent two families it does not have. The name is the guard — a paper app that reaches for
+ * `solariumHues` can see in the identifier that it is reaching outside its own system.
+ */
+export const solariumHues = {
+  /**
+   * **Failure, and only failure.** `clayDeep` and `claySoft` are NOT repeated here — they are
+   * `status.error` and `statusBg.error`, which is where a failed run should be reading its
+   * colour from anyway. This is the mid rung: the 1px rule down a failure bubble, the alert
+   * glyph's stroke, a full-height bar in a trend strip. Never text — 2.60:1 on white.
+   */
+  clay: '#D98E73',
+
+  /** The mid rung of the gate hue — the padlock's stroke, not its ground. 1.83:1 on white. */
+  butter: '#E9B949',
+  /**
+   * `--on-butter`, and deliberately not `--butter-deep` (`#7D5F14`, which is `kind.action.fg`).
+   * Solarium names both because they do different jobs: the deep rung is a LABEL on the soft
+   * tint, this is ink on `--butter` itself. Substituting one for the other is not a nuance —
+   * on that ground the deep rung measures 3.27:1 and this one 5.91:1, so the wrong pick puts
+   * the gate's own words under the legibility floor.
+   */
+  onButter: '#4D3B0B',
+
+  /** Mid rungs. Their soft and deep rungs are `kind.media`/`reference` and `kind.flow`/`capability`. */
+  sky: '#6E9FC4',
+  lilac: '#9C8FD0',
+} as const;
+
+/**
+ * Solarium's elevation, which is a pure drop shadow — **no inset ring**.
+ *
+ * That is the visible difference from paper, whose every lift begins `0 0 0 1px`. Android
+ * still collapses to a hairline, which Solarium's own handoff states in the same words:
+ * *on Android, `lift-2` collapses to a hairline and rows group with dividers instead.*
+ *
+ * **Rungs 1 and 2 ARE `--lift-1` and `--lift-2`**, character for character — the chat-duplex
+ * handoff names the same two recipes it already carried, so there was nothing to add and
+ * re-entering them under the CSS names would have given each shadow two spellings. Read the
+ * handoff's assignments onto these: `--lift-1` on white cards and bubbles (rung 1, which is
+ * also `edgeFor`), `--lift-2` on the voice surface and the conversations drawer (rung 2).
+ *
+ * **Butter and clay turns carry NO shadow — the tint is the elevation.** There is no rung 0
+ * and there must not be one: a token whose value is "nothing" invites a call site to ask for
+ * elevation and receive it silently. A gate or failure bubble simply omits `boxShadow`.
+ *
+ * **On the two forms React Native wants.** RN 0.86 takes a CSS `boxShadow` string, and that
+ * is this file's only shadow vocabulary — 135 call sites pass these strings straight through,
+ * and there is not one `shadowColor` or `shadowOffset` in the repo. The iOS/Android split is
+ * therefore made HERE, by `liftFor` choosing between two string ladders, rather than at a
+ * call site branching on platform; `elevation` never appears because a tonal `elevation` and
+ * a drop shadow would both be applied on Android and double the lift. Adding a
+ * `{ shadowColor, shadowOffset, shadowOpacity, shadowRadius, elevation }` object for these
+ * two rungs was the obvious alternative and was rejected for exactly that reason: it would be
+ * a second, competing way to say the same thing, and the 135 existing sites would not move.
+ */
+const SOLARIUM_IOS_LIFT: Record<Lift, string> = {
+  /* --lift-1, Solarium 0.2.0's FLATTENED value — a card is a 1px line-soft border plus this. Was the
+     Ambi handoff's two-part shadow until 2026-09-24; 0.2.0 is the design authority. */
+  1: '0 1px 2px rgba(44,46,42,.05)',
+  /* --lift-2 */
+  2: '0 2px 4px rgba(44,46,42,.05), 0 16px 40px rgba(44,46,42,.11)',
+  /* Solarium names two rungs. Dialogs need a third; extrapolated on the same curve. */
+  3: '0 4px 8px rgba(44,46,42,.06), 0 28px 64px rgba(44,46,42,.15)',
+};
+
+const SOLARIUM_ANDROID_LIFT: Record<Lift, string> = {
+  1: '0 0 0 1px rgba(44,46,42,0.06)',
+  2: '0 1px 3px rgba(44,46,42,0.12)',
+  3: '0 4px 12px rgba(44,46,42,0.16)',
+};
+
+
+
+/**
+ * **The keyboard focus ring — Solarium 0.2.0, mandatory (onboarding PRD §1.7).**
+ *
+ * A 1px accent edge plus a 3px accent-soft halo: the handoff's `border-color: --coral` +
+ * `box-shadow: 0 0 0 3px --coral-soft`, drawn entirely as box-shadow so it needs no border on the
+ * element and cannot shift layout. Built from the palette, so paper gets its own accent and nothing
+ * here is a new hex. It REPLACES the old "no colour focus ring anywhere" rule (2026-09-24,
+ * `docs/DECISIONS.md` §2): that rule is what the ThresholdFlow audit failed on.
+ *
+ * Shown on `:focus-visible` for controls (keyboard focus — `core/focusVisible` decides) and on any
+ * focus for text fields (`:focus-within` in the handoff), where the caret is not enough.
+ */
+export function focusRingFor(colors: Colors): string {
+  return `0 0 0 1px ${colors.accentFill}, 0 0 0 4px ${colors.brandSubtle}`;
+}
+
+/** The example in the colour field's invalid-hex message. Lives here because it is a hex. */
+export const HEX_EXAMPLE = '#1F6FEB';
+
+/** There is one palette. The signature keeps its shape so call sites do not churn. */
+export function paletteFor(_mode: Mode, surface: Surface, theme: Theme = 'paper'): Colors {
+  if (theme === 'solarium') return surface === 'android' ? solariumAndroid : solariumIos;
+  return surface === 'android' ? android : ios;
+}
+
+/* ── The lift ladder ─────────────────────────────────────────────────────── */
+
+/**
+ * Each level is a hairline plus a two-part shadow: a tight contact shadow that keeps the
+ * edge crisp, and a wide soft one that does the lifting. Both are needed — one alone
+ * either looks stuck down or looks like it is floating away.
+ *
+ * **There is no fourth level.** If something seems to need one it needs different spacing.
+ *
+ * **Never add a light-coloured outer shadow.** That single move is what reads as
+ * neumorphism, and it is the specific thing this system has now replaced twice over.
+ */
+export type Lift = 1 | 2 | 3;
+
+const IOS_LIFT: Record<Lift, string> = {
+  1: '0 0 0 1px rgba(42,39,36,0.07), 0 1px 2px rgba(42,39,36,0.04), 0 10px 24px -16px rgba(42,39,36,0.30)',
+  2: '0 0 0 1px rgba(42,39,36,0.07), 0 2px 4px rgba(42,39,36,0.05), 0 14px 30px -14px rgba(42,39,36,0.40)',
+  3: '0 0 0 1px rgba(42,39,36,0.07), 0 4px 8px rgba(42,39,36,0.06), 0 24px 48px -20px rgba(42,39,36,0.45)',
+};
+
+// M3 uses tonal elevation rather than a shadow ladder: containers group rows with dividers
+// instead of floating each one, so level 1 reduces to a hairline.
+const ANDROID_LIFT: Record<Lift, string> = {
+  1: '0 0 0 1px rgba(42,39,36,0.06)',
+  2: '0 1px 3px rgba(42,39,36,0.12)',
+  3: '0 4px 12px rgba(42,39,36,0.16)',
+};
+
+export function liftFor(surface: Surface, level: Lift = 1, theme: Theme = 'paper'): string {
+  if (theme === 'solarium') {
+    return (surface === 'android' ? SOLARIUM_ANDROID_LIFT : SOLARIUM_IOS_LIFT)[level];
+  }
+  return (surface === 'android' ? ANDROID_LIFT : IOS_LIFT)[level];
+}
+
+/**
+ * The lift for a card sitting **inside** another card's sunken tray, rather than on the page.
+ *
+ * Tighter than level 1 — `-14px`/`.28` against its `-16px`/`.30`. The difference is small and
+ * it is the whole point: a widget frame using the page-level shadow reads as floating above
+ * the tray instead of resting in it, which undoes the separation the tray exists to draw.
+ *
+ * Android collapses to the same hairline as level 1, because M3 groups with dividers rather
+ * than stacking shadows and a second inset shadow there reads as a seam.
+ */
+export function liftInner(surface: Surface): string {
+  return surface === 'android'
+    ? ANDROID_LIFT[1]
+    : '0 0 0 1px rgba(42,39,36,0.07), 0 1px 2px rgba(42,39,36,0.04), 0 8px 20px -14px rgba(42,39,36,0.28)';
+}
+
+/**
+ * The ONE coloured shadow in the system, and it exists because the primary button is the
+ * one coloured object that floats.
+ */
+export const liftAccent = '0 6px 16px -8px rgba(193, 80, 46, 0.80)';
+
+/** Theme-aware `liftAccent` — paper's `#C1502E` vs Solarium's `#C1552C`; see `authFocusRingFor`. */
+export function liftAccentFor(theme: Theme = 'paper'): string {
+  return theme === 'solarium' ? '0 6px 16px -8px rgba(193, 85, 44, 0.80)' : liftAccent;
+}
+
+/**
+ * A field is a hole in the paper, not an object on it, so it **never lifts**.
+ * Focus darkens the hairline from 9% to 28% — there is no colour focus ring anywhere.
+ */
+export const fieldEdge = {
+  default: '0 0 0 1px rgba(42,39,36,0.09), 0 1px 2px rgba(42,39,36,0.04)',
+  focus: '0 0 0 1px rgba(42,39,36,0.28), 0 1px 2px rgba(42,39,36,0.05)',
+  error: '0 0 0 1px #A33224',
+} as const;
+
+/**
+ * **Home's command field, which keys its ring off CONTENT rather than focus.**
+ *
+ * Not a second opinion about `fieldEdge` — a different state machine. Every other field in
+ * the product darkens on focus and returns when focus leaves; Home's dock darkens when the
+ * field **has something in it, or is in Build mode**, and stays dark whether or not the
+ * caret is there. That is deliberate: the dock is the subject of the tab, so its ring says
+ * *this field is carrying something* rather than *you are typing here*.
+ *
+ * There is no focus ring at all, which is why both steps are so close together. The field is
+ * not competing with the results above it, and an accent ring on a screen whose only accent
+ * is the mode chip and the mic would put the eye in the wrong place.
+ */
+export const commandEdge = {
+  rest: '0 0 0 1px rgba(42,39,36,0.07), 0 1px 2px rgba(42,39,36,0.04)',
+  filled: '0 0 0 1px rgba(42,39,36,0.14), 0 1px 2px rgba(42,39,36,0.04)',
+} as const;
+
+/**
+ * A sign-in door — a white button that carries a provider mark and floats slightly.
+ *
+ * Heavier at the edge than `lift1` (14% against 7%) because a door is pressed rather than read:
+ * it has to look like an object with a boundary, not a card holding content. The soft half is
+ * tighter too (`-14px`/`.28` against `-16px`/`.30`), which keeps three stacked doors from reading
+ * as one drifting mass.
+ */
+export const doorEdge = {
+  primary:
+    '0 0 0 1px rgba(42,39,36,0.14), 0 1px 2px rgba(42,39,36,0.04), 0 8px 20px -14px rgba(42,39,36,0.28)',
+  secondary: '0 0 0 1px rgba(42,39,36,0.12)',
+} as const;
+
+/**
+ * **The one accent focus ring in the product, and it is a knowing exception.**
+ *
+ * This file states plainly that a field is a hole and that "focus darkens the hairline; there is
+ * no colour ring anywhere". The sign-in handoff (August 2026) specifies one anyway, twice, and the
+ * second use is why it is adopted rather than overruled: on the code field the ring sits on the
+ * **next empty box** and *is* the caret — there is no text cursor to see, so the ring has to carry
+ * position, and a darker hairline reads as a heavier border rather than as "you are here".
+ *
+ * Scoped to sign-in. Every other field in the product keeps `fieldEdge`, and this must not spread
+ * — flag it to design rather than quietly generalising it.
+ */
+export const authFocusRing = '0 0 0 1.5px rgba(193, 80, 46, 0.45)';
+export const authFieldRing = '0 0 0 1px rgba(42, 39, 36, 0.12)';
+
+/**
+ * **Theme-aware versions of `authFocusRing`/`authFieldRing`/`doorEdge`, for an app on Solarium.**
+ *
+ * The three constants above are evaluated at import time against paper's exact hex
+ * (`accentFill` `#C1502E`, `textPrimary` `#2A2724`) and cannot themselves become theme-aware —
+ * the same reason `lift1`/`lift2` are exposed through `useDs()` rather than imported directly
+ * (see `DsProvider.tsx`'s own note). Solarium's values are three digits apart (`accentFill`
+ * `#C1552C`, `textPrimary` `#2C2E2A`), which the sign-in and onboarding screens never picked up
+ * because nothing routed them there — the auth focus ring and every door's edge rendered a few
+ * RGB units off from where Solarium's own accent and ink actually sit.
+ *
+ * Kept as separate functions rather than changing the constants' type: `canvas-app` imports
+ * `authFieldRing`/`authFocusRing`/`doorEdge` directly as plain strings (`parity.test.ts`), so
+ * turning them into functions would be a breaking change to a consumer outside this repo.
+ */
+export function authFocusRingFor(theme: Theme = 'paper'): string {
+  return theme === 'solarium' ? '0 0 0 1.5px rgba(193, 85, 44, 0.45)' : authFocusRing;
+}
+export function authFieldRingFor(theme: Theme = 'paper'): string {
+  return theme === 'solarium' ? '0 0 0 1px rgba(44, 46, 42, 0.12)' : authFieldRing;
+}
+export function doorEdgeFor(theme: Theme = 'paper'): { primary: string; secondary: string } {
+  if (theme !== 'solarium') return doorEdge;
+  return {
+    primary:
+      '0 0 0 1px rgba(44,46,42,0.14), 0 1px 2px rgba(44,46,42,0.04), 0 8px 20px -14px rgba(44,46,42,0.28)',
+    secondary: '0 0 0 1px rgba(44,46,42,0.12)',
+  };
+}
+
+/**
+ * **A button that is drawn rather than filled** — an outline on the page colour, with no lift.
+ *
+ * The secondary half of a pair whose primary is sunken or accent-filled: Home's `Dismiss`
+ * beside `Copy`, and the save bar's `✕` beside `Save`. Heavier than a card's hairline at 12%
+ * against 7–9%, because it has to read as an edge you can press rather than as the boundary of
+ * a surface.
+ */
+export const outlineEdge = '0 0 0 1px rgba(42,39,36,0.12)';
+
+/** Theme-aware `outlineEdge` — same reason and same shape as `authFieldRingFor`. */
+export function outlineEdgeFor(theme: Theme = 'paper'): string {
+  return theme === 'solarium' ? '0 0 0 1px rgba(44,46,42,0.12)' : outlineEdge;
+}
+
+/**
+ * Compatibility alias. The pine system called the card treatment `edge` and most
+ * components still ask for it; it resolves to lift-1.
+ */
+export function edgeFor(_mode: Mode, surface: Surface, theme: Theme = 'paper'): string {
+  return liftFor(surface, 1, theme);
+}
+
+/** Search-field focus. Kept for call sites; the edge IS the focus indicator. */
+export function focusEdgeFor(_mode: Mode): string {
+  return fieldEdge.focus;
+}
+
+/* ── The page ────────────────────────────────────────────────────────────── */
+
+/**
+ * Three stops — cool green-grey at the top drifting warm toward the bottom, the way a
+ * sheet lit from one side reads.
+ *
+ * This is the ONE thing carried over from the glass system, and its justification changed
+ * completely: there it existed so blur had something to refract, here it is simply the
+ * warmth of the paper. **Keep it subtle** — if you can name it as a gradient at arm's
+ * length it is too strong. Full-bleed, never scrolls independently, never interactive.
+ */
+export function substrateFor(_mode?: Mode, theme: Theme = 'paper'): readonly BackgroundImageValue[] {
+  /**
+   * **Solarium's page is one vertical gradient, and it ends on the accent tint.**
+   *
+   * `linear-gradient(180deg, --well, --ground 45%, --coral-tint)` — warm-neutral at the top,
+   * faintly warmer at the bottom. Straight down rather than paper's 168deg: the handoff
+   * specifies 180 and the whole point of the stop order is that the warmth collects under
+   * the composer, which an angle would smear sideways.
+   */
+  if (theme === 'solarium') {
+    return [
+      {
+        type: 'linear-gradient',
+        direction: '180deg',
+        colorStops: [
+          { color: '#F7F5EE', positions: ['0%'] },
+          { color: '#FBFAF7', positions: ['45%'] },
+          { color: '#FBF0E8', positions: ['100%'] },
+        ],
+      },
+    ];
+  }
+  return [
+    {
+      type: 'linear-gradient',
+      direction: '168deg',
+      colorStops: [
+        { color: '#F3F6EF', positions: ['0%'] },
+        { color: '#F8F4ED', positions: ['46%'] },
+        { color: '#F6F1E9', positions: ['100%'] },
+      ],
+    },
+  ];
+}
+
+/**
+ * The keyboard composites opaquely for its frame budget, which cost the glass system a
+ * whole baked-material pipeline. On paper that is simply what the surfaces already are —
+ * the extension renders what every other surface renders.
+ */
+export const keyboard = {
+  surface: '#FFFFFF',
+  surfaceAlt: '#E7E2D9',
+  bar: '#F6F1E9',
+  bed: '#E4DED4',
+  edge: '0 1px 1.5px rgba(42, 39, 36, 0.16)',
+} as const;
+
+/**
+ * The ladder pre-resolved for this platform. There is one palette and the platform is
+ * fixed at runtime, so a module constant is honest here — and it lets a module-scope
+ * `StyleSheet.create` block carry a lift without threading anything through.
+ */
+/**
+ * ⚠ **Theme-blind, and nothing in this app should import them any more.**
+ *
+ * They are evaluated at import time — before an app has had the chance to say which theme it
+ * wants — so they are always `paper`'s elevation, whatever the provider was told. The
+ * theme-aware reads are `useDs().lift1`, `.lift2` and — for level 3 — `.edge3`.
+ *
+ * ⚠ **This block used to claim every call site in the repo had already moved, and that was
+ * false for `lift3`.** `HomeSheet` and `ConfirmCard` still imported the constant, so the home
+ * sheet, the build panel's sheet and the canvas confirm card all drew PAPER's level 3 inside an
+ * app mounted `theme="solarium"` (App.tsx). Not a near-miss: paper level 3 opens with a
+ * `0 0 0 1px` hairline ring and closes on a tight `0 24px 48px -20px …0.45`, where solarium has
+ * no ring at all and a wide, soft `0 28px 64px …0.15`. Both now read `edge3`.
+ *
+ * There is deliberately no `useDs().lift3`. Level 3 has lived on the context as `edge3` since
+ * before this ladder was named, `RunSheet` already reads it, and a fourth synonym for one value
+ * in a file that already carries `edge`≈`lift1` and `edge2`≈`lift2` would make the confusion
+ * that caused this bug worse rather than better.
+ *
+ * Kept exported only because the two sibling apps' copies of this package still import them and
+ * are still on paper, where the values are correct. Delete them when those repos are synced.
+ */
+export const lift1 = liftFor(RNPlatform.OS === 'android' ? 'android' : 'ios', 1);
+export const lift2 = liftFor(RNPlatform.OS === 'android' ? 'android' : 'ios', 2);
+export const lift3 = liftFor(RNPlatform.OS === 'android' ? 'android' : 'ios', 3);
+
+/**
+ * The one true drop shadow inside a platform-owned control: the iOS switch thumb. The
+ * redesign does not reach inside it.
+ */
+export const switchThumb = [
+  { offsetX: 0, offsetY: 2, blurRadius: 4, color: 'rgba(0, 0, 0, 0.28)', inset: false },
+];
+
+/* ── Geometry ────────────────────────────────────────────────────────────── */
+
+export const radii = {
+  key: 10,
+  chip: 8,
+  control: 14,
+  card: 20,
+  sheet: 28,
+  pill: 999,
+  cardAndroid: 16,
+  controlAndroid: 999,
+  // Legacy rungs. `key`, `card` and `pill` already exist above with v2 values, so
+  // call sites naming those get the new geometry automatically.
+  field: 8,
+  pillSm: 10,
+  search: 11,
+  row: 12,
+  button: 13,
+  sheetIos: 14,
+  iconTile: 18,
+  dialogMd: 28,
+  screen: 35,
+  bezel: 44,
+} as const;
+
+/**
+ * Solarium's radii, by the names this system already uses.
+ *
+ * Sheets take `26px` — the handoff calls that out as an iOS/Android platform value rather
+ * than a Solarium token, so it is quoted here with that provenance rather than folded into
+ * the ladder as if the design system had chosen it.
+ *
+ * **Chat bubbles are not on this ladder, and no rung should be added for them.** The
+ * chat-duplex handoff states it directly: bubbles use literal asymmetric radii, not tokens —
+ * agent `18 18 18 6`, yours `18 18 6 18`, the voice surface a uniform `26`. The asymmetry is
+ * the point (the squared corner is the tail, and which corner it is says who spoke), so the
+ * value a bubble needs is a four-corner shape rather than a number, and `card: 18` already
+ * supplies the three round corners. A `bubbleAgent` / `bubbleUser` pair here would be four
+ * numbers pretending to be one rung, and the next reader would try to use it for a card.
+ * They belong in the bubble component's own `StyleSheet` as
+ * `borderTopLeftRadius` / `…TopRight` / `…BottomRight` / `…BottomLeft`.
+ */
+export const solariumRadii = {
+  ...radii,
+  chip: 9,
+  control: 14,
+  card: 18,
+  sheet: 26,
+  pill: 999,
+  cardAndroid: 18,
+  controlAndroid: 999,
+  /** `--r-sentence`: the command field and every search field. */
+  sentence: 22,
+  /** `--r-major`: full-card empty states. */
+  major: 20,
+  /** `--r-inset`: rows inside a list. */
+  row: 14,
+  /** `--r-tile`: the 34-40px icon tiles. */
+  iconTile: 9,
+  /** `--r-key` */
+  key: 7,
+  /** `--r-nav` */
+  nav: 12,
+} as const;
+
+/**
+ * **The Building Blocks radius ladder — a third set, and deliberately not merged into either.**
+ *
+ * `design_handoff_solarium_blocks_case_studies` (2026-09-23) specifies major 16 · mid 12 · inset 8
+ * · tile 6 · key 4, with the rule *nest inner = outer − gap*. `solariumRadii` above came from the
+ * Ambi handoff and disagrees on every shared name (`major` 20, `row` 14, `iconTile` 9, `key` 7).
+ * Rewriting `solariumRadii` would reshape every Ambi screen; so the blocks read this ladder and
+ * nothing else does. Which ladder is right is open — `docs/HANDOFF-SOLARIUM-BLOCKS.md` §6.
+ */
+export const blockRadii = {
+  /** `--r-major`: cards, toasts, dialogs. */
+  major: 16,
+  /** `--r-mid`: selectable cards, callouts, menus. */
+  mid: 12,
+  /** `--r-inset`: fields, buttons, wells, menu items. */
+  inset: 8,
+  /** `--r-tile`: leading tiles, segments. */
+  tile: 6,
+  /** `--r-key`: a checkbox. */
+  key: 4,
+} as const;
+
+/**
+ * **Which rung each part of a widget's interior sits on.**
+ *
+ * Not a second system — every value here *is* a `radii` or `type` rung above. It exists
+ * because the widget layer kept answering "what radius is an error box?" per file, and
+ * arrived at seven different radii (6, 7, 8, 9, 10, 12, 999) and eight font sizes across
+ * eleven widgets. The answer is not a new number; it is *which existing rung*, written down
+ * once so the twelfth widget does not invent a ninth.
+ *
+ * Read it as a lookup, not a scale: a widget asks what KIND of part it is drawing and gets
+ * the rung. Anything not listed here does not belong inside a widget body.
+ */
+export const widgetPart = {
+  /** A pill: type pill, produced pill, delta pill, state pill. */
+  pill: radii.chip,
+  /** An inset block that holds a value: a well, an error box, a stats tile, a diff original. */
+  block: radii.key,
+  /** A pressable control inside a body: Reconnect, Re-run, the presentation toggle. */
+  control: radii.row,
+  /** A skeleton bar. Small enough that a softer corner reads as a different object. */
+  skeleton: 4,
+  /** Anything circular — a numeral badge, a deck action. */
+  round: radii.pill,
+} as const;
+
+/**
+ * **The strip along the bottom edge that docked overlays occupy.**
+ *
+ * A scrollable screen whose LAST element is something the user must press has to reserve this,
+ * or that control ends up underneath a toast. It is a real defect rather than a cosmetic one:
+ * an overlay sitting on top of a button swallows the tap, and from the user's side the button
+ * simply does not work.
+ *
+ * It has to clear two different things, which is why it is larger than any one of them. Ours is
+ * `ConflictToast`, docked at `insets.bottom + space.s14 * 2` because it is mounted once at the
+ * app root and cannot know whether the screen under it has a tab bar — so it clears the tallest
+ * case always. React Native's own LogBox notification is the other, and it sits lower; it is a
+ * development overlay, but "the Continue button does not respond while you are testing" is a
+ * cost paid on every device run.
+ *
+ * **Reserved on top of the safe-area inset, never instead of it** — the inset is the gesture
+ * handle's, and Android reports ~11dp for one it draws far taller.
+ */
+/**
+ * **The ground behind a modal, and it was never a token before this.**
+ *
+ * The app carries THREE scrim values across two files, all inline: `Confirm.tsx` uses
+ * `rgba(0, 0, 0, 0.42)`, while `Sheet.tsx` uses `rgba(8, 8, 10, 0.5)` and `rgba(8, 8, 10, 0.62)`
+ * for its destructive variant. Two different hues and three different opacities for one job —
+ * exactly the drift this file exists to stop, and it went unnoticed because a scrim is drawn
+ * once per overlay and never side by side with another.
+ *
+ * `Sheet`'s pair is adopted here because `Sheet` is the general-purpose overlay and the
+ * destructive step is a real distinction the other value cannot express. **`Confirm.tsx`'s
+ * `rgba(0, 0, 0, 0.42)` is left unreconciled on purpose** — collapsing it silently would be a
+ * visual change to a shipped screen made in passing, which is not a token decision to take
+ * inside an unrelated task. Flag it, port `Confirm` onto this, then delete the third value.
+ */
+export const scrim = {
+  default: 'rgba(8, 8, 10, 0.5)',
+  /** One step darker, for a sheet whose primary action destroys something. */
+  destructive: 'rgba(8, 8, 10, 0.62)',
+} as const;
+
+/**
+ * **The Building Blocks modal scrim (O4)** — `rgba(44,46,42,.28)`, lighter than `scrim.default`
+ * because the handoff's dialog sits on a porcelain page rather than over a photo-dark app. Only the
+ * blocks' `Modal`/`Layer` read it; every existing sheet keeps `scrim`.
+ */
+export const blockScrim = 'rgba(44, 46, 42, 0.28)';
+
+export const overlayLane = 80;
+
+/** 4pt base throughout — nothing is spaced by eye. */
+export const space = {
+  s1: 4,
+  s2: 8,
+  s3: 12,
+  s4: 16,
+  s5: 20,
+  s6: 24,
+  s8: 32,
+  s10: 40,
+  s14: 56,
+  // Legacy names still used by screens not yet re-spaced onto the 4pt scale above.
+  // Additive only — nothing here overrides a v2 value.
+  gutterRow: 13,
+  gutterText: 16,
+  gapRow: 8,
+  gapChip: 7,
+  gapSection: 20,
+  hitIos: 44,
+  hitMd: 48,
+} as const;
+
+export const layout = {
+  gutter: 20,
+  gutterAndroid: 16,
+  rowPadding: 16,
+  rowGap: 12,
+  sectionGap: 20,
+  /** Accessibility floor. Never override, on either platform. */
+  touchTargetMin: 44,
+  kindChipSize: 28,
+  kindChipSizeAndroid: 40,
+  ctaHeight: 56,
+  /**
+   * The tab bar's own content height, BEFORE the safe-area inset — voice-and-tabs §1.
+   *
+   * §1 quotes 88 "including the home indicator", which makes it a derivation rather than a
+   * constant: 10 of top padding, a 27pt pill, a 6pt gap and the label come to 54, and the
+   * device adds the rest. On a 34pt phone that is the specified 88; on one with no indicator
+   * it is 54, instead of 88 with 34pt of dead strip under the labels.
+   *
+   * It replaces the `tabBarHeight` / `tabBarHeightAndroid` pair, which existed because the bar
+   * was a floating pill on iOS and flush on Android. It is flush on both now, so one number.
+   */
+  tabBarContent: 54,
+} as const;
+
+/** Platform-resolved layout constants, so screens do not branch by hand. */
+export const isAndroid = RNPlatform.OS === 'android';
+export const gutter = isAndroid ? layout.gutterAndroid : layout.gutter;
+export const cardRadius = isAndroid ? radii.cardAndroid : radii.card;
+export const kindChipSize = isAndroid ? layout.kindChipSizeAndroid : layout.kindChipSize;
+export const tabBarHeight = layout.tabBarContent;
+
+/* ── Type ────────────────────────────────────────────────────────────────── */
+
+/**
+ * Sizes, weights and tracking only — the FAMILY is resolved from the provider, because
+ * typeface is a user preference. Never hard-code a family at a call site.
+ */
+export const type = {
+  display: { fontSize: 34, lineHeight: 38, fontWeight: '700' as const, letterSpacing: -0.021 * 34 },
+  title: { fontSize: 22, lineHeight: 28, fontWeight: '600' as const, letterSpacing: -0.011 * 22 },
+  heading: { fontSize: 17, lineHeight: 24, fontWeight: '600' as const, letterSpacing: -0.006 * 17 },
+  body: { fontSize: 16, lineHeight: 24, fontWeight: '400' as const, letterSpacing: 0 },
+  label: { fontSize: 14, lineHeight: 20, fontWeight: '500' as const, letterSpacing: 0 },
+  caption: { fontSize: 13, lineHeight: 18, fontWeight: '400' as const, letterSpacing: 0.005 * 13 },
+  monoTrigger: { fontSize: 17, lineHeight: 24, fontWeight: '500' as const, letterSpacing: 0 },
+  monoMeta: { fontSize: 13, lineHeight: 18, fontWeight: '400' as const, letterSpacing: 0 },
+  /**
+   * The 32px screen H1 a KeyShort top-level screen carries below its drawer row — "Home",
+   * "Your keyboard", "Library". Added by A7 (`tasks/KEYSHORT-REVAMP.md`, 11 Sep 2026) rather
+   * than S4, which found the gap first but deliberately left it unnamed until a real call site
+   * existed to name it from (`KeyShortScreensA/B/C/D.dc.html`: `font-size:32px;line-height:1.1;
+   * letter-spacing:-.01em`). `display` (34) is close but is the mono mark on Shortcut detail's
+   * `/remind`, a different job at a different size — do not reach for it here.
+   */
+  screenTitle: { fontSize: 32, lineHeight: 35, fontWeight: '400' as const, letterSpacing: -0.01 * 32 },
+  /** Structural group labels — `RECENT RUNS`, `TRIGGER`, `STEPS`. */
+  eyebrow: { fontSize: 12, lineHeight: 16, fontWeight: '500' as const, letterSpacing: 0.09 * 12 },
+  /**
+   * The same job at the KeyShort handoff's size — `font-size:10px; letter-spacing:.12em` on
+   * every structural label it draws (`SET UP`, `TYPEFACE`, `ACTIONS`). Selected per app by
+   * `DsProvider`'s `headings="screen"`, never by a call site: the eyebrow is one decision for
+   * the whole app, not a size each screen picks. See D4 in the KeyShort task board.
+   */
+  eyebrowDense: { fontSize: 10, lineHeight: 14, fontWeight: '500' as const, letterSpacing: 0.12 * 10 },
+  /**
+   * The Settings handoff's grouped row (`design_handoff_padki_settings`, Component Spec · Row): a
+   * 15px title and a 12px subtitle, both regular. Neither `body` (16) nor `caption` (13) is either
+   * one, and v2 is pixel-exact. The value beside them is `caption`, which already is 13. Used by
+   * `GroupedRow` (SET-3, 13 Sep 2026).
+   */
+  rowTitleDense: { fontSize: 15, lineHeight: 20, fontWeight: '400' as const, letterSpacing: 0 },
+  rowSubtitle: { fontSize: 12, lineHeight: 16, fontWeight: '400' as const, letterSpacing: 0 },
+  /**
+   * `SubScreenHeader`'s two rungs (Settings handoff, 13 Sep 2026). `appBarTitle` is the Android top
+   * app bar's title — 18/600, the handoff's `← Settings` row; `mdAppBar` (22) is the legacy M3 size
+   * and not this. `screenSubtitle` is the 14px line under a screen title on both platforms.
+   */
+  appBarTitle: { fontSize: 18, lineHeight: 24, fontWeight: '600' as const, letterSpacing: 0 },
+  screenSubtitle: { fontSize: 14, lineHeight: 20, fontWeight: '400' as const, letterSpacing: 0 },
+  // Legacy rungs, still named by the components moved in from neu/. Re-expressed in v2
+  // sizes rather than carried over at their old 1.26-scaled values.
+  iosLargeTitle: { fontSize: 34, lineHeight: 38, fontWeight: '700' as const, letterSpacing: -0.7 },
+  mdAppBar: { fontSize: 22, lineHeight: 28, fontWeight: '600' as const },
+  overlayTitle: { fontSize: 19, lineHeight: 24, fontWeight: '600' as const },
+  rowTitle: { fontSize: 16, lineHeight: 24, fontWeight: '400' as const },
+  rowTrigger: { fontSize: 17, lineHeight: 24, fontWeight: '500' as const },
+  rowMeta: { fontSize: 13, lineHeight: 18, fontWeight: '400' as const },
+  sectionLabel: { fontSize: 13, lineHeight: 18, fontWeight: '600' as const },
+  monoLabel: { fontSize: 12, lineHeight: 16, fontWeight: '400' as const, letterSpacing: 1.08 },
+  monoCount: { fontSize: 12, lineHeight: 16, fontWeight: '400' as const },
+  monoId: { fontSize: 11, lineHeight: 15, fontWeight: '400' as const },
+  statusBar: { fontSize: 12, lineHeight: 16, fontWeight: '400' as const },
+} as const;
+
+/**
+ * v2 is pixel-exact, so this is the identity. It survives only because the components
+ * moved in from `neu/` still wrap their literals in it; it goes as they are re-spaced.
+ */
+export const scale = (n: number): number => n;
+
+/**
+ * No binaries are committed, so both families fall back to the system faces. React
+ * Native and iOS need .otf or .ttf — woff2 is web-only and will not load.
+ */
+/**
+ * The families the shortcuts handoff specifies — **Switzer** and **JetBrains Mono**,
+ * replacing Geist and Geist Mono.
+ *
+ * Naming them here would be worse than useless: no binaries are bundled, and React Native
+ * takes a single family name rather than a stack, so an unresolvable name silently falls
+ * back with no way to tell it did. The names are recorded and the system faces stand in
+ * until the binaries land — and they must be .otf or .ttf, not the woff2 the handoff's
+ * fonts.css imports, which will not load on iOS or Android.
+ */
+export const FONT_FAMILIES = { sans: 'Switzer', mono: 'JetBrains Mono' } as const;
+
+export const FONTS = {
+  sans: RNPlatform.select({ ios: 'System', android: 'sans-serif', default: 'System' }),
+  /* Web: the same stack `DsProvider`'s typefaces use (`MONO_STACK_WEB`) — one mono, everywhere. */
+  mono: RNPlatform.select({ ios: 'Menlo', android: 'monospace', web: "ui-monospace, 'SF Mono', Menlo, monospace", default: 'monospace' }),
+} as const;
+
+/* ── Motion ──────────────────────────────────────────────────────────────── */
+
+/**
+ * One signature moment: trigger fire. Everything else is restrained — press is scale
+ * only, never a colour change and never an opacity dip; a tab change is a crossfade,
+ * never a slide, because the four tabs are peers rather than a sequence.
+ */
+export const motion = {
+  easeSweep: [0.22, 1, 0.36, 1] as const,
+  easeStandard: [0.4, 0, 0.2, 1] as const,
+  durationSweep: 420,
+  durationPress: 120,
+  durationTab: 180,
+  durationReducedPulse: 200,
+  /* M8 press, Solarium 0.2.0: scale .98 (was .985). */
+  pressScale: 0.98,
+  // Legacy durations named by the moved components.
+  instant: 140,
+  fast: 160,
+  quick: 180,
+  base: 200,
+  spin: 900,
+} as const;
+
+/** The active segment of a Solarium segmented control (onboarding batch 2): white on the well, this lift. */
+export const segmentLift = '0 1px 2px rgba(44, 46, 42, .08)';