@repobit/dex-system-design 0.25.12 → 1.0.0

package/src/tokens/tokens.js

@@ -1,7 +1,28 @@
 import { css } from 'lit';
 
-export const tokens = css`
-    :host {
+/**
+ * Design tokens.
+ *
+ * These are declared on :root in document scope, inside the `bd-tokens` cascade
+ * layer, rather than on :host inside every component. Both halves of that
+ * matter:
+ *
+ *   - A :host declaration beats an inherited value. While every component
+ *     re-declared the full token set on its own :host, an application could not
+ *     override a token from the page at all — its `:root` never reached the
+ *     shadow tree.
+ *   - Moving to :root is not sufficient on its own. adoptedStyleSheets are
+ *     ordered after the document's own author stylesheets, so an unlayered
+ *     :root here would still beat the application's CSS. Anything inside a
+ *     cascade layer loses to unlayered CSS, which is what makes the override
+ *     work.
+ *
+ * The upshot: an application can now do `:root { --color-blue-500: ... }`, or a
+ * whole `@media (prefers-color-scheme: dark)` block, and it wins.
+ *
+ * Importing any component installs this once. Nothing else is required.
+ */
+const declarations = `
         --typography-fontFamily-sans: "IBM Plex Sans", system-ui, -apple-system,
             BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif;
         --typography-fontFamily-mono: "IBM Plex Mono", ui-monospace, SFMono-Regular,
@@ -18,7 +39,7 @@ export const tokens = css`
         --typography-fontSize-4xl: 2.25rem; /* 36px */
         --typography-fontSize-5xl: 3rem; /* 48px */
         --typography-fontSize-6xl: 3.75rem; /* 60px */
-        --typography-fontSize-7xl: 4.5rem; /* 72px */
+                --typography-fontSize-7xl: 4.5rem; /* 72px */
         --typography-fontSize-8xl: 6rem; /* 96px */
         --typography-fontSize-9xl: 8rem; /* 128px */
 
@@ -30,11 +51,44 @@ export const tokens = css`
 
         --typography-lineHeight-none: 1;
         --typography-lineHeight-tight: 1.25;
-        --typography-lineHeight-snug: 1.375;
+        /* There is no snug (1.375). It was Tailwind's step, it carried the
+           heading roles until the leading was measured against IBM Plex Sans,
+           and once those moved to tight and 130 its only readers were four
+           documentation-chrome files setting 11px text. 11px is what
+           label-extra-small already answers, at normal, so they were repointed
+           there and the step was retired rather than kept alive by its own
+           documentation. */
         --typography-lineHeight-normal: 1.5;
         --typography-lineHeight-relaxed: 1.625;
         --typography-lineHeight-loose: 2;
 
+        /* The three steps above named for a density -- none .. loose -- are
+           Tailwind's default scale, values and names both, and nothing in them
+           was derived from IBM Plex Sans. These three were, and they are named
+           numerically because that is what the rest of this system does for a
+           scale step: --spacing-14, --dimension-44, --border-width-2.
+
+             130  the font's own declared line box. hhea, OS/2 sTypo and OS/2
+                  usWin in IBMPlexSans-*.woff2 all state 1.30, which is both
+                  unusual and deliberate -- it is why the same text does not
+                  change height between macOS and Windows.
+             140  IBM's own published value for Plex at 20px (@carbon/type,
+                  productive-heading-03 and expressive-heading-03).
+             145  between IBM's 1.5 at 16px and 1.4 at 20px.
+
+           The floor under all of them is ink, not taste. The deepest glyphs in
+           this family are the Romanian comma-below letters -- s-comma and
+           t-comma, -0.275em in Bold, a third deeper than g -- and the tallest
+           are grave and acute capitals at +0.977em. Measured per weight, ink
+           spans 1.174 Light, 1.194 Regular, 1.219 Medium, 1.235 SemiBold,
+           1.252 Bold. Nothing may be set below the floor for its weight, which
+           is why the display roles stay at tight and are not tightened further.
+           Foundations/Typography/Vertical Rhythm reaches 1.231 for 48px Bold
+           from canvas metrics; this is the same number from outline bounds. */
+        --typography-lineHeight-130: 1.3;
+        --typography-lineHeight-140: 1.4;
+        --typography-lineHeight-145: 1.45;
+
         --typography-letterSpacing-tighter: -0.05em;
         --typography-letterSpacing-tight: -0.025em;
         --typography-letterSpacing-normal: 0em;
@@ -80,6 +134,7 @@ export const tokens = css`
         --color-green-800: #0b6a26;
         --color-green-900: #084a1a;
         --color-green-950: #063c14;
+        --color-green-975: #011705;
 
         --color-yellow-50: #fffbf0;
         --color-yellow-100: #fff5d6;
@@ -92,6 +147,7 @@ export const tokens = css`
         --color-yellow-800: #855f00;
         --color-yellow-900: #5c4000;
         --color-yellow-950: #473100;
+        --color-yellow-975: #1a0f00;
 
         --color-neutral-0: #ffffff;
         --color-neutral-25: #fafafa;
@@ -100,11 +156,38 @@ export const tokens = css`
         --color-neutral-200: #c5c9ce;
         --color-neutral-300: #a6adb4;
         --color-neutral-400: #88909b;
-        --color-neutral-500: #6c7580;
+        /* The five in-between steps -- 450, 850, 925 here, and the two 975s
+           above -- exist for a dark theme, and nothing in light reads them.
+           The dark mode study (Foundations/Theming/Dark mode) found the ramps
+           too coarse at the dark end: container and subtle had to share
+           neutral-900 (finding 2), no step kept text-subtle both quieter than
+           muted and over 4.5:1 (finding 3), and green-950 and yellow-950 sat
+           1.5:1 off the dark page where every other tint sits near 1.1
+           (finding 5). Each is interpolated in OKLCH between its two
+           neighbours to the ratio the derivation asks for: 450 is 4.75:1 on
+           a dark card (4.93 on the dark page), midway between 500 and 400 at
+           1.22:1 from each -- subtle text sits on a page or a card, so it is
+           measured on the card (decision 17); 925 and 850 are 1.04 and 1.12
+           off it, the light container and subtle steps; the 975s are 1.04
+           and 1.03, the light tints. Measured against neutral-950, the dark
+           page, in src/tokens/dark-derivation.js. */
+        --color-neutral-450: #78818c;
+        /* #6a737e, moved one step from #6c7580. neutral-500 is
+           --color-text-subtle, and at #6c7580 subtle text on a card
+           (--color-surface-container, neutral-25) measured 4.48:1 -- under
+           4.5 on the ground most subtle text sits on. #6a737e gives 4.61 on a
+           card and 4.81 on the page, and stays a clear step above
+           neutral-600 (1.37:1 apart, the gap was 1.39). It does not clear
+           subtle on surface-subtle or the status tints (4.29 to 4.46):
+           that needs a step this ramp does not have, and is its own
+           decision. */
+        --color-neutral-500: #6a737e;
         --color-neutral-600: #565e66;
         --color-neutral-700: #41474d;
         --color-neutral-800: #2c3035;
+        --color-neutral-850: #181b1d;
         --color-neutral-900: #151719;
+        --color-neutral-925: #111214;
         --color-neutral-950: #0c0d0e;
         --color-neutral-1000: #000000;
 
@@ -132,20 +215,19 @@ export const tokens = css`
              ================================ */
 
 
-        --dimension-2px: 2px;
-        --dimension-4px: 4px;
-        --dimension-8px: 8px;
-        --dimension-12px: 12px;
-        --dimension-16px: 16px;
-        --dimension-20px: 20px;
-        --dimension-24px: 24px;
-        --dimension-32px: 32px;
-        --dimension-34px: 34px;
-        --dimension-40px: 40px;
-        --dimension-45px: 45px;
-        --dimension-48px: 48px;
-        --dimension-55px: 55px;
-        --dimension-64px: 64px;
+        --dimension-4: 4px;
+        --dimension-8: 8px;
+        --dimension-12: 12px;
+        --dimension-16: 16px;
+        --dimension-20: 20px;
+        --dimension-24: 24px;
+        --dimension-32: 32px;
+        --dimension-36: 36px;
+        --dimension-40: 40px;
+        --dimension-44: 44px;
+        --dimension-48: 48px;
+        --dimension-56: 56px;
+        --dimension-64: 64px;
 
         /* ================================
              CORE TRANSITION TOKENS
@@ -158,6 +240,13 @@ export const tokens = css`
 
         --transition-easing-linear: linear;
         --transition-easing-smooth: ease-in-out;
+        /* The CSS default curve. It was missing, and its absence was the single
+           reason eleven component transitions could not be expressed in tokens:
+           ease is not ease-in-out — it front-loads, and swapping one for the
+           other is a visible change. Named after the keyword, as linear,
+           ease-in and ease-out beside it are; smooth is the outlier that
+           aliases a keyword rather than naming it. */
+        --transition-easing-ease: ease;
         --transition-easing-ease-in: ease-in;
         --transition-easing-ease-out: ease-out;
         --transition-easing-bounce: cubic-bezier(0.68, -0.55, 0.265, 1.55);
@@ -190,55 +279,611 @@ export const tokens = css`
         --focus-outline-success: 0 0 0 2px var(--color-neutral-0),
             0 0 0 4px var(--color-green-500);
 
+        /* The four above put the WHITE band against the control, which is what
+           keeps them visible on a coloured hero. That fails on a control which
+           is itself white: bd-button-link variant="white" measured 1.00:1 for
+           the inner band against its own fill and 2.38:1 for the blue band
+           against a blue hero, so neither band reached the 3:1 WCAG 2.4.11
+           asks of a focus indicator. This one inverts the pair -- dark band
+           against the control, white band against the ground -- so the inner
+           band carries the contrast whatever the control is sitting on. */
+        --focus-outline-inverse: 0 0 0 2px var(--color-neutral-900),
+            0 0 0 4px var(--color-neutral-0);
+
         /* Traditional Outline Values for Fallback */
         --focus-outline-traditional: 2px solid var(--color-blue-500);
         --focus-outline-offset: 2px;
 
+        /* The ring is a box-shadow, so it already follows the radius of the
+           element it is on. This is the default for elements that have no
+           radius of their own — a link, a tab, an accordion header — so the
+           ring is not a hard rectangle. An element with its own radius should
+           set nothing and let the ring follow its shape. */
+        --focus-outline-radius: var(--radius-sm);
+
+        /* ================================
+             SEMANTIC ROLE - SELECTED INDICATOR
+             ================================
+           What marks the current item in a set. Two components already drew it
+           — Components/Tab List and the anchor nav — and they drifted apart on
+           easing while both used valid tokens. The role is named here so there
+           is one answer, not two spellings.
+
+           THE COLOUR IS NOT NAMED FOR A SHAPE, and that is the whole point of
+           the split below. It was --indicator-underline-color, which described
+           the underline three components happen to draw rather than the job the
+           value does. awards-flex marks its current slide with a DOT: same job,
+           same blue-500, and it could not adopt the token because a dot is not
+           an underline, so it reached for the primitive instead. Vocabulary
+           question E1 found that — see plans/reports/phase-2-vocab-e-has-role-pass.md.
+
+           Renamed with no back-compat alias, following the same convention as
+           --typography-label-xsmall becoming --typography-body-xsmall: rename
+           cleanly and say why here.
+
+           The geometry stays underline-specific, because it genuinely is — a
+           3px height and a width transition describe a rule sliding under a
+           tab, and a dot scales instead. A fourth consumer needing dot
+           geometry should name it for the dot, not borrow these. */
+        --indicator-color: var(--color-blue-500);
+        --indicator-underline-height: var(--border-width-3);
+        --indicator-underline-duration: var(--transition-duration-slow);
+        --indicator-underline-easing: var(--transition-easing-smooth);
+
+        /* ================================
+             SEMANTIC ROLE - CARD SHAPE
+             ================================
+           The corner and the inset that make a card a card here. Eleven
+           card-shaped objects agree on both -- the Card box, CardFeatures,
+           LightCarousel, Bento, the Awards feature card, the TrustPanel card,
+           the CompareSection card, the Carousel item, the Comparison Panel
+           column and both Pricing cards -- and they only agree because the two
+           that did not were brought in one at a time.
+
+           This role is named now and was deliberately not named before, and
+           the difference is evidence rather than appetite. CLAUDE.md said
+           there was no semantic radius scale because "the components do not
+           agree closely enough for a shared role to be honest", which was true
+           when it was written: the compare card sat at --radius-3xl and the
+           carousel item at --radius-3xl with a 2em inset. Both have since been
+           measured, argued and moved. A role declared then would have imposed
+           a consensus; declared now it records one.
+
+           It is a role, not a scale. There is still no --card-* family and no
+           semantic step between radii -- naming the job is the whole point,
+           and the same reasoning is why --panel-radius is NOT here: the eight
+           --radius-xl consumers are a code block, a bar track, a table
+           container, a discount pill, two public image variants, a modal and a
+           terminal. That is not a family, and calling it one would be the
+           mistake this comment is describing.
+
+           scripts/card-shapes.json lists the eleven and lint:tokens checks it
+           both ways, so a card that stops using the role and a registry entry
+           that stops matching are both findings. */
+        --card-radius: var(--radius-2xl);
+        --card-padding: var(--spacing-32);
+
+        /* The inset a card takes when the viewport is too narrow to afford the
+           full one. Four cards reached for this independently before it had a
+           name -- Bento below sm, the Comparison Panel and Trust Panel below
+           md, and LightCarousel with an em literal -- and three of the four
+           picked exactly 24. That is the agreement that makes it a role rather
+           than four local decisions.
+
+           Two steps, not a scale. A card is either affording its inset or it
+           is not; there is no third size, and a component that wants one is
+           asking a design question rather than a token question. */
+        --card-padding-compact: var(--spacing-24);
+
+        /* ================================
+             SEMANTIC ROLES - COLOUR
+             ================================
+           The tier the architecture always described and the components never
+           had. Measured before this landed: 71.8% of the colour references in
+           the atom layer pointed straight at a palette step — 38 distinct
+           primitives across 233 references, where the roles underneath them
+           number about thirty. That gap is why four text atoms ended up with
+           four different inks, and why two components disagreed about which
+           green means "success".
+
+           None of these are new decisions. Every value is the step something
+           already uses, and the text roles are the ones COLOR_ROLES in
+           src/components/shared/token-scales.js had already chosen as clearing
+           4.5:1 on white — that map should now resolve through these rather
+           than reaching past them into the palette.
+
+           Reach for the role, not the step. The palette stays available for
+           what no role covers yet; when that happens, add the role.
+
+           ---
+
+           NAME COLLISION WITH src/blog. The blog sub-system already declares
+           seven of these names with different values:
+
+             --color-text-secondary   here neutral-700   blog neutral-600
+             --color-text-muted       here neutral-600   blog neutral-500
+             --color-surface-brand    here blue-500      blog blue-50   (!)
+             --color-surface-inverse  here neutral-900   blog neutral-950
+             --color-border-default   here neutral-400   blog neutral-300
+             --color-border-subtle    here neutral-200   blog neutral-100
+             --color-border-strong    here neutral-900   blog neutral-600
+
+           This is safe today and must not be assumed safe. The blog applies
+           its tokens on :host inside each blog component, so inside a blog
+           shadow tree the blog value wins, and outside it never applies.
+           Nothing in this system renders inside that tree.
+
+           It stops being safe if a page ever loads src/blog/tokens.css
+           globally alongside this file. That file is an unlayered :root block,
+           and unlayered CSS beats a cascade layer, so it would win — silently
+           turning --color-surface-brand from a saturated fill into a pale
+           tint under any component that had adopted it.
+
+           The two files share 616 names and disagree on 82 of them; all 58
+           shared palette primitives are identical, so the fork is entirely at
+           this tier and above. Reconciling it is its own piece of work. Until
+           it happens, do not load both globally. */
+
+        /* Text. -primary is the default ink for anything that reads as body
+           or heading copy. -brand is blue-600 rather than blue-500 on purpose:
+           blue-500 is 4.53:1 on pure white and fails on any tint. */
+        --color-text-primary: var(--color-neutral-900);
+        --color-text-secondary: var(--color-neutral-700);
+        --color-text-muted: var(--color-neutral-600);
+        /* Subtle sits on the page or a card, and nowhere else: on a band
+           (surface-subtle, surface-muted) or a status tint, step up to
+           -muted. No value can be both quieter than muted and 4.5:1 on every
+           ground -- on surface-muted it would have to be muted -- so the rule
+           is where it goes, not how dark it is. Dark mode decision 17. */
+        --color-text-subtle: var(--color-neutral-500);
+        --color-text-disabled: var(--color-neutral-400);
+        --color-text-inverse: var(--color-neutral-0);
+        /* Subordinate text on an inverse surface. --color-text-inverse is the
+           high-emphasis step there; this is the one below it, and until now the
+           system had no such step at all -- the light-side -secondary, -muted and
+           -subtle roles invert to 1.91, 2.73 and 3.85 against
+           --color-surface-inverse and cannot be used.
+
+           Two components had already invented it independently and spelled it
+           differently: bd-terminal-message with rgba(255,255,255,0.5) and
+           bd-process-steps with --color-neutral-300 twice. neutral-300 is the
+           value here because it is the portable one. Measured on the three
+           inverse grounds in use -- neutral-900, neutral-800 and the #0b1626 the
+           process-steps gradient ends on -- it reads 7.92, 5.85 and 8.00, while
+           the white-at-half-alpha spelling reads 5.27, 3.89 and 5.32 and only
+           clears 4.5 because the terminal's ground happens to be the darkest of
+           the three.
+
+           There is deliberately no -secondary-inverse: bd-cta-banner has a third
+           tier at white 0.85 and it is one consumer, which is not a
+           responsibility. An earlier draft of this note also called it a
+           contrast failure, from a worst-case calculation against the lightest
+           stop in its gradient. Sampling the pixels actually behind the text
+           disproved that -- the radial highlight sits at 78% -10% and is mostly
+           outside the banner, so the three tiers measure 4.60, 4.57 and 4.46 at
+           their worst pixel rather than the 3.35, 2.84 and 2.13 the arithmetic
+           predicted. The tier is fine; it is still not a role. */
+        --color-text-muted-inverse: var(--color-neutral-300);
+        /* Ink on --color-surface-media, fixed with it: a part that does not
+           switch needs ink that does not switch either (the white button
+           preset, dark mode finding 8). text-inverse and text-muted-inverse
+           flip in a dark theme and would put dark ink on the dark frame --
+           a video play icon at 3.13:1, a terminal's quieter lines at 1.91. */
+        --color-text-on-media: var(--color-neutral-0);
+        --color-text-on-media-muted: var(--color-neutral-300);
+        --color-text-brand: var(--color-blue-600);
+        /* Brand text, hovered: a link or a citation reference under the
+           pointer. Before this role existed, the hover read
+           --color-action-primary-active -- a pressed button fill used as ink.
+           The value is the same blue-700, so nothing moves in this theme; the
+           difference is that a fill and a text colour answer different
+           questions, and a dark theme has to answer them differently. Measured
+           in the Figma Dark mode study: the fill stays put on a dark page and
+           the link it borrowed falls to 2.27:1. */
+        --color-text-brand-hover: var(--color-blue-700);
+        --color-text-success: var(--color-green-800);
+        --color-text-warning: var(--color-yellow-800);
+        --color-text-error: var(--color-red-700);
+
+        /* Surfaces. The feedback four are the tints a message sits on, each
+           measured against the matching --color-text-* step above: success
+           6.42, warning 5.59, error 6.83, info 5.72.
+
+           -brand is the one to watch. --color-text-inverse on it measures
+           4.53:1 — it passes, with no headroom at all, and it is the same
+           blue-500 the contrast note warns about elsewhere. White on brand is
+           fine for a button label; do not build a tinted variant on top of it
+           without re-measuring. */
+        --color-surface-default: var(--color-neutral-0);
+        /* The ground a self-contained content object sits on: one step off the
+           page, so a card, tile or panel reads as its own object without
+           needing a border or a shadow to say so. Twelve components were
+           reaching past the surface family for this, eight of them declaring
+           the same local alias, because the role did not exist.
+
+           Container is not subtle. Subtle groups things that already belong
+           together and is meant to recede; container is the default ground of
+           an object that stands on its own. They also differ visibly -- the
+           step between them is the difference between an object on the page
+           and a wash behind a group -- so they are not interchangeable.
+
+           The name means a visual container for content. It has nothing to do
+           with CSS container queries. */
+        --color-surface-container: var(--color-neutral-25);
+        --color-surface-subtle: var(--color-neutral-50);
+        --color-surface-muted: var(--color-neutral-100);
+        --color-surface-inverse: var(--color-neutral-900);
+        /* The frame around media: a video letterbox, a terminal panel. Dark in
+           every theme, because what it frames is dark -- which is why it is
+           not --color-surface-inverse, the polarity flip, that both used to
+           read. Inverse turns light in a dark theme; a letterbox must not,
+           and the terminal's own palette (blue-400, the traffic-light green)
+           is only legible on a dark ground. Dark mode decision 15. */
+        --color-surface-media: var(--color-neutral-900);
+        --color-surface-brand: var(--color-blue-500);
+        --color-surface-disabled: var(--color-neutral-100);
+        /* The ground of a control while it is held down, one step below
+           -muted (its hover). bd-back read neutral-200 for this and said in a
+           no-token comment that the surface roles stopped at -muted; reading
+           the primitive meant it could not follow a theme, and on a dark page
+           it measured 1.48:1 under a label that did (dark mode finding 14). */
+        --color-surface-pressed: var(--color-neutral-200);
+        --color-surface-success: var(--color-green-50);
+        --color-surface-warning: var(--color-yellow-50);
+        --color-surface-error: var(--color-red-50);
+        --color-surface-info: var(--color-blue-50);
+
+        /* Borders, measured on --color-surface-default. Only the two that
+           bound a live control clear the 3:1 WCAG 1.4.11 asks of a UI
+           component: -default at 3.23 and -brand at 4.53.
+
+           -subtle (1.66) and -disabled (2.27) sit below it on purpose.
+           -subtle is a decorative hairline between things that already belong
+           together, not the edge of anything actionable, and disabled controls
+           are exempt under 1.4.3. Do not reach for -subtle to outline a
+           control. */
+        --color-border-subtle: var(--color-neutral-200);
+        --color-border-default: var(--color-neutral-400);
+        --color-border-strong: var(--color-neutral-900);
+        --color-border-brand: var(--color-blue-500);
+        --color-border-disabled: var(--color-neutral-300);
+
+        /* The boundary of a self-contained object -- a card, a panel, a
+           navigation band -- drawn only so the object is perceptible, never so
+           it looks operable. It is the border counterpart of
+           --color-surface-container, and the two answer the same question from
+           opposite sides: is this its own thing.
+
+           It exists because eight components needed it and none could ask for
+           it. Seven reached past the roles to --color-neutral-100 directly and
+           one more declared a private --border-card-grey alias in seven files
+           to say --color-neutral-50. Measured on --color-surface-default it is
+           1.29:1, and on --color-surface-container 1.23:1 -- deliberately below
+           -subtle's 1.66, because -subtle is already spoken for as the hairline
+           between things that belong together, and a long way below the 3:1
+           WCAG 1.4.11 asks of anything actionable. That is the point: an object
+           boundary is not a control edge, and must not read as one.
+
+           -inverse is the same responsibility on an inverse surface, the way
+           --color-text-inverse and --color-surface-inverse are, and not a
+           second role. It is spelled as a proportion of --color-neutral-0
+           rather than a raw rgba for the same reason
+           --button-outline-white-border-default is: the value stays traceable
+           to a token when the palette moves. Over --color-surface-inverse it
+           measures 1.42:1, which puts it in the same perceptual band as the
+           light value rather than at the 10.8:1 --color-border-subtle would
+           give there.
+
+           This role says what a low-emphasis boundary looks like. It does not
+           say whether a component should have one -- that stays a component
+           decision, and the evidence says the components genuinely disagree. */
+        --color-border-container: var(--color-neutral-100);
+        --color-border-container-inverse: color-mix(in srgb, var(--color-neutral-0) 12%, transparent);
+
+        /* Action. The interactive ramp, one step down the palette per state.
+           accent is this system's conversion colour — Buy now and the like —
+           and is not a danger signal; see the bd-button story notes. */
+        --color-action-primary: var(--color-blue-500);
+        --color-action-primary-hover: var(--color-blue-600);
+        --color-action-primary-active: var(--color-blue-700);
+        --color-action-accent: var(--color-red-600);
+        --color-action-accent-hover: var(--color-red-700);
+        --color-action-accent-active: var(--color-red-800);
+        /* The neutral action fill: the secondary button, and the ghost
+           button's pressed state. Both read neutral-950 / 800 / 1000 straight
+           from the palette, which no theme can reach -- and the dark page is
+           neutral-950 too, so in a dark theme the fill would vanish into it
+           (dark mode finding 8). A role gives the fill a value of its own in
+           each theme. */
+        --color-action-secondary: var(--color-neutral-950);
+        --color-action-secondary-hover: var(--color-neutral-800);
+        --color-action-secondary-active: var(--color-neutral-1000);
+        /* Ink on an action fill: a button label, a checkmark, a radio dot, a
+           switch thumb. Before this role existed the buttons read
+           --color-text-inverse ("text on an inverse surface") and the controls
+           read --color-surface-default ("the page"). Both resolve to white in
+           this theme, which is why the borrowing never showed -- and both must
+           flip to near-black in a dark one, which would turn every label and
+           mark dark on its blue or red fill. White clears every action fill:
+           4.53 to 10.51:1. Measured in the Figma Dark mode study. */
+        --color-action-on-fill: var(--color-neutral-0);
+
+        /* ================================
+             SEMANTIC ROLES - STACKING
+             ================================
+           Thirty z-index declarations across eight values that were never
+           chosen relative to one another: -1, 1, 2, 10, 200, 1000, 1001 and
+           9999. Both bd-modal and the carousel sit on 9999, so there is no
+           answer to which of the two wins — that is what an unscaled ladder
+           costs.
+
+           The rungs are far apart on purpose, so a component can take a rung
+           and still stack its own internals inside it with a calc. A tooltip
+           opened from inside a dialog has to clear the dialog, which is why
+           it is the top rung rather than the first. */
+        --z-below: -1;
+        --z-base: 1;
+        --z-raised: 2;
+        --z-sticky: 200;
+        --z-overlay: 1000;
+        --z-modal: 1100;
+        --z-tooltip: 1200;
+
+        /* ================================
+             SEMANTIC ROLES - OPACITY
+             ================================
+           One role, because one role is what the evidence supports. The dim
+           end of a reduced-motion pulse is spelled three times in the atom
+           layer — bd-button and bd-spinner at 0.4, bd-skeleton at 0.45 — and
+           is the same intent each time: a mark that cannot spin should still
+           read as busy.
+
+           Disabled is deliberately absent. This system expresses disabled with
+           the neutral ramp rather than by dimming, and the one token that said
+           otherwise (--button-shared-disabled-opacity: 0.6) is unused. */
+        --opacity-pulse: 0.4;
+
+        /* ================================
+             SEMANTIC ROLE - STATUS TONES
+             ================================
+           bd-badge, bd-tag and bd-alert all say the same six things and each
+           spelled them out for itself. The text colours already matched across
+           badge and tag — the tag story says so — but by coincidence rather
+           than construction, and the one place they had drifted proves the
+           point: alert drew its success rule in green-600 where badge's
+           success dot used green-700.
+
+           Seven roles, because the three components need different weights of
+           the same tone:
+
+             -text            ink on a tinted chip        badge shade, tag
+             -surface         the light tint              tag, alert
+             -surface-strong  the heavier tint            badge shade
+             -border          the hairline                tag
+             -accent          the saturated step          badge dot, alert rule
+             -fill / -on-fill a saturated chip and its ink  badge fill
+
+           What is deliberately *not* unified: a tag carries a border and sits
+           on -surface, a badge has no border and sits on -surface-strong. That
+           difference is documented in the tag story — the lighter fill is what
+           lets the tag's border read — so it is expressed as two roles rather
+           than flattened into one.
+
+           Brand has no -surface-strong. It would be blue-100, which is
+           info's, so a brand badge on it could not be told from an info badge.
+           Brand's badge sits on -surface like its tag, and that one collision
+           is the whole exception. */
+
+        --status-neutral-text: var(--color-neutral-700);
+        --status-neutral-surface: var(--color-neutral-50);
+        --status-neutral-surface-strong: var(--color-neutral-100);
+        --status-neutral-border: var(--color-neutral-200);
+        --status-neutral-accent: var(--color-neutral-700);
+        --status-neutral-fill: var(--color-neutral-900);
+        --status-neutral-on-fill: var(--color-neutral-0);
+
+        --status-brand-text: var(--color-blue-600);
+        --status-brand-surface: var(--color-blue-50);
+        --status-brand-border: var(--color-blue-200);
+        --status-brand-accent: var(--color-blue-600);
+        --status-brand-fill: var(--color-blue-500);
+        --status-brand-on-fill: var(--color-neutral-0);
+
+        --status-info-text: var(--color-blue-600);
+        --status-info-surface: var(--color-blue-50);
+        --status-info-surface-strong: var(--color-blue-100);
+        --status-info-border: var(--color-blue-200);
+        --status-info-accent: var(--color-blue-500);
+        --status-info-fill: var(--color-blue-500);
+        --status-info-on-fill: var(--color-neutral-0);
+
+        --status-success-text: var(--color-green-800);
+        --status-success-surface: var(--color-green-50);
+        --status-success-surface-strong: var(--color-green-100);
+        --status-success-border: var(--color-green-200);
+        --status-success-accent: var(--color-green-700);
+        --status-success-fill: var(--color-green-700);
+        --status-success-on-fill: var(--color-neutral-0);
+
+        --status-warning-text: var(--color-yellow-800);
+        --status-warning-surface: var(--color-yellow-50);
+        --status-warning-surface-strong: var(--color-yellow-100);
+        --status-warning-border: var(--color-yellow-200);
+        --status-warning-accent: var(--color-yellow-700);
+        --status-warning-fill: var(--color-yellow-500);
+        --status-warning-on-fill: var(--color-neutral-900);
+
+        --status-error-text: var(--color-red-700);
+        --status-error-surface: var(--color-red-50);
+        --status-error-surface-strong: var(--color-red-100);
+        --status-error-border: var(--color-red-200);
+        --status-error-accent: var(--color-red-600);
+        --status-error-fill: var(--color-red-600);
+        --status-error-on-fill: var(--color-neutral-0);
+
         /* ================================
              COMPONENT TOKENS - TYPOGRAPHY
              ================================ */
 
+
+        /* ===============================================================
+           FLUID TYPE - the roles that cannot hold their size on a phone.
+
+           WHY. Measured in the Figma file (page "Type on mobile"), the
+           binding constraint on large type is not how many lines a sentence
+           takes, it is whether the longest UNBREAKABLE WORD fits the column.
+           The column is the viewport minus twice --grid-padding-*, so a 320px
+           phone gives type 288px -- 10% of the screen is gutter. Against that
+           column the ceiling for the worst realistic compound (Finnish
+           "Henkilollisyyssuoja", 9.07px of width per px of size) is 31px.
+           heading-h1 is 48. It overflowed at 375 as well as at 320, in German
+           and Finnish both.
+
+           WHY NOT A BREAKPOINT STEP. Tried first and abandoned, measured:
+           stepping h1 to 36 below sm still overflows at 320 (needs 327 of
+           288) and changes nothing at 576-767 where the ceiling is already 54.
+           The constraint moves continuously with the column, because the
+           column is a function of viewport width -- a step function
+           approximates a line with a staircase. clamp() states the line.
+
+           THE WINDOW IS 320 -> 992. The minimum is reached at 320 and the
+           maximum at 992, which is the lg breakpoint. Above lg NOTHING
+           changes from the sizes this system shipped with, so every desktop
+           layout that has been reviewed stays exactly as reviewed, and the
+           whole change is confined to the widths where the failures were
+           measured.
+
+           THE MIDDLE TERM CARRIES A rem, AND THAT IS NOT OPTIONAL.
+           clamp(2rem, 4vw, 3rem) is the spelling everyone reaches for and it
+           breaks text resize: a size depending only on viewport width ignores
+           the reader's own font-size setting, which is WCAG 1.4.4. With a rem
+           in the middle term the type still grows when the reader enlarges
+           it. This package already refuses the equivalent mistake twice --
+           line-height is always unitless, and --spacing-* is rem precisely so
+           boxes grow with the text.
+
+           THE TWO LITERALS PER ROLE ARE DERIVED, NOT CHOSEN. For a role
+           running from min m to max M across the window V1..V2:
+
+             slope     = (M - m) / (V2 - V1)        px of size per px of width
+             vw term   = slope x 100
+             rem term  = (m - slope x V1) / 16
+
+           With V1=320 and V2=992 that is (M-m)/6.72 vw and
+           (m - (M-m)/2.1) / 16 rem. Every pair below is that arithmetic and
+           nothing else; each line states its own m and M so it can be checked
+           without re-deriving. Changing the mobile ladder means changing the
+           -fontSizeMin token and re-running the two formulas.
+
+           THE MOBILE LADDER IS THE DESIGN DECISION HERE, and it is these six
+           numbers: 30 27 24 21 18 16 for h1 through h6. Its ratios are 1.11,
+           1.13, 1.14, 1.17, 1.13 -- near-even, against the desktop ladder's
+           irregular 1.33, 1.13, 1.33, 1.20, 1.11. A phone has less range to
+           spend (16 to the 31px ceiling, a factor of 1.94, where desktop has
+           18 to 48, a factor of 2.67), so the ladder has to compress, and
+           compressing it evenly is what keeps six levels distinguishable.
+           Measured: h1 at 30 needs 272px of a 288px column, so there is 16px
+           of margin for a word longer than any tested.
+
+           WHAT IS DELIBERATELY NOT FLUID.
+           - Every role at 24px and below except body-lead. Nothing that small
+             overflows, and the small end's own failure is measure, not
+             overflow -- see below.
+           - display-lg, display-xl, display-2xl, display-3xl (60 to 128px).
+             Above display-md the family has NO mobile identity
+             to give it: five roles would all have to squeeze between 30 and
+             the 31px ceiling. They are desktop-only, and a component that
+             needs one of them on a phone should reach for a heading role
+             instead. Recorded rather than papered over.
+           - body-regular at 16px. It runs 40 characters per line on a 288px
+             column, which the study first called "below the comfortable
+             45-75 band" -- and that band is a print and desktop yardstick.
+             Reaching 45 CPL on a 288px column needs 14.2px body text, and 50
+             CPL needs 12.8px; applying it to a phone trades the 16px
+             accessibility floor for a soft readability target. 40 characters
+             is what every phone does. body-lead is the one prose role that
+             does move, 20 -> 18, because at 20 it ran 32 characters -- five
+             or six words a line -- and an intro paragraph has no claim on
+             being the largest thing on a small screen.
+           =============================================================== */
+
         /* Heading Tokens */
-        --typography-heading-h1-fontSize: var(--typography-fontSize-5xl);
+        /* fluid: 30px at 320 -> 48px at 992. (48-30)/6.72=2.6786vw, (30-(48-30)/2.1)/16=1.33929rem */
+        --typography-heading-h1-fontSizeMin: 1.875rem; /* 30px */
+        --typography-heading-h1-fontSize: clamp(
+          var(--typography-heading-h1-fontSizeMin),
+          calc(1.33929rem + 2.6786vw),
+          var(--typography-fontSize-5xl)
+        );
         --typography-heading-h1-fontWeight: var(--typography-fontWeight-bold);
-        --typography-heading-h1-lineHeight: var(--typography-lineHeight-snug);
+        --typography-heading-h1-lineHeight: var(--typography-lineHeight-tight);
         --typography-heading-h1-letterSpacing: var(--typography-letterSpacing-normal);
         --typography-heading-h1-fontFamily: var(--typography-fontFamily-sans);
 
-        --typography-heading-h2-fontSize: var(--typography-fontSize-4xl);
+        /* fluid: 27px at 320 -> 36px at 992. (36-27)/6.72=1.3393vw, (27-(36-27)/2.1)/16=1.41964rem */
+        --typography-heading-h2-fontSizeMin: 1.6875rem; /* 27px */
+        --typography-heading-h2-fontSize: clamp(
+          var(--typography-heading-h2-fontSizeMin),
+          calc(1.41964rem + 1.3393vw),
+          var(--typography-fontSize-4xl)
+        );
         --typography-heading-h2-fontWeight: var(--typography-fontWeight-bold);
-        --typography-heading-h2-lineHeight: var(--typography-lineHeight-snug);
+        --typography-heading-h2-lineHeight: var(--typography-lineHeight-tight);
         --typography-heading-h2-letterSpacing: var(--typography-letterSpacing-normal);
         --typography-heading-h2-fontFamily: var(--typography-fontFamily-sans);
 
-        --typography-heading-h3-fontSize: var(--typography-fontSize-3xl);
+        /* fluid: 24px at 320 -> 32px at 992. (32-24)/6.72=1.1905vw, (24-(32-24)/2.1)/16=1.26190rem */
+        --typography-heading-h3-fontSizeMin: 1.5rem; /* 24px */
+        --typography-heading-h3-fontSize: clamp(
+          var(--typography-heading-h3-fontSizeMin),
+          calc(1.26190rem + 1.1905vw),
+          var(--typography-fontSize-3xl)
+        );
         --typography-heading-h3-fontWeight: var(--typography-fontWeight-semibold);
-        --typography-heading-h3-lineHeight: var(--typography-lineHeight-snug);
+        --typography-heading-h3-lineHeight: var(--typography-lineHeight-130);
         --typography-heading-h3-letterSpacing: var(--typography-letterSpacing-normal);
         --typography-heading-h3-fontFamily: var(--typography-fontFamily-sans);
 
-        --typography-heading-h4-fontSize: var(--typography-fontSize-2xl);
+        /* fluid: 21px at 320 -> 24px at 992. (24-21)/6.72=0.4464vw, (21-(24-21)/2.1)/16=1.22321rem */
+        --typography-heading-h4-fontSizeMin: 1.3125rem; /* 21px */
+        --typography-heading-h4-fontSize: clamp(
+          var(--typography-heading-h4-fontSizeMin),
+          calc(1.22321rem + 0.4464vw),
+          var(--typography-fontSize-2xl)
+        );
         --typography-heading-h4-fontWeight: var(--typography-fontWeight-semibold);
-        --typography-heading-h4-lineHeight: var(--typography-lineHeight-snug);
+        --typography-heading-h4-lineHeight: var(--typography-lineHeight-130);
         --typography-heading-h4-letterSpacing: var(--typography-letterSpacing-normal);
         --typography-heading-h4-fontFamily: var(--typography-fontFamily-sans);
 
-        --typography-heading-h5-fontSize: var(--typography-fontSize-xl);
+        /* fluid: 18px at 320 -> 20px at 992. (20-18)/6.72=0.2976vw, (18-(20-18)/2.1)/16=1.06548rem */
+        --typography-heading-h5-fontSizeMin: 1.125rem; /* 18px */
+        --typography-heading-h5-fontSize: clamp(
+          var(--typography-heading-h5-fontSizeMin),
+          calc(1.06548rem + 0.2976vw),
+          var(--typography-fontSize-xl)
+        );
         --typography-heading-h5-fontWeight: var(--typography-fontWeight-medium);
-        --typography-heading-h5-lineHeight: var(--typography-lineHeight-normal);
+        --typography-heading-h5-lineHeight: var(--typography-lineHeight-140);
         --typography-heading-h5-letterSpacing: var(--typography-letterSpacing-normal);
         --typography-heading-h5-fontFamily: var(--typography-fontFamily-sans);
 
-        --typography-heading-h6-fontSize: var(--typography-fontSize-lg);
+        /* fluid: 16px at 320 -> 18px at 992. (18-16)/6.72=0.2976vw, (16-(18-16)/2.1)/16=0.94048rem */
+        --typography-heading-h6-fontSizeMin: 1rem; /* 16px */
+        --typography-heading-h6-fontSize: clamp(
+          var(--typography-heading-h6-fontSizeMin),
+          calc(0.94048rem + 0.2976vw),
+          var(--typography-fontSize-lg)
+        );
         --typography-heading-h6-fontWeight: var(--typography-fontWeight-medium);
-        --typography-heading-h6-lineHeight: var(--typography-lineHeight-normal);
+        --typography-heading-h6-lineHeight: var(--typography-lineHeight-145);
         --typography-heading-h6-letterSpacing: var(--typography-letterSpacing-normal);
         --typography-heading-h6-fontFamily: var(--typography-fontFamily-sans);
 
         /* Body Text Tokens */
         --typography-body-large-fontSize: var(--typography-fontSize-lg);
         --typography-body-large-fontWeight: var(--typography-fontWeight-normal);
-        --typography-body-large-lineHeight: var(--typography-lineHeight-relaxed);
+        --typography-body-large-lineHeight: var(--typography-lineHeight-145);
         --typography-body-large-letterSpacing: var(--typography-letterSpacing-normal);
         --typography-body-large-fontFamily: var(--typography-fontFamily-sans);
 
@@ -252,13 +897,19 @@ export const tokens = css`
 
         --typography-body-small-fontSize: var(--typography-fontSize-sm);
         --typography-body-small-fontWeight: var(--typography-fontWeight-normal);
-        --typography-body-small-lineHeight: var(--typography-lineHeight-normal);
+        --typography-body-small-lineHeight: var(--typography-lineHeight-145);
         --typography-body-small-letterSpacing: var(--typography-letterSpacing-normal);
         --typography-body-small-fontFamily: var(--typography-fontFamily-sans);
 
-        --typography-body-lead-fontSize: var(--typography-fontSize-xl);
+        /* fluid: 18px at 320 -> 20px at 992. (20-18)/6.72=0.2976vw, (18-(20-18)/2.1)/16=1.06548rem */
+        --typography-body-lead-fontSizeMin: 1.125rem; /* 18px */
+        --typography-body-lead-fontSize: clamp(
+          var(--typography-body-lead-fontSizeMin),
+          calc(1.06548rem + 0.2976vw),
+          var(--typography-fontSize-xl)
+        );
         --typography-body-lead-fontWeight: var(--typography-fontWeight-normal);
-        --typography-body-lead-lineHeight: var(--typography-lineHeight-relaxed);
+        --typography-body-lead-lineHeight: var(--typography-lineHeight-140);
         --typography-body-lead-letterSpacing: var(--typography-letterSpacing-normal);
         --typography-body-lead-fontFamily: var(--typography-fontFamily-sans);
 
@@ -277,8 +928,32 @@ export const tokens = css`
         --typography-label-small-letterSpacing: var(--typography-letterSpacing-wide);
         --typography-label-small-fontFamily: var(--typography-fontFamily-sans);
 
+        /* The only role for the 11px step, and it carried a size and nothing
+           else -- so anything using it inherited its leading from whatever it
+           happened to sit inside, which is not a typography contract. The four
+           missing axes match label-small, one step up. It has no consumers
+           today; the five components that render 11px reach past it for the
+           primitive, and moving them is a visual change this phase does not
+           make. */
         --typography-label-extra-small-fontSize: var(--typography-fontSize-xxs);
-        --typography-label-xsmall-fontSize: var(--typography-fontSize-xs);
+        --typography-label-extra-small-fontWeight: var(--typography-fontWeight-medium);
+        --typography-label-extra-small-lineHeight: var(--typography-lineHeight-normal);
+        --typography-label-extra-small-letterSpacing: var(--typography-letterSpacing-wide);
+        --typography-label-extra-small-fontFamily: var(--typography-fontFamily-sans);
+
+        /* Deliberately size-only: bd-p variant=xsmall composes it with
+           body-small's weight, leading and tracking, so giving it axes of its
+           own would create a second answer to those questions.
+
+           It lives in the body family, not the label one. It was
+           --typography-label-xsmall-fontSize, one character away from
+           label-extra-small, which is a complete 11px role with a weight, a
+           leading and a family. Two names that close, describing things that
+           different, is a trap: one is a role you can ask for and the other is
+           a bare size that matches any one-axis 12px declaration on size
+           alone. Naming it for the component that owns it says which is
+           which. */
+        --typography-body-xsmall-fontSize: var(--typography-fontSize-xs);
 
         --typography-label-large-fontSize: var(--typography-fontSize-base);
         --typography-label-large-fontWeight: var(--typography-fontWeight-medium);
@@ -288,11 +963,56 @@ export const tokens = css`
         );
         --typography-label-large-fontFamily: var(--typography-fontFamily-sans);
 
-        --typography-label-xl-fontSize: var(--typography-fontSize-lg);
-        --typography-label-xl-fontWeight: var(--typography-fontWeight-medium);
-        --typography-label-xl-lineHeight: var(--typography-lineHeight-normal);
-        --typography-label-xl-letterSpacing: var(--typography-letterSpacing-normal);
-        --typography-label-xl-fontFamily: var(--typography-fontFamily-sans);
+        /* Control Label Tokens
+
+           label-* at control leading. Every label-* rung is lineHeight-normal
+           (1.5); a control -- a badge, a button -- needs 1.25 so its box can be
+           padding-driven without the line box forcing it taller.
+           scripts/typography-pairings.json already records 16px at 1.25 as
+           physically valid "because control text needs it", and rule 8 says
+           that file is a technical boundary rather than authorization, so the
+           authorization is here: this is the role that means "a label on a
+           control".
+
+           Motivated by badge.css.js and button.css.js's .bd-contact-btn, which
+           each arrived independently at medium + tight and had no role to ask
+           for. The three rungs mirror label-small / label-default /
+           label-large step for step. The one place they do not mirror is
+           tracking on the small rung: label-small is letterSpacing-wide, but
+           badge -- the atom this rung exists for -- renders normal, so the rung
+           describes its consumer rather than its twin. Everywhere else the only
+           axis that differs from the label-* rung of the same name is the
+           leading. */
+        --typography-control-label-small-fontSize: var(--typography-fontSize-xs);
+        --typography-control-label-small-fontWeight: var(--typography-fontWeight-medium);
+        --typography-control-label-small-lineHeight: var(--typography-lineHeight-tight);
+        --typography-control-label-small-letterSpacing: var(--typography-letterSpacing-normal);
+        --typography-control-label-small-fontFamily: var(--typography-fontFamily-sans);
+
+        --typography-control-label-default-fontSize: var(--typography-fontSize-sm);
+        --typography-control-label-default-fontWeight: var(--typography-fontWeight-medium);
+        --typography-control-label-default-lineHeight: var(--typography-lineHeight-tight);
+        --typography-control-label-default-letterSpacing: var(--typography-letterSpacing-normal);
+        --typography-control-label-default-fontFamily: var(--typography-fontFamily-sans);
+
+        --typography-control-label-large-fontSize: var(--typography-fontSize-base);
+        --typography-control-label-large-fontWeight: var(--typography-fontWeight-medium);
+        --typography-control-label-large-lineHeight: var(--typography-lineHeight-tight);
+        --typography-control-label-large-letterSpacing: var(--typography-letterSpacing-normal);
+        --typography-control-label-large-fontFamily: var(--typography-fontFamily-sans);
+
+        /* The rung label-xl used to occupy. label-xl was lg/medium/normal and
+           documented in vertical-rhythm.stories.js as "the name of a large
+           control" -- the same job this family names, but at label leading
+           rather than control leading, and with no consumer in the package.
+           Retired in favour of this. Note it was byte-identical to heading-h6,
+           which stays: that pair was two questions with coincidentally equal
+           answers, and heading-h6 is the one bd-h actually renders. */
+        --typography-control-label-xl-fontSize: var(--typography-fontSize-lg);
+        --typography-control-label-xl-fontWeight: var(--typography-fontWeight-medium);
+        --typography-control-label-xl-lineHeight: var(--typography-lineHeight-tight);
+        --typography-control-label-xl-letterSpacing: var(--typography-letterSpacing-normal);
+        --typography-control-label-xl-fontFamily: var(--typography-fontFamily-sans);
 
         /* Caption Tokens */
         --typography-caption-default-fontSize: var(--typography-fontSize-xs);
@@ -302,6 +1022,7 @@ export const tokens = css`
             --typography-letterSpacing-normal
         );
         --typography-caption-default-fontFamily: var(--typography-fontFamily-sans);
+        --typography-caption-default-color: var(--color-text-muted);
 
         --typography-caption-small-fontSize: var(--typography-fontSize-xs);
         --typography-caption-small-fontWeight: var(--typography-fontWeight-normal);
@@ -319,6 +1040,12 @@ export const tokens = css`
         --typography-link-default-fontFamily: inherit;
         --typography-link-default-textDecoration-default: underline;
         --typography-link-default-textDecoration-hover: none;
+        /* The gap between the text and its underline. It was spelled as a 2px
+           literal in seven places in bd-link, on a property the length rule
+           does not check, so nothing could see it and nothing could change it
+           in one move. */
+        --typography-link-underlineOffset: var(--spacing-2);
+        --typography-link-underlineThickness: var(--border-width-2);
 
         --typography-link-standalone-fontSize: var(--typography-fontSize-base);
         --typography-link-standalone-fontWeight: var(--typography-fontWeight-medium);
@@ -370,13 +1097,25 @@ export const tokens = css`
         --typography-display-lg-letterSpacing: var(--typography-letterSpacing-tight);
         --typography-display-lg-fontFamily: var(--typography-fontFamily-sans);
 
-        --typography-display-md-fontSize: var(--typography-fontSize-5xl);
+        /* fluid: 30px at 320 -> 48px at 992. (48-30)/6.72=2.6786vw, (30-(48-30)/2.1)/16=1.33929rem */
+        --typography-display-md-fontSizeMin: 1.875rem; /* 30px */
+        --typography-display-md-fontSize: clamp(
+          var(--typography-display-md-fontSizeMin),
+          calc(1.33929rem + 2.6786vw),
+          var(--typography-fontSize-5xl)
+        );
         --typography-display-md-fontWeight: var(--typography-fontWeight-bold);
         --typography-display-md-lineHeight: var(--typography-lineHeight-tight);
         --typography-display-md-letterSpacing: var(--typography-letterSpacing-tight);
         --typography-display-md-fontFamily: var(--typography-fontFamily-sans);
 
-        --typography-display-sm-fontSize: var(--typography-fontSize-4xl);
+        /* fluid: 30px at 320 -> 36px at 992. (36-30)/6.72=0.8929vw, (30-(36-30)/2.1)/16=1.69643rem */
+        --typography-display-sm-fontSizeMin: 1.875rem; /* 30px */
+        --typography-display-sm-fontSize: clamp(
+          var(--typography-display-sm-fontSizeMin),
+          calc(1.69643rem + 0.8929vw),
+          var(--typography-fontSize-4xl)
+        );
         --typography-display-sm-fontWeight: var(--typography-fontWeight-bold);
         --typography-display-sm-lineHeight: var(--typography-lineHeight-tight);
         --typography-display-sm-letterSpacing: var(--typography-letterSpacing-tight);
@@ -392,65 +1131,104 @@ export const tokens = css`
         --form-label-default-lineHeight: var(--typography-lineHeight-normal);
         --form-label-default-letterSpacing: var(--typography-letterSpacing-normal);
         --form-label-default-fontFamily: var(--typography-fontFamily-sans);
-        --form-label-default-color: var(--color-neutral-900);
-        --form-label-default-marginBottom: var(--spacing-1);
+        --form-label-default-color: var(--color-text-primary);
+        --form-label-default-marginBottom: var(--spacing-4);
 
         --form-label-large-fontSize: var(--typography-fontSize-lg);
         --form-label-large-fontWeight: var(--typography-fontWeight-medium);
         --form-label-large-lineHeight: var(--typography-lineHeight-normal);
         --form-label-large-letterSpacing: var(--typography-letterSpacing-normal);
         --form-label-large-fontFamily: var(--typography-fontFamily-sans);
-        --form-label-large-color: var(--color-neutral-900);
-        --form-label-large-marginBottom: var(--spacing-2);
+        --form-label-large-color: var(--color-text-primary);
+        --form-label-large-marginBottom: var(--spacing-8);
 
         --form-label-small-fontSize: var(--typography-fontSize-xs);
         --form-label-small-fontWeight: var(--typography-fontWeight-medium);
         --form-label-small-lineHeight: var(--typography-lineHeight-normal);
         --form-label-small-letterSpacing: var(--typography-letterSpacing-wide);
         --form-label-small-fontFamily: var(--typography-fontFamily-sans);
-        --form-label-small-color: var(--color-neutral-900);
-        --form-label-small-marginBottom: var(--spacing-1);
+        --form-label-small-color: var(--color-text-primary);
+        --form-label-small-marginBottom: var(--spacing-4);
 
-        --form-label-required-color: var(--color-red-500);
-        --form-label-required-marginLeft: var(--spacing-1);
+        --form-label-required-color: var(--status-error-accent);
+        --form-label-required-marginLeft: var(--spacing-4);
 
         /* Form Input Tokens */
-        --form-input-small-height: var(--dimension-34px);
+
+        /* The height of a control is derived, not chosen: padding, type step and
+           line-height, the same three bd-button derives its own height from.
+           That derivation is what keeps a field and a button of the same size
+           the same height on one row of a form.
+
+           These three said --dimension-36/44/56 and stated a height the system
+           does not draw. A small field renders 33.5px and a large one 54.5px;
+           only medium agreed, and it agreed by coincidence. Nothing read them,
+           so nothing surfaced the disagreement -- which is the argument for
+           spelling the derivation here rather than a rounder number, and for
+           shared/form-field.css.js reading these instead of repeating the calc
+           three times. Changing them changes no pixel; it changes what the
+           package tells a consumer the height is.
+
+           The line box these leave is 2px taller than the content box, because
+           the derivation counts padding but not the 1px border on each edge.
+           Measured at every size: no glyph clips, because an input centres its
+           line and paints into the padding. Correcting it would move a field
+           off its button, so it stays a recorded fact rather than a fix. */
+        --form-input-small-height: calc(
+          var(--spacing-8) * 2 + var(--typography-fontSize-sm) * var(--typography-lineHeight-tight)
+        );
         --form-input-small-fontSize: var(--typography-fontSize-sm);
-        --form-input-small-padding: var(--spacing-2) var(--spacing-3);
+        --form-input-small-padding: var(--spacing-8) var(--spacing-12);
         --form-input-small-borderRadius: var(--radius-sm);
 
-        --form-input-medium-height: var(--dimension-45px);
+        --form-input-medium-height: calc(
+          var(--spacing-12) * 2 + var(--typography-fontSize-base) * var(--typography-lineHeight-tight)
+        );
         --form-input-medium-fontSize: var(--typography-fontSize-base);
-        --form-input-medium-padding: var(--spacing-3) var(--spacing-4);
+        --form-input-medium-padding: var(--spacing-12) var(--spacing-16);
         --form-input-medium-borderRadius: var(--radius-md);
 
-        --form-input-large-height: var(--dimension-55px);
+        --form-input-large-height: calc(
+          var(--spacing-16) * 2 + var(--typography-fontSize-lg) * var(--typography-lineHeight-tight)
+        );
         --form-input-large-fontSize: var(--typography-fontSize-lg);
-        --form-input-large-padding: var(--spacing-4) var(--spacing-5);
+        --form-input-large-padding: var(--spacing-16) var(--spacing-20);
         --form-input-large-borderRadius: var(--radius-lg);
 
-        --form-input-default-backgroundColor: var(--color-neutral-0);
-        --form-input-default-borderColor: var(--color-neutral-300);
+        --form-input-default-backgroundColor: var(--color-surface-default);
+        --form-input-default-borderColor: var(--color-border-default);
         --form-input-default-borderWidth: var(--border-width-1);
-        --form-input-default-color: var(--color-neutral-900);
+        --form-input-default-color: var(--color-text-primary);
         --form-input-default-fontFamily: var(--typography-fontFamily-sans);
-        --form-input-default-lineHeight: var(--typography-lineHeight-normal);
-
-        --form-input-focus-borderColor: var(--color-blue-500);
+        /* There is deliberately no --form-input-default-lineHeight. There was
+           one, it said normal (1.5), it had no consumer, and it described the
+           opposite of what the control does: form-field.css.js sets tight and
+           records why -- at normal the line box stood taller than the content
+           box the derived height leaves, and the select clipped the descenders
+           of its own option text.
+
+           It is not restored as tight either. The control's height is
+           DERIVED from padding, type step and this leading, so exposing the
+           leading as a component token would let a consuming page change the
+           height by setting something that reads like a type preference. The
+           primitive is used at the one site that needs it, with its reason on
+           the line, which is what keeps the box and the text unable to
+           disagree. */
+
+        --form-input-focus-borderColor: var(--color-border-brand);
         --form-input-focus-boxShadow: var(--shadow-focus-outline-blue);
 
-        --form-input-error-backgroundColor: var(--color-red-50);
-        --form-input-error-borderColor: var(--color-red-500);
-        --form-input-error-placeholderColor: var(--color-red-400);
+        --form-input-error-backgroundColor: var(--status-error-surface);
+        --form-input-error-borderColor: var(--status-error-accent);
+        --form-input-error-placeholderColor: var(--color-red-600);
 
-        --form-input-success-backgroundColor: var(--color-green-50);
-        --form-input-success-borderColor: var(--color-green-500);
-        --form-input-success-placeholderColor: var(--color-green-400);
+        --form-input-success-backgroundColor: var(--status-success-surface);
+        --form-input-success-borderColor: var(--color-green-600);
+        --form-input-success-placeholderColor: var(--color-green-700);
 
-        --form-input-disabled-backgroundColor: var(--color-neutral-100);
-        --form-input-disabled-borderColor: var(--color-neutral-300);
-        --form-input-disabled-color: var(--color-neutral-500);
+        --form-input-disabled-backgroundColor: var(--color-surface-disabled);
+        --form-input-disabled-borderColor: var(--color-border-disabled);
+        --form-input-disabled-color: var(--color-text-subtle);
         --form-input-disabled-placeholderColor: var(--color-neutral-400);
 
         /* Form Help Text Tokens */
@@ -461,41 +1239,69 @@ export const tokens = css`
             --typography-letterSpacing-normal
         );
         --form-help-text-default-fontFamily: var(--typography-fontFamily-sans);
-        --form-help-text-default-color: var(--color-neutral-600);
-        --form-help-text-default-marginTop: var(--spacing-1);
-
-        --form-help-text-error-color: var(--color-red-600);
-        --form-help-text-success-color: var(--color-green-600);
-
-        /* Form Layout Tokens */
-        --form-fieldSpacing: var(--spacing-6);
-        --form-sectionSpacing: var(--spacing-8);
-        --form-labelSpacing: var(--spacing-1);
-        --form-helpTextSpacing: var(--spacing-1);
+        --form-help-text-default-color: var(--color-text-muted);
+        --form-help-text-default-marginTop: var(--spacing-4);
+
+        /* Measured against the tint the field itself takes in each state, not
+           against white — that is the background this text actually sits
+           beside. red-600 on red-50 is 4.92 and needs nothing.
+
+           success was green-700, which is 4.75 on white but only 4.51 on
+           green-50: passing by a hundredth, and the kind of margin that stops
+           passing the moment a tint moves. green-800 is 6.42 there, and is
+           already the step --color-text-success names for this role. */
+        --form-help-text-error-color: var(--status-error-accent);
+        --form-help-text-success-color: var(--color-text-success);
+
+        /* Form Layout Tokens
+
+           These were written against a step-indexed spacing scale, where the
+           number is the position on the scale, and never converted when the
+           scale became pixel-named, where the number is the value. So
+           --spacing-6 stopped meaning "the sixth step, 24px" and started
+           meaning 6px, silently — every token still resolved, and the lint has
+           no way to see it.
+
+           bd-fieldset consumes fieldSpacing, so a form built from it has been
+           stacking its fields 6px apart. Decoded as indices these read 24 and
+           32, which is what a form actually wants and what the value is set to
+           here. */
+        --form-fieldSpacing: var(--spacing-24);
+        --form-sectionSpacing: var(--spacing-32);
+        --form-labelSpacing: var(--spacing-4);
+        --form-helpTextSpacing: var(--spacing-4);
 
         /* ================================
              COMPONENT TOKENS - BUTTON
              ================================ */
 
         /* Button Size Tokens */
-        --button-small-height: var(--dimension-34px);
+        /* One size family. There were two — this one and --button-size-*, with
+           different padding in each and neither matching what the component
+           rendered. bd-button reads these.
+
+           No -height. The component derives its height from padding, type step
+           and line-height rather than pinning it, which is what keeps it equal
+           to a field of the same size; a height token here would be a second
+           answer that could disagree. */
         --button-small-fontSize: var(--typography-fontSize-sm);
-        --button-small-padding: var(--spacing-2) var(--spacing-3);
+        --button-small-padding: var(--spacing-8) var(--spacing-16);
+        --button-small-gap: var(--spacing-4);
         --button-small-borderRadius: var(--radius-sm);
 
-        --button-medium-height: var(--dimension-45px);
         --button-medium-fontSize: var(--typography-fontSize-base);
-        --button-medium-padding: var(--spacing-3) var(--spacing-4);
+        --button-medium-padding: var(--spacing-12) var(--spacing-24);
+        --button-medium-gap: var(--spacing-8);
         --button-medium-borderRadius: var(--radius-md);
 
-        --button-large-height: var(--dimension-55px);
         --button-large-fontSize: var(--typography-fontSize-lg);
-        --button-large-padding: var(--spacing-4) var(--spacing-5);
+        --button-large-padding: var(--spacing-16) var(--spacing-32);
+        --button-large-gap: var(--spacing-8);
         --button-large-borderRadius: var(--radius-lg);
 
         /* Button Default State */
         --button-default-backgroundColor: var(--color-neutral-0);
-        --button-default-borderColor: var(--color-neutral-300);
+        --button-default-borderColor: var(--color-neutral-400);
         --button-default-borderWidth: var(--border-width-1);
         --button-default-color: var(--color-neutral-900);
         --button-default-fontFamily: var(--typography-fontFamily-sans);
@@ -518,113 +1324,142 @@ export const tokens = css`
         --button-shared-disabled-opacity: 0.6;
         --button-shared-disabled-cursor: not-allowed;
 
-        /* Button Size Tokens */
-        --button-size-small-padding-vertical: var(--spacing-2);
-        --button-size-small-padding-horizontal: var(--spacing-4);
-        --button-size-small-fontSize: var(--typography-fontSize-sm);
-        --button-size-small-height: var(--dimension-34px);
-        --button-size-small-borderRadius: var(--radius-sm);
-        --button-size-small-gap: var(--spacing-1);
-
-        --button-size-medium-padding-vertical: var(--spacing-3);
-        --button-size-medium-padding-horizontal: var(--spacing-5);
-        --button-size-medium-fontSize: var(--typography-fontSize-base);
-        --button-size-medium-height: var(--dimension-45px);
-        --button-size-medium-borderRadius: var(--radius-md);
-        --button-size-medium-gap: var(--spacing-2);
-
-        --button-size-large-padding-vertical: var(--spacing-4);
-        --button-size-large-padding-horizontal: var(--spacing-6);
-        --button-size-large-fontSize: var(--typography-fontSize-lg);
-        --button-size-large-height: var(--dimension-55px);
-        --button-size-large-borderRadius: var(--radius-lg);
-        --button-size-large-gap: var(--spacing-2);
-
-        /* Button Primary State */
-        --button-primary-background-default: var(--color-blue-500);
-        --button-primary-text-default: var(--color-neutral-0);
-        --button-primary-border-default: var(--color-blue-500);
-        --button-primary-background-hover: var(--color-blue-600);
-        --button-primary-border-hover: var(--color-blue-600);
-        --button-primary-background-active: var(--color-blue-700);
-        --button-primary-border-active: var(--color-blue-700);
-        --button-primary-border-focus: var(--color-blue-500);
-        --button-primary-background-disabled: var(--color-neutral-300);
-        --button-primary-text-disabled: var(--color-neutral-500);
-        --button-primary-border-disabled: var(--color-neutral-300);
-
-        /* Button Secondary State */
-        --button-secondary-background-default: var(--color-neutral-950);
-        --button-secondary-text-default: var(--color-neutral-0);
-        --button-secondary-border-default: var(--color-neutral-950);
-        --button-secondary-background-hover: var(--color-neutral-900);
-        --button-secondary-text-hover: var(--color-neutral-0);
-        --button-secondary-border-hover: var(--color-neutral-900);
-        --button-secondary-background-active: var(--color-neutral-800);
-        --button-secondary-text-active: var(--color-neutral-0);
-        --button-secondary-border-active: var(--color-neutral-800);
-        --button-secondary-border-focus: var(--color-neutral-950);
-        --button-secondary-background-disabled: var(--color-neutral-300);
-        --button-secondary-text-disabled: var(--color-neutral-500);
-        --button-secondary-border-disabled: var(--color-neutral-300);
-
-        /* Button Tertiary Primary State */
-        --button-tertiaryPrimary-background-default: transparent;
-        --button-tertiaryPrimary-text-default: var(--color-blue-500);
-        --button-tertiaryPrimary-border-default: var(--color-blue-500);
-        --button-tertiaryPrimary-borderWidth: var(--border-width-2);
-        --button-tertiaryPrimary-background-hover: var(--color-blue-50);
-        --button-tertiaryPrimary-text-hover: var(--color-blue-500);
-        --button-tertiaryPrimary-border-hover: var(--color-blue-500);
-        --button-tertiaryPrimary-background-active: var(--color-blue-500);
-        --button-tertiaryPrimary-text-active: var(--color-neutral-0);
-        --button-tertiaryPrimary-border-active: var(--color-blue-500);
-        --button-tertiaryPrimary-border-focus: var(--color-blue-500);
-        --button-tertiaryPrimary-background-disabled: transparent;
-        --button-tertiaryPrimary-text-disabled: var(--color-neutral-400);
-        --button-tertiaryPrimary-border-disabled: var(--color-neutral-300);
-
-        /* Button Tertiary Secondary State */
-        --button-tertiarySecondary-background-default: transparent;
-        --button-tertiarySecondary-text-default: var(--color-neutral-900);
-        --button-tertiarySecondary-border-default: var(--color-neutral-900);
-        --button-tertiarySecondary-borderWidth: var(--border-width-2);
-        --button-tertiarySecondary-background-hover: var(--color-neutral-100);
-        --button-tertiarySecondary-text-hover: var(--color-neutral-900);
-        --button-tertiarySecondary-border-hover: var(--color-neutral-900);
-        --button-tertiarySecondary-background-active: var(--color-neutral-900);
-        --button-tertiarySecondary-text-active: var(--color-neutral-0);
-        --button-tertiarySecondary-border-active: var(--color-neutral-900);
-        --button-tertiarySecondary-border-focus: var(--color-neutral-900);
-        --button-tertiarySecondary-background-disabled: transparent;
-        --button-tertiarySecondary-text-disabled: var(--color-neutral-400);
-        --button-tertiarySecondary-border-disabled: var(--color-neutral-300);
-
-        /* Button CTA State */
-        --button-cta-background-default: var(--color-red-500);
-        --button-cta-text-default: var(--color-neutral-0);
-        --button-cta-border-default: var(--color-red-500);
-        --button-cta-background-hover: var(--color-red-600);
-        --button-cta-border-hover: var(--color-red-600);
-        --button-cta-background-active: var(--color-red-700);
-        --button-cta-border-active: var(--color-red-700);
-        --button-cta-border-focus: var(--color-red-500);
-        --button-cta-background-disabled: var(--color-neutral-300);
-        --button-cta-text-disabled: var(--color-neutral-500);
-        --button-cta-border-disabled: var(--color-neutral-300);
-
-        /* Button Empty State */
-        --button-empty-background-default: var(--color-neutral-200);
-        --button-empty-text-default: transparent;
-        --button-empty-border-default: var(--color-neutral-200);
-
-        /* Button Disabled State */
-        --button-disabled-backgroundColor: var(--color-neutral-100);
-        --button-disabled-borderColor: var(--color-neutral-300);
-        --button-disabled-color: var(--color-neutral-500);
-
-        /* Button Focus State */
-        --button-focus-boxShadow: var(--shadow-focus-outline-blue);
+        /* ---- variant colours -------------------------------------------
+           Named for the kind attribute they serve, because that is the public
+           vocabulary: primary, secondary, tertiary, ghost, accent, white and
+           outline-white. They used to be named tertiaryPrimary,
+           tertiarySecondary and cta, which no consumer could map onto the
+           component without reading its source.
+
+           bd-button aliases each of these onto a --button-*-bg property on its
+           own :host, so there are two override points and they do different
+           jobs: set the token on :root to move every button in the document,
+           or the alias on the bd-button element to move one. The alias is also what
+           surface="dark" switches, which is why the component keeps it.
+
+           Every value here is what the component already renders. The old
+           values had drifted apart from it in four places — secondary's hover
+           and active, tertiary's hover border and ghost's active fill — so
+           wiring them up unchanged would have moved pixels.
+
+           The per-variant -focus and -disabled sets are gone. The component
+           draws one focus ring for every variant, from --focus-outline-primary,
+           and one shared disabled treatment; thirty tokens described per-variant
+           versions of both that nothing rendered. --button-empty-* went with
+           them: there is no empty kind. */
+
+        /* primary: blue fill */
+        --button-primary-background-default: var(--color-action-primary);
+        --button-primary-background-hover: var(--color-action-primary-hover);
+        --button-primary-background-active: var(--color-action-primary-active);
+        --button-primary-text-default: var(--color-action-on-fill);
+
+        /* secondary: near-black fill */
+        --button-secondary-background-default: var(--color-action-secondary);
+        --button-secondary-background-hover: var(--color-action-secondary-hover);
+        --button-secondary-background-active: var(--color-action-secondary-active);
+        --button-secondary-text-default: var(--color-action-on-fill);
+
+        /* tertiary: blue outline. text-hover is blue-600, not blue-500: on the
+           blue-50 hover fill the lighter step measures 4.20:1 and fails 1.4.3,
+           where blue-600 gives 5.72.
+           .
+           text-default is blue-600 for the same reason, applied to the state a
+           reader actually sits in. The line above fixed hover, where blue-500
+           failed outright, and left the resting state on blue-500 at 4.53:1 --
+           passing 4.5 by 0.03 on pure white and failing on any tint, which is
+           the margin CLAUDE.md says is not real. Both states now name the same
+           ink role, and the role is the category-correct one: --color-action-primary
+           is an interaction role for fills, not ink, and it was being read by a
+           color: property. Measured 4.53:1 -> 6.18:1 on all six consumers.
+           The ring is deliberately NOT changed here and stays blue-500: it is
+           non-text UI at a 3:1 bar, it passes, and moving it would mean naming a
+           blue-600 border role that does not exist. See the plan's backlog. */
+        --button-tertiary-text-default: var(--color-text-brand);
+        --button-tertiary-border-default: var(--color-border-brand);
+        --button-tertiary-background-hover: var(--color-surface-info);
+        --button-tertiary-text-hover: var(--color-text-brand);
+        --button-tertiary-border-hover: var(--color-action-primary-hover);
+        --button-tertiary-background-active: var(--color-action-primary);
+        --button-tertiary-text-active: var(--color-action-on-fill);
+
+        /* ghost: dark outline */
+        --button-ghost-text-default: var(--color-text-primary);
+        --button-ghost-border-default: var(--color-border-strong);
+        --button-ghost-background-hover: var(--color-surface-muted);
+        --button-ghost-text-hover: var(--color-text-primary);
+        --button-ghost-background-active: var(--color-action-secondary);
+        --button-ghost-text-active: var(--color-action-on-fill);
+
+        /* accent: red fill. This system's conversion colour — Buy now and the
+           like — not a danger signal; there is deliberately no danger variant.
+           red-600, not red-500: white on red-500 measures 4.00:1 and fails. */
+        --button-accent-background-default: var(--color-action-accent);
+        --button-accent-background-hover: var(--color-action-accent-hover);
+        --button-accent-background-active: var(--color-action-accent-active);
+        --button-accent-text-default: var(--color-action-on-fill);
+        --button-accent-ring-default: transparent;
+
+        /* white and outline-white: fixed presets for a solid-colour banner,
+           where even a surface="dark" primary would sit too close in tone.
+           They ignore surface on purpose.
+
+           text-default is blue-600 rather than blue-500: white is the fill
+           here, and blue-500 on white is 4.53:1 — the marginal step the
+           contrast note warns against for text.
+
+           The translucent whites were rgba(255,255,255,…) and #ffffff8c
+           literals, which no theme could reach. color-mix keeps the alpha and
+           puts the colour back on the palette. */
+        --button-white-background-default: var(--color-neutral-0);
+        --button-white-background-hover: var(--color-blue-50);
+        --button-white-background-active: var(--color-blue-100);
+        /* blue-600 by name, not --color-text-brand. The preset is fixed --
+           a white fill on a brand band, in any theme -- so its ink must be
+           fixed too. Reading the role mixed a fill that never switches with a
+           label that does: text-brand goes light in a dark theme and measured
+           2.36:1 on the white fill (dark mode finding 8). */
+        --button-white-text-default: var(--color-blue-600);
+
+        --button-outline-white-text-default: var(--color-action-on-fill);
+        /* 71% rather than 55%. This edge is the only thing bounding an
+           outline-white button, so it carries the 3:1 of WCAG 1.4.11 on its
+           own. Measured over the grounds the preset is actually used on, 55%
+           gave 2.34 on blue-500 and 2.90 on blue-600 and only cleared on
+           blue-700 at 3.65. 71% is the lowest value that clears all three
+           with one number, so the token stops depending on which blue is
+           behind it. */
+        --button-outline-white-border-default: color-mix(in srgb, var(--color-neutral-0) 71%, transparent);
+        /* Hover and press DARKEN the band, they do not wash it white. A white
+           wash lightened the blue under a white label: 3.91:1 on hover and
+           3.38 pressed over blue-500, and 4.22 pressed over blue-600 -- under
+           the 4.5 the label needs. 10% and 20% black take blue-500 to 5.40
+           and 6.49 and give the 71% edge more ground (3.46 and 4.03); every
+           ground the preset sits on now clears, the CTA gradient included.
+           Darker on hover is also what every filled button already does.
+           .
+           The trade-off, chosen knowingly: on the navy end of the CTA
+           gradient (#061a5c) darkening barely shows, a 1.05 step where the
+           white wash gave 1.31. The label is what must pass; the hover there
+           is carried by the cursor. A white wash cannot work on blue-500 at
+           all, where the label clears 4.5 at rest by 0.03. */
+        --button-outline-white-background-hover: color-mix(in srgb, var(--color-neutral-1000) 10%, transparent);
+        --button-outline-white-background-active: color-mix(in srgb, var(--color-neutral-1000) 20%, transparent);
+
+        /* Shared across every variant. Filled kinds go grey; outlined ones keep
+           a transparent fill and take the subtle border. Contrast is exempt
+           here under WCAG 1.4.3.
+
+           borderColor is --color-border-disabled: the role named for the state
+           it expresses, and the one disabled-edge value the whole control
+           family now shares. It read neutral-300 once, then moved to
+           neutral-200 to match what the component drew; bd-checkbox and
+           bd-radio have since moved to neutral-300, so token and component
+           agree again -- a step darker, 2.27:1 against the page where
+           neutral-200 gave 1.66, and still lighter than any enabled edge. */
+        --button-disabled-backgroundColor: var(--color-surface-disabled);
+        --button-disabled-borderColor: var(--color-border-disabled);
+        --button-disabled-color: var(--color-text-subtle);
 
         /* ================================
              COMPONENT TOKENS - ANNOTATION
@@ -643,9 +1478,9 @@ export const tokens = css`
         --citation-reference-fontSize: inherit;
         --citation-reference-fontWeight: var(--typography-fontWeight-normal);
         --citation-reference-lineHeight: inherit;
-        --citation-reference-color: var(--color-blue-600);
+        --citation-reference-color: var(--color-text-brand);
         --citation-reference-textDecoration: underline;
-        --citation-reference-hover-color: var(--color-blue-700);
+        --citation-reference-hover-color: var(--color-text-brand-hover);
         --citation-reference-hover-textDecoration: none;
 
         /* Mathematical Notation Tokens */
@@ -666,36 +1501,21 @@ export const tokens = css`
              ================================ */
 
         /* Icon Size Tokens */
-        --icon-xs-size: var(--dimension-12px);
-        --icon-sm-size: var(--dimension-16px);
-        --icon-md-size: var(--dimension-20px);
-        --icon-lg-size: var(--dimension-24px);
-        --icon-xl-size: var(--dimension-32px);
-        --icon-2xl-size: var(--dimension-48px);
-        --icon-3xl-size: var(--dimension-64px);
-
-        /* Icon Context Tokens */
-        --icon-button-small-size: var(--dimension-16px);
-        --icon-button-medium-size: var(--dimension-20px);
-        --icon-button-large-size: var(--dimension-24px);
-
-        --icon-form-small-size: var(--dimension-16px);
-        --icon-form-medium-size: var(--dimension-20px);
-        --icon-form-large-size: var(--dimension-24px);
-
-        /* Icon State Tokens */
-        --icon-default-color: var(--color-neutral-600);
-        --icon-hover-color: var(--color-neutral-700);
-        --icon-active-color: var(--color-neutral-800);
-        --icon-disabled-color: var(--color-neutral-400);
-
-        --icon-primary-color: var(--color-blue-500);
-        --icon-primary-hover-color: var(--color-blue-600);
-        --icon-primary-active-color: var(--color-blue-700);
-
-        --icon-success-color: var(--color-green-500);
-        --icon-warning-color: var(--color-yellow-500);
-        --icon-error-color: var(--color-red-500);
+        --icon-xs-size: var(--dimension-12);
+        --icon-sm-size: var(--dimension-16);
+        --icon-md-size: var(--dimension-20);
+        --icon-lg-size: var(--dimension-24);
+        --icon-xl-size: var(--dimension-32);
+        --icon-2xl-size: var(--dimension-48);
+        --icon-3xl-size: var(--dimension-64);
+
+        /* The context aliases (--icon-button-*, --icon-form-*) and the ten
+           --icon-*-color tokens were removed when the icon elements moved onto
+           the size scale and currentColor. The aliases said the same thing as a
+           step — --icon-button-small-size and --icon-sm-size were both 16px —
+           and the colours described states an icon no longer has: it takes the
+           colour of the text it sits in, so there is nothing per-state to keep
+           in step. */
 
         /* ================================
              CORE SPACING TOKENS
@@ -729,114 +1549,14 @@ export const tokens = css`
         --spacing-112: 7rem; /* 112px */
         --spacing-128: 8rem; /* 128px */
 
-        /* =====================
-            OLD VALUES -------------------------------------------------------------------------------
-        ====================== */
-
-        /* Display default */
-        --display-xxsmall: 44px; /* 58.652px = 3.666rem */
-        --display-xsmall: 48px; /* 63.984px = 3.999rem */
-        --display-small: 52px; /* 69.316px = 4.332rem */
-        --display-medium: 56px; /* 74.648px = 4.666rem */
-        --display-large: 60px; /* 79.98px = 5rem */
-        --display-xlarge: 64px; /* 85.312px = 5.333rem */
-
-        /* Display mobile */
-        --display-xxsmall-mobile: 34px; /* 45.322px = 2.833rem */
-        --display-xsmall-mobile: 36px; /* 47.988px = 2.999rem */
-        --display-small-mobile: 38px; /* 50.654px = 3.167rem */
-        --display-medium-mobile: 40px; /* 53.32px = 3.333rem */
-        --display-large-mobile: 44px; /* 58.652px = 3.666rem */
-        --display-xlarge-mobile: 48px; /* 63.984px = 3.999rem */
-
-        /* Heading default */
-        --heading-xxsmall: 18px; /* 23.994px = 1.5rem */
-        --heading-xsmall: 20px; /* 26.66px = 1.667rem */
-        --typography-heading-h4-fontSize: 24px; /* 31.992px = 2rem */
-        --heading-medium: 28px; /* 37.324px = 2.333rem */
-        --typography-fontSize-3xl: 32px; /* 42.656px = 2.667rem */
-        --heading-xlarge: 36px; /* 47.988px = 2.999rem */
-        --heading-xxlarge: 40px; /* 53.32px = 3.333rem */
-
-        /* Body default */
-        --body-small: 13px; /* 17.329px = 1.083rem */
-        --typography-body-small-fontSize: 14px; /* 18.662px = 1.167rem */
-        --typography-body-regular-fontSize: 16px; /* 21.328px = 1.333rem */
-        --body-xlarge: 18px; /* 23.994px = 1.5rem */
-
-        /* Caption default */
-        --typography-label-extra-small-fontSize: 11px; /* 14.663px = 0.917rem */
-        --typography-label-small-fontSize: 12px; /* 15.996px = 1rem */
-
-        /* Display Default */
-        --display-xlarge-line-height: 1.1; /* For 60px */
-        --display-medium-line-height: 1.15; /* For 52px */
-
-        /* Display Mobile */
-        --display-xlarge-mobile-line-height: 1.15; /* For 44px */
-        --display-medium-mobile-line-height: 1.2; /* For 38px */
-
-        /* Heading */
-        --heading-xlarge-line-height: 1.2; /* For 36px */
-        --typography-heading-h4-fontSize-line-height: 1.3; /* For 24px */
-
-        /* Body */
-        --typography-body-regular-fontSize-line-height: 1.5; /* For 16px */
-
-        /* Caption */
-        --typography-label-small-fontSize-line-height: 1.35; /* For 12px */
-
-        /* Spacing Tokens
-        -----------------------------------------------*/
-        /* Base spacing tokens - Based on 4px grid */
-        --space-none: 0;
-        --space-4xs: 0.125rem; /* 2px */
-        --space-3xs: 0.25rem; /* 4px */
-        --space-2xs: 0.5rem; /* 8px */
-        --space-xs: 0.75rem; /* 12px */
-        --space-sm: 1rem; /* 16px */
-        --space-md: 1.5rem; /* 24px */
-        --space-lg: 2rem; /* 32px */
-        --space-xl: 2.5rem; /* 40px */
-        --space-2xl: 3rem; /* 48px */
-        --space-3xl: 4rem; /* 64px */
-        --space-4xl: 6rem; /* 96px */
-        --space-5xl: 8rem; /* 128px */
-
-        /* Semantic Padding Tokens */
-        --padding-button: var(--space-xs) var(--space-md);
-        --padding-input: var(--space-xs);
-        --padding-card: var(--space-md);
-        --padding-card-sm: var(--space-sm);
-        --padding-card-lg: var(--space-lg);
-
-        --padding-section: var(--space-3xl) 0;
-        --padding-section-sm: var(--space-2xl) 0;
-        --padding-section-lg: var(--space-4xl) 0;
-
-        /* Container and Layout Tokens */
-        --container-padding: var(--space-md);
-        --container-padding-sm: var(--space-sm);
-        --container-padding-lg: var(--space-lg);
-
-        /* Inset (Padding All Sides) Tokens */
-        --inset-xs: var(--space-xs);
-        --inset-sm: var(--space-sm);
-        --inset-md: var(--space-md);
-        --inset-lg: var(--space-lg);
-
-        /* Stack (Vertical Spacing) Tokens */
-        --stack-xs: var(--space-xs);
-        --stack-sm: var(--space-sm);
-        --stack-md: var(--space-md);
-        --stack-lg: var(--space-lg);
-        --stack-xl: var(--space-xl);
-
-        /* Inline (Horizontal Spacing) Tokens */
-        --inline-xs: var(--space-xs);
-        --inline-sm: var(--space-sm);
-        --inline-md: var(--space-md);
-        --inline-lg: var(--space-lg);
+        /* The OLD VALUES block stood here: --display-*, --heading-*, --body-* and
+           --caption-* as pixel font sizes, and a second spacing vocabulary in
+           --space-*, --padding-*, --container-*, --inset-*, --stack-* and
+           --inline-*. Forty-nine tokens, every one a duplicate of something on
+           a live scale under a different name, and not one of them referenced
+           by any component. They are gone. Type comes from
+           --typography-fontSize-* and the component type tokens above it;
+           spacing comes from --spacing-*. */
 
         /* Accessibility Spacing Tokens
         -----------------------------------------------*/
@@ -848,7 +1568,20 @@ export const tokens = css`
         --content-width-readable: 70ch; /* Approximately 70 characters per line */
         --content-width-max: 1200px; /* Maximum overall content width */
 
-        /** GRID TOKENS
+        /** GRID AND BREAKPOINT TOKENS
+
+           These have no consumer in this package and are kept deliberately.
+           A media condition cannot read a custom property — @media
+           (max-width: var(--breakpoint-sm)) is not valid CSS — so a breakpoint
+           token can never be referenced the way a colour is. It exists so the
+           six values have one place to be read from, by the lint that checks
+           media queries against them and by anything generating CSS. The grid
+           tokens are the same case: a layout that wants them reads them, and
+           nothing in the atom layer does.
+
+           They are the exception. Everything else here that nothing references
+           is dead weight, and the OLD VALUES and FONT TOKENS blocks that used
+           to sit below were removed for exactly that reason.
          */
         /* Grid container max widths */
         --grid-container-max-xs: 100%; /* mobile full width */
@@ -882,162 +1615,19 @@ export const tokens = css`
         --breakpoint-xxl: 1400px;
         /* =====================
             FONT-FACE DEFINITIONS
+            Intentionally NOT here. @font-face nested inside a :host rule is
+            discarded at parse time, and even at the top level of a shadow-root
+            stylesheet it never reaches document.fonts. Font faces must be
+            loaded in document scope: see src/tokens/fonts.css.
         ====================== */
 
-        @font-face {
-            font-family: "IBM Plex Mono";
-            font-style: normal;
-            font-weight: 700;
-            src: url("../assets/fonts/IBMPlexMono-Bold.woff2") format("woff2");
-        }
-        @font-face {
-            font-family: "IBM Plex Mono";
-            font-style: normal;
-            font-weight: 700;
-            src: url("../assets/fonts/IBMPlexMono-BoldItalic.woff2") format("woff2");
-        }
-
-        @font-face {
-            font-family: "IBM Plex Mono";
-            font-style: italic;
-            font-weight: 300;
-            src: url("../assets/fonts/IBMPlexMono-Italic.woff2") format("woff2");
-        }
-        @font-face {
-            font-family: "IBM Plex Mono";
-            font-style: normal;
-            font-weight: 300;
-            src: url("../assets/fonts/IBMPlexMono-Light.woff2") format("woff2");
-        }
-        @font-face {
-            font-family: "IBM Plex Mono";
-            font-style: italic;
-            font-weight: 300;
-            src: url("../assets/fonts/IBMPlexMono-LightItalic.woff2") format("woff2");
-        }
-
-        @font-face {
-            font-family: "IBM Plex Mono";
-            font-style: italic;
-            font-weight: 500;
-            src: url("../assets/fonts/IBMPlexMono-Medium.woff2") format("woff2");
-        }
-        @font-face {
-            font-family: "IBM Plex Mono";
-            font-style: italic;
-            font-weight: 500;
-            src: url("../assets/fonts/IBMPlexMono-MediumItalic.woff2") format("woff2");
-        }
-        @font-face {
-            font-family: "IBM Plex Mono";
-            font-style: italic;
-            font-weight: 400;
-            src: url("../assets/fonts/IBMPlexMono-Regular.woff2") format("woff2");
-        }
-        @font-face {
-            font-family: "IBM Plex Mono";
-            font-style: italic;
-            font-weight: 600;
-            src: url("../assets/fonts/IBMPlexMono-SemiBold.woff2") format("woff2");
-        }
-        @font-face {
-            font-family: "IBM Plex Mono";
-            font-style: italic;
-            font-weight: 600;
-            src: url("../assets/fonts/IBMPlexMono-SemiBoldItalic.woff2") format("woff2");
-        }
-
-        /*
-        IBM PLEX SANS
-        */
-
-        @font-face {
-            font-family: "IBMPlexSans";
-            font-style: normal;
-            font-weight: 700;
-            src: url("../assets/fonts/IBMPlexSans-Bold.woff2") format("woff2");
-        }
-        @font-face {
-            font-family: "IBMPlexSans";
-            font-style: normal;
-            font-weight: 700;
-            src: url("../assets/fonts/IBMPlexSans-BoldItalic.woff2") format("woff2");
-        }
-
-        @font-face {
-            font-family: "IBMPlexSans";
-            font-style: italic;
-            font-weight: 300;
-            src: url("../assets/fonts/IBMPlexSans-Italic.woff2") format("woff2");
-        }
-        @font-face {
-            font-family: "IBMPlexSans";
-            font-style: normal;
-            font-weight: 300;
-            src: url("../assets/fonts/IBMPlexSans-Light.woff2") format("woff2");
-        }
-        @font-face {
-            font-family: "IBMPlexSans";
-            font-style: italic;
-            font-weight: 300;
-            src: url("../assets/fonts/IBMPlexSans-LightItalic.woff2") format("woff2");
-        }
-
-        @font-face {
-            font-family: "IBMPlexSans";
-            font-style: italic;
-            font-weight: 500;
-            src: url("../assets/fonts/IBMPlexSans-Medium.woff2") format("woff2");
-        }
-        @font-face {
-            font-family: "IBMPlexSans";
-            font-style: italic;
-            font-weight: 500;
-            src: url("../assets/fonts/IBMPlexSans-MediumItalic.woff2") format("woff2");
-        }
-        @font-face {
-            font-family: "IBMPlexSans";
-            font-style: italic;
-            font-weight: 400;
-            src: url("../assets/fonts/IBMPlexSans-Regular.woff2") format("woff2");
-        }
-        @font-face {
-            font-family: "IBMPlexSans";
-            font-style: italic;
-            font-weight: 600;
-            src: url("../assets/fonts/IBMPlexSans-SemiBold.woff2") format("woff2");
-        }
-        @font-face {
-            font-family: "IBMPlexSans";
-            font-style: italic;
-            font-weight: 600;
-            src: url("../assets/fonts/IBMPlexSans-SemiBoldItalic.woff2") format("woff2");
-        }
-
-        /* =====================
-            FONT TOKENS
-        ====================== */
-        /* IBM Plex Mono */
-        --font-family-mono: "IBM Plex Mono", monospace;
-        --font-weight-mono-light: 300;
-        --font-weight-mono-regular: 400;
-        --font-weight-mono-medium: 500;
-        --font-weight-mono-semibold: 600;
-        --font-weight-mono-bold: 700;
-
-        --font-style-mono-normal: normal;
-        --font-style-mono-italic: italic;
-
-        /* IBM Plex Sans */
-        --typography-fontFamily-sans: 'IBM Plex Sans', sans-serif;
-        --font-weight-sans-light: 300;
-        --typography-body-large-fontWeight: 400;
-        --font-weight-sans-medium: 500;
-        --typography-fontWeight-semibold: 600;
-        --typography-fontWeight-bold: 700;
+        /* The FONT TOKENS block stood here: --font-weight-mono-*,
+           --font-weight-sans-*, --font-style-mono-* and --font-style-sans-*.
+           Thirteen tokens duplicating --typography-fontWeight-* under a second
+           name, with regular where the live scale says normal, and nothing
+           consuming any of them. --font-family-mono went earlier, with bd-li.
+           A weight is a weight whichever face it is set in. */
 
-        --font-style-sans-normal: normal;
-        --font-style-sans-italic: italic;
         /* Awards section — Orbit Frame 14 (node 1882:9342) */
         --layout-awards-section-background: var(--color-blue-50);
         --layout-awards-banner-max-width: 37.5rem; /* legacy narrow cap; prefer cluster */
@@ -1045,7 +1635,55 @@ export const tokens = css`
         --layout-awards-intro-max-width: 39.4375rem; /* 631px — headline stack */
         /* Legacy: narrow lower block from Orbit; prefer --layout-ensemble-content-max for compare-aligned grids */
         --layout-awards-content-max-width: 53.0625rem; /* 849px */
+        /* There is no page-width token. The page column is an implementation --
+           src/components/shared/ensemble.css.js -- on the grid container scale
+           above (--grid-container-max-* with --grid-padding-*), which is what
+           Foundations/Grid System documented and nothing had built. A width token
+           here is how six ensembles came to hold one literal each and seven other
+           modules a different one. This padding step stays only because the blog
+           still reads it. */
         --layout-ensemble-inline-padding: var(--spacing-24);
 
+    `;
+
+const LAYER = 'bd-tokens';
+const INSTALLED = '__bdDesignTokens';
+
+function install() {
+  if (typeof document === 'undefined') return;
+
+  const rule = `@layer ${LAYER} { :root {${declarations}} }`;
+
+  if ('adoptedStyleSheets' in document && typeof CSSStyleSheet === 'function') {
+    if (document.adoptedStyleSheets.some(sheet => sheet[INSTALLED])) return;
+    try {
+      const sheet = new CSSStyleSheet();
+      sheet.replaceSync(rule);
+      sheet[INSTALLED] = true;
+      document.adoptedStyleSheets = [...document.adoptedStyleSheets, sheet];
+      return;
+    } catch {
+      // fall through to the <style> path below
     }
-`;
+  }
+
+  // Fallback for anything without constructable stylesheets. Without this the
+  // whole token set would simply be absent rather than degrading.
+  if (document.querySelector(`style[data-${LAYER}]`)) return;
+  const style = document.createElement('style');
+  style.setAttribute(`data-${LAYER}`, '');
+  style.textContent = rule;
+  document.head.appendChild(style);
+}
+
+install();
+
+/** The raw declaration text, for tooling that needs to emit tokens elsewhere. */
+export { declarations as tokenDeclarations };
+
+/**
+ * @deprecated Components no longer need to adopt this — the tokens live in
+ * document scope. Kept, and deliberately empty, so that any existing
+ * `static styles = [tokens, componentCSS]` keeps working unchanged.
+ */
+export const tokens = css``;