okchroma 0.1.0 → 0.1.1

package/dist-lib/index.cjs

@@ -20,6 +20,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  CSS_FAMILY: () => CSS_FAMILY,
   DEFAULT_LINK_HEX: () => DEFAULT_LINK_HEX,
   EXT_KEY: () => EXT_KEY,
   INK_0: () => INK_0,
@@ -46,11 +47,14 @@ __export(index_exports, {
   checkCollision: () => checkCollision,
   checkHueCollision: () => checkHueCollision,
   classifyArchetype: () => classifyArchetype,
+  ctaBorderRung: () => ctaBorderRung,
+  ctaNeedsBorder: () => ctaNeedsBorder,
   emitDtcgRamp: () => emitDtcgRamp,
   generateNeutralScale: () => generateNeutralScale,
   generateScale: () => generateScale,
   generateSubtleSecondary: () => generateSubtleSecondary,
   neutralCss: () => neutralCss,
+  pageStopFor: () => pageStopFor,
   parseToken: () => parseToken,
   resolveBrand: () => resolveBrand,
   resolveDtcgRamp: () => resolveDtcgRamp,
@@ -90,9 +94,11 @@ function stateStepL(restL, _mode, k) {
   return k * STATE_HOVER_K;
 }
 var OVERRIDE_LIGHT_BELOW = ARCHETYPES.find((a) => a.name === "rich").min;
+var OVERRIDE_DARK_ABOVE = ARCHETYPES.find((a) => a.name === "light").min;
 function stateFillL(restL, mode, k) {
   const natural = mode === "dark" ? 1 : -1;
-  const preferred = mode === "light" && restL < OVERRIDE_LIGHT_BELOW ? -natural : natural;
+  const overridden = mode === "light" ? restL < OVERRIDE_LIGHT_BELOW : restL > OVERRIDE_DARK_ABOVE;
+  const preferred = overridden ? -natural : natural;
   const fits = (d) => {
     const p = restL + d * stateStepL(restL, mode, 2);
     return p >= STATE_L_MIN && p <= STATE_L_MAX;
@@ -2619,7 +2625,7 @@ function generateNeutralScale(brandH, level = "default", contrastProfile) {
   scale.ctaHoverDark = nState(10, "dark", scale.ctaDark, 1);
   scale.ctaPressedDark = nState(11, "dark", scale.ctaDark, 2);
   const onEnforce = contrastProfile !== "apca";
-  const onFloor = contrastProfile === "apca" ? void 0 : 4.5;
+  const onFloor = 4.5;
   scale.onFillTextIsWhite = onTextIsWhite(apcaY(scale.cta.r, scale.cta.g, scale.cta.b), scale.cta.L, scale.cta.C, scale.cta.H, onEnforce, onFloor);
   scale.onFillTextIsWhiteDark = onTextIsWhite(apcaY(scale.ctaDark.r, scale.ctaDark.g, scale.ctaDark.b), scale.ctaDark.L, scale.ctaDark.C, scale.ctaDark.H, onEnforce, onFloor);
   return scale;
@@ -2650,7 +2656,7 @@ function generateSubtleSecondary(hex, opts) {
   scale.ctaHoverDark = st(10, "dark", scale.ctaDark, 1);
   scale.ctaPressedDark = st(11, "dark", scale.ctaDark, 2);
   const onEnforce = opts?.contrastProfile !== "apca";
-  const onFloor = opts?.contrastProfile === "apca" ? void 0 : 4.5;
+  const onFloor = 4.5;
   scale.onFillTextIsWhite = onTextIsWhite(apcaY(scale.cta.r, scale.cta.g, scale.cta.b), scale.cta.L, scale.cta.C, scale.cta.H, onEnforce, onFloor);
   scale.onFillTextIsWhiteDark = onTextIsWhite(apcaY(scale.ctaDark.r, scale.ctaDark.g, scale.ctaDark.b), scale.ctaDark.L, scale.ctaDark.C, scale.ctaDark.H, onEnforce, onFloor);
   return scale;
@@ -2695,7 +2701,7 @@ var COLOR_WORD = {
   [FAMILY.info]: " (blue)"
 };
 var PAPER = { req: "backgrounds, inverted text", theming: (f) => TINT[f], collides: true };
-var WASH = { req: "subtle interaction states, decorative borders, illos, signal hierarchy", theming: (f) => TINT[f], collides: true };
+var WASH = { req: "subtle interactive states, decorative borders, illos, signal hierarchy", theming: (f) => TINT[f], collides: true };
 var solved = (f) => `${TINT[f]}; re-solved to clear its floor`;
 var OVERLAY = {
   req: "translucent backgrounds that hold their reading on any paper",
@@ -2713,12 +2719,15 @@ var SCALE = {
   "wash-89": WASH,
   "wash-85": WASH,
   "wash-80": WASH,
+  // ("icons" KEPT through the 2026-08-28 on-flood strip (owner): an "icon" query
+  // landing on the mark rows is worth its ic-ON-s noise — the one surviving body carrier)
   "mark-74": { req: "focus rings, icons, large text", contrast: AA_LARGE, theming: solved, collides: true },
   "lead-53": { req: "regular text, inverted backgrounds", contrast: AA_BODY, theming: solved, collides: true },
   "ink-42": { req: "regular text, inverted backgrounds", contrast: AA_BODY, theming: solved, collides: true },
   // ("high-emphasis" reworded 2026-08-12: the surface planes took low/high as label
-  // words, and a body carrying either floods that token's picker search — the C50 law)
-  "ink-30": { req: "strong-emphasis text, inverted backgrounds", contrast: AAA_BODY, theming: solved, collides: true },
+  // words, and a body carrying either floods that token's picker search — the C50 law;
+  // "strong-emphasis" reworded 2026-08-28: str-ON-g fed the "on" flood)
+  "ink-30": { req: "heavy-emphasis text, inverted backgrounds", contrast: AAA_BODY, theming: solved, collides: true },
   // the stamp family (cta words → solid 2026-08-18, solid → stamp 2026-08-27). "CTA" stays in
   // these bodies on purpose: it stopped being a token label, so it floods nothing,
   // and a designer's "cta" query still lands on these rows.
@@ -2729,17 +2738,17 @@ var SCALE = {
   // ("fill" reworded out 2026-08-18: fill became a label word and is foreign here)
   "stamp/on": { req: "text over the CTA color", contrast: `${AA_BODY} over its CTA`, theming: (f) => `whichever pole passes; quiet CTAs take the soft pole${COLOR_WORD[f]}` }
 };
-var ABS = { req: "max contrast on CTAs, aliased global endpoints" };
-var OFFSET = { req: "min APCA visibility", theming: "offsets buttons in themes whose CTAs sit close to the page" };
+var ABS = { req: "extreme poles for CTAs, aliased global endpoints" };
+var OFFSET = { req: "min APCA visibility", theming: "offsets CTAs in themes where they sit close to the page" };
 var SHADOW = { req: "drop shadows" };
 var PLANE = (req) => ({ req, theming: "aliased to the gray ramp" });
 var LINK = (state, contrast) => ({
   req: "links" + state,
   contrast,
-  theming: "rides the theme\u2019s text action; custom seed re-solves; overridable per theme"
+  theming: "rides the theme\u2019s link color; custom seed re-solves; overridable per theme"
 });
 var LINK_INVERSE = (state, contrast) => ({
-  req: "links on inverted backgrounds" + state,
+  req: "links over inverted backgrounds" + state,
   contrast,
   theming: "same seed as the link, re-solved for inverted backgrounds; overridable per theme"
 });
@@ -2750,19 +2759,23 @@ var SYSTEM = {
   // the anchor is engine-resolved and rides the neutral in BOTH plugins now —
   // NEUTRAL_ONLY above. Old files' static rows orphan unwritten.)
   "system/abs-primary": { req: "identity seed reference", theming: "the theme\u2019s own input, as given" },
-  "system/abs-alt": { req: "identity seed reference", theming: "the theme\u2019s companion input, as given" },
+  // ("companion" reworded 2026-08-28: compani-ON fed the "on" flood)
+  "system/abs-alt": { req: "identity seed reference", theming: "the theme\u2019s paired input, as given" },
   "system/alpha/transparent": { req: "aliased off-states" },
   // ("dimming" reworded 2026-08-18: the surface planes took dim as a label word)
   "system/alpha/abs-black-060": { req: "veils the page behind modals" },
-  // ("fills" reworded 2026-08-18: fill became a label word and is foreign here)
-  "system/alpha/ink": { req: "soft on-color for quiet CTAs" },
+  // ("fills" reworded 2026-08-18: fill became a label word and is foreign here;
+  // "on-color" reworded 2026-08-28: the bare on fed the "on" flood)
+  "system/alpha/ink": { req: "soft text pole for quiet CTAs" },
   "system/alpha/006": OFFSET,
   "system/alpha/008": OFFSET,
   "system/alpha/016": OFFSET,
   "system/alpha/shadow-04": SHADOW,
   "system/alpha/shadow-08": SHADOW,
   "system/alpha/shadow-12": SHADOW,
-  "system/surface/dim": PLANE("recessed elevation plane"),
+  // ("elevation" dropped 2026-08-28: elevati-ON fed the "on" flood; the sibling
+  // planes never carried the word)
+  "system/surface/dim": PLANE("recessed plane"),
   "system/surface/low": PLANE("resting page plane"),
   "system/surface/mid": PLANE("raised plane \u2014 cards, menus"),
   // ("overlays" reworded 2026-08-13: paper-overlay took the word as a label — the C50 law)
@@ -3627,7 +3640,7 @@ function brandCss(slug, displayName, r, secondary, noteSuffix = "", neutralLevel
   };
   const softOnCta = (mode) => {
     if (!secondary || secondaryStyle === "outline") return [];
-    if (secondaryStyle !== "default" && !softOnCtaPasses(secondary, mode)) return [];
+    if (!softOnCtaPasses(secondary, mode)) return [];
     const white = mode === "light" ? secondary.onFillTextIsWhite : secondary.onFillTextIsWhiteDark;
     return [`  --${CSS_SECONDARY}-stamp-on: rgba(${white ? "255, 255, 255" : "0, 0, 0"}, ${SOFT_ON_CTA_ALPHA[mode]});`];
   };
@@ -3820,7 +3833,7 @@ function themeToFigma(r, input) {
       });
     };
     softOnCta(neutralGroup, mode === "light" ? nScale.onFillTextIsWhite : nScale.onFillTextIsWhiteDark);
-    if (input.secondary && input.secondaryStyle !== "outline" && (input.secondaryStyle === "default" || softOnCtaPasses(input.secondary, mode)))
+    if (input.secondary && input.secondaryStyle !== "outline" && softOnCtaPasses(input.secondary, mode))
       softOnCta(secondaryGroup, mode === "light" ? secondaryOnFillLight : secondaryOnFillDark);
     const brandGroup = rampGroup(scale[mode], mode === "light" ? scale.onFillTextIsWhite : scale.onFillTextIsWhiteDark, brandExtra(scale, mode, CSS_FAMILY.brandPrimary));
     const esc = input.ctaEscape ? escapeCtaFamily(nScale, mode, input.contrastProfile) : null;

package/dist-lib/index.mjs

@@ -20,9 +20,11 @@ function stateStepL(restL, _mode, k) {
   return k * STATE_HOVER_K;
 }
 var OVERRIDE_LIGHT_BELOW = ARCHETYPES.find((a) => a.name === "rich").min;
+var OVERRIDE_DARK_ABOVE = ARCHETYPES.find((a) => a.name === "light").min;
 function stateFillL(restL, mode, k) {
   const natural = mode === "dark" ? 1 : -1;
-  const preferred = mode === "light" && restL < OVERRIDE_LIGHT_BELOW ? -natural : natural;
+  const overridden = mode === "light" ? restL < OVERRIDE_LIGHT_BELOW : restL > OVERRIDE_DARK_ABOVE;
+  const preferred = overridden ? -natural : natural;
   const fits = (d) => {
     const p = restL + d * stateStepL(restL, mode, 2);
     return p >= STATE_L_MIN && p <= STATE_L_MAX;
@@ -2549,7 +2551,7 @@ function generateNeutralScale(brandH, level = "default", contrastProfile) {
   scale.ctaHoverDark = nState(10, "dark", scale.ctaDark, 1);
   scale.ctaPressedDark = nState(11, "dark", scale.ctaDark, 2);
   const onEnforce = contrastProfile !== "apca";
-  const onFloor = contrastProfile === "apca" ? void 0 : 4.5;
+  const onFloor = 4.5;
   scale.onFillTextIsWhite = onTextIsWhite(apcaY(scale.cta.r, scale.cta.g, scale.cta.b), scale.cta.L, scale.cta.C, scale.cta.H, onEnforce, onFloor);
   scale.onFillTextIsWhiteDark = onTextIsWhite(apcaY(scale.ctaDark.r, scale.ctaDark.g, scale.ctaDark.b), scale.ctaDark.L, scale.ctaDark.C, scale.ctaDark.H, onEnforce, onFloor);
   return scale;
@@ -2580,7 +2582,7 @@ function generateSubtleSecondary(hex, opts) {
   scale.ctaHoverDark = st(10, "dark", scale.ctaDark, 1);
   scale.ctaPressedDark = st(11, "dark", scale.ctaDark, 2);
   const onEnforce = opts?.contrastProfile !== "apca";
-  const onFloor = opts?.contrastProfile === "apca" ? void 0 : 4.5;
+  const onFloor = 4.5;
   scale.onFillTextIsWhite = onTextIsWhite(apcaY(scale.cta.r, scale.cta.g, scale.cta.b), scale.cta.L, scale.cta.C, scale.cta.H, onEnforce, onFloor);
   scale.onFillTextIsWhiteDark = onTextIsWhite(apcaY(scale.ctaDark.r, scale.ctaDark.g, scale.ctaDark.b), scale.ctaDark.L, scale.ctaDark.C, scale.ctaDark.H, onEnforce, onFloor);
   return scale;
@@ -2625,7 +2627,7 @@ var COLOR_WORD = {
   [FAMILY.info]: " (blue)"
 };
 var PAPER = { req: "backgrounds, inverted text", theming: (f) => TINT[f], collides: true };
-var WASH = { req: "subtle interaction states, decorative borders, illos, signal hierarchy", theming: (f) => TINT[f], collides: true };
+var WASH = { req: "subtle interactive states, decorative borders, illos, signal hierarchy", theming: (f) => TINT[f], collides: true };
 var solved = (f) => `${TINT[f]}; re-solved to clear its floor`;
 var OVERLAY = {
   req: "translucent backgrounds that hold their reading on any paper",
@@ -2643,12 +2645,15 @@ var SCALE = {
   "wash-89": WASH,
   "wash-85": WASH,
   "wash-80": WASH,
+  // ("icons" KEPT through the 2026-08-28 on-flood strip (owner): an "icon" query
+  // landing on the mark rows is worth its ic-ON-s noise — the one surviving body carrier)
   "mark-74": { req: "focus rings, icons, large text", contrast: AA_LARGE, theming: solved, collides: true },
   "lead-53": { req: "regular text, inverted backgrounds", contrast: AA_BODY, theming: solved, collides: true },
   "ink-42": { req: "regular text, inverted backgrounds", contrast: AA_BODY, theming: solved, collides: true },
   // ("high-emphasis" reworded 2026-08-12: the surface planes took low/high as label
-  // words, and a body carrying either floods that token's picker search — the C50 law)
-  "ink-30": { req: "strong-emphasis text, inverted backgrounds", contrast: AAA_BODY, theming: solved, collides: true },
+  // words, and a body carrying either floods that token's picker search — the C50 law;
+  // "strong-emphasis" reworded 2026-08-28: str-ON-g fed the "on" flood)
+  "ink-30": { req: "heavy-emphasis text, inverted backgrounds", contrast: AAA_BODY, theming: solved, collides: true },
   // the stamp family (cta words → solid 2026-08-18, solid → stamp 2026-08-27). "CTA" stays in
   // these bodies on purpose: it stopped being a token label, so it floods nothing,
   // and a designer's "cta" query still lands on these rows.
@@ -2659,17 +2664,17 @@ var SCALE = {
   // ("fill" reworded out 2026-08-18: fill became a label word and is foreign here)
   "stamp/on": { req: "text over the CTA color", contrast: `${AA_BODY} over its CTA`, theming: (f) => `whichever pole passes; quiet CTAs take the soft pole${COLOR_WORD[f]}` }
 };
-var ABS = { req: "max contrast on CTAs, aliased global endpoints" };
-var OFFSET = { req: "min APCA visibility", theming: "offsets buttons in themes whose CTAs sit close to the page" };
+var ABS = { req: "extreme poles for CTAs, aliased global endpoints" };
+var OFFSET = { req: "min APCA visibility", theming: "offsets CTAs in themes where they sit close to the page" };
 var SHADOW = { req: "drop shadows" };
 var PLANE = (req) => ({ req, theming: "aliased to the gray ramp" });
 var LINK = (state, contrast) => ({
   req: "links" + state,
   contrast,
-  theming: "rides the theme\u2019s text action; custom seed re-solves; overridable per theme"
+  theming: "rides the theme\u2019s link color; custom seed re-solves; overridable per theme"
 });
 var LINK_INVERSE = (state, contrast) => ({
-  req: "links on inverted backgrounds" + state,
+  req: "links over inverted backgrounds" + state,
   contrast,
   theming: "same seed as the link, re-solved for inverted backgrounds; overridable per theme"
 });
@@ -2680,19 +2685,23 @@ var SYSTEM = {
   // the anchor is engine-resolved and rides the neutral in BOTH plugins now —
   // NEUTRAL_ONLY above. Old files' static rows orphan unwritten.)
   "system/abs-primary": { req: "identity seed reference", theming: "the theme\u2019s own input, as given" },
-  "system/abs-alt": { req: "identity seed reference", theming: "the theme\u2019s companion input, as given" },
+  // ("companion" reworded 2026-08-28: compani-ON fed the "on" flood)
+  "system/abs-alt": { req: "identity seed reference", theming: "the theme\u2019s paired input, as given" },
   "system/alpha/transparent": { req: "aliased off-states" },
   // ("dimming" reworded 2026-08-18: the surface planes took dim as a label word)
   "system/alpha/abs-black-060": { req: "veils the page behind modals" },
-  // ("fills" reworded 2026-08-18: fill became a label word and is foreign here)
-  "system/alpha/ink": { req: "soft on-color for quiet CTAs" },
+  // ("fills" reworded 2026-08-18: fill became a label word and is foreign here;
+  // "on-color" reworded 2026-08-28: the bare on fed the "on" flood)
+  "system/alpha/ink": { req: "soft text pole for quiet CTAs" },
   "system/alpha/006": OFFSET,
   "system/alpha/008": OFFSET,
   "system/alpha/016": OFFSET,
   "system/alpha/shadow-04": SHADOW,
   "system/alpha/shadow-08": SHADOW,
   "system/alpha/shadow-12": SHADOW,
-  "system/surface/dim": PLANE("recessed elevation plane"),
+  // ("elevation" dropped 2026-08-28: elevati-ON fed the "on" flood; the sibling
+  // planes never carried the word)
+  "system/surface/dim": PLANE("recessed plane"),
   "system/surface/low": PLANE("resting page plane"),
   "system/surface/mid": PLANE("raised plane \u2014 cards, menus"),
   // ("overlays" reworded 2026-08-13: paper-overlay took the word as a label — the C50 law)
@@ -3557,7 +3566,7 @@ function brandCss(slug, displayName, r, secondary, noteSuffix = "", neutralLevel
   };
   const softOnCta = (mode) => {
     if (!secondary || secondaryStyle === "outline") return [];
-    if (secondaryStyle !== "default" && !softOnCtaPasses(secondary, mode)) return [];
+    if (!softOnCtaPasses(secondary, mode)) return [];
     const white = mode === "light" ? secondary.onFillTextIsWhite : secondary.onFillTextIsWhiteDark;
     return [`  --${CSS_SECONDARY}-stamp-on: rgba(${white ? "255, 255, 255" : "0, 0, 0"}, ${SOFT_ON_CTA_ALPHA[mode]});`];
   };
@@ -3750,7 +3759,7 @@ function themeToFigma(r, input) {
       });
     };
     softOnCta(neutralGroup, mode === "light" ? nScale.onFillTextIsWhite : nScale.onFillTextIsWhiteDark);
-    if (input.secondary && input.secondaryStyle !== "outline" && (input.secondaryStyle === "default" || softOnCtaPasses(input.secondary, mode)))
+    if (input.secondary && input.secondaryStyle !== "outline" && softOnCtaPasses(input.secondary, mode))
       softOnCta(secondaryGroup, mode === "light" ? secondaryOnFillLight : secondaryOnFillDark);
     const brandGroup = rampGroup(scale[mode], mode === "light" ? scale.onFillTextIsWhite : scale.onFillTextIsWhiteDark, brandExtra(scale, mode, CSS_FAMILY.brandPrimary));
     const esc = input.ctaEscape ? escapeCtaFamily(nScale, mode, input.contrastProfile) : null;
@@ -3853,6 +3862,7 @@ function resolveDtcgRamp(group) {
   return resolveRamp(seedHex, mode, { stops, roles, ons });
 }
 export {
+  CSS_FAMILY,
   DEFAULT_LINK_HEX,
   EXT_KEY,
   INK_0,
@@ -3879,11 +3889,14 @@ export {
   checkCollision,
   checkHueCollision,
   classifyArchetype,
+  ctaBorderRung,
+  ctaNeedsBorder,
   emitDtcgRamp,
   generateNeutralScale,
   generateScale,
   generateSubtleSecondary,
   neutralCss,
+  pageStopFor,
   parseToken,
   resolveBrand,
   resolveDtcgRamp,

package/dist-lib/types/index.d.ts

@@ -1,6 +1,7 @@
 export { generateScale, generateNeutralScale, generateSubtleSecondary, type GeneratedScale, type ColorStop, type GenerateOptions, type NeutralLevel, type ContrastProfile, } from './engine/colorEngine';
 export { resolveBrand, resolveTheme, resolveLinkTrio, resolveLinkInverseTrio, DEFAULT_LINK_HEX, SIGNAL_SCALES, signalScalesFor, SECONDARY_DISTINCT_DELTA_E, SUBTLE_TINT_MULT, SUBTLE_PASTEL_K, OUTLINE_HOVER_ALPHA, type ResolvedBrand, type ResolvedTheme, type ResolvedSecondary, type SecondaryLevel, type SecondaryStyle, type SignalOverride, } from './engine/resolve';
-export { brandCss, neutralCss, signalsCss, stopsToVars, toHex, stopHex, OFFSET_ALPHAS } from './engine/cssRender';
+export { brandCss, neutralCss, signalsCss, stopsToVars, toHex, stopHex, OFFSET_ALPHAS, ctaNeedsBorder, ctaBorderRung, pageStopFor, } from './engine/cssRender';
+export { CSS_FAMILY } from './engine/tokenDescriptions';
 export { themeToFigma, type FigmaGroup, type FigmaColorToken, type ThemeInput, } from './engine/figmaRender';
 export { emitDtcgRamp, resolveDtcgRamp, parseToken, EXT_KEY, RESOLVER_ID, type DtcgRampGroup, type DtcgRequirementToken, type DtcgSeedToken, type DtcgColorValue, } from './engine/requirements/dtcg';
 export { MODE_SPECS, type ModeSpec } from './engine/requirements/spec';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "okchroma",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "license": "MIT",
   "description": "Color token engine: one brand hex in, a full WCAG-enforced light+dark token system out (CSS variables, DTCG JSON, Figma variables)",
   "repository": {
@@ -18,7 +18,8 @@
     }
   },
   "files": [
-    "dist-lib"
+    "dist-lib",
+    "tokens"
   ],
   "sideEffects": false,
   "scripts": {

package/tokens/semantic.css

@@ -0,0 +1,204 @@
+/*
+  Semantic token layer — maps role names to primitive tokens.
+  This file never changes per brand. Only the primitives (--brand-*, --neutral-*) change.
+*/
+
+/* ─── Global surface / fg / border ─────────────────────────────────────────── */
+
+[data-brand] {
+  /* Elevation planes sunken → low → base → high (owner spec 2026-07-24 Figma
+     elevation study; renamed 2026-08-12 — base is the raised plane components sit
+     on, the page behind it is low, the two extremes are edge cases): both themes
+     use the SAME four stops, in reversed order — elevation always moves toward
+     paper-100's side of the ramp. Light descends the ramp as elevation rises
+     (sunken paper-95 → high paper-100 white); dark ascends it (sunken paper-100
+     black → high paper-95). paper-100 flips white→black with the mode, so it is
+     always the extreme pole: the high in light, the sunken in dark. The stops
+     themselves have never moved through any of the renames. */
+  --surface-dim:        var(--neutral-paper-95);
+  --surface-low:         var(--neutral-paper-97);
+  --surface-mid:       var(--neutral-paper-99);
+  --surface-high:        var(--paper-100, #ffffff);
+
+  --fg-default:           var(--neutral-ink-30);
+  --fg-subtle:            var(--neutral-lead-53);
+  /* --fg-link moved to the SYSTEM LINK trio below (owner 2026-07-16: one link per
+     theme, riding --link — no longer the brand's raw ink pair) */
+
+  /* --border-default IS THE ACCESSIBILITY BORDER (owner 2026-07-29): a border that has
+     to be there — inputs and other controls — so it rides mark-74, the stop that
+     carries the WCAG 1.4.11 3:1 non-text require (highlight-8 pre-Stage-B). It sat on
+     --neutral-highlight-9 until that stop was deleted; mark-74 is where the
+     requirement actually lives, and it is the one stop this round does not move.
+     Decorative borders are --border-subtle (wash-89) and the per-family
+     --*-border-default (wash-85). */
+  --border-default:       var(--neutral-mark-74);
+  --border-subtle:        var(--neutral-wash-89);
+
+  /* Shadow transparencies (owner 2026-07-27) — pure black, mirrors the plugin's
+     system/alpha/shadow-04|08|12 rows 1:1. Dark is heavier by necessity: near
+     black a light-mode alpha vanishes, so the dark values carry the same roles
+     at 32/48/64%. Elevation recipes (--elev-*) compose these, so dark shadows
+     fall out of the token swap with nothing bespoke per style. */
+  --shadow-04: rgba(0, 0, 0, 0.04);
+  --shadow-08: rgba(0, 0, 0, 0.08);
+  --shadow-12: rgba(0, 0, 0, 0.12);
+}
+
+[data-brand][data-theme="dark"] {
+  /* Dark runs the same four stops upward: sunken paper-100 (black) → low paper-99 →
+     base paper-97 → high paper-95 — the one-level highest background (C27: every
+     family's paper-95 shares one photometric level, so chips sit flush on the high
+     plane by construction; a generated candidate for it was tried and retired,
+     owner 2026-07-28). Low needs its own override here because the shared block's
+     low is paper-97 (the light value); the stops themselves did not move. */
+  --surface-dim:        var(--paper-100, #000000);
+  --surface-low:         var(--neutral-paper-99);
+  --surface-mid:       var(--neutral-paper-97);
+  --surface-high:        var(--neutral-paper-95);
+
+  --shadow-04: rgba(0, 0, 0, 0.32);
+  --shadow-08: rgba(0, 0, 0, 0.48);
+  --shadow-12: rgba(0, 0, 0, 0.64);
+}
+
+/* ─── role.brand ────────────────────────────────────────────────────────────── */
+
+[data-brand] {
+  --brand-fg:                    var(--brand-ink-30);
+  --brand-fg-hover:              var(--brand-lead-53);
+  --brand-fg-alt:                var(--brand-lead-53);
+  --brand-fg-alt-hover:          var(--brand-ink-30);
+  --brand-fg-on-emphasis:        var(--brand-stamp-on);
+
+  --brand-bg-faint:              var(--brand-paper-97);
+  --brand-bg-subtle:             var(--brand-wash-89);
+  --brand-bg-subtle-hover:       var(--brand-wash-85);
+  --brand-bg-emphasis:           var(--brand-stamp-fill);
+  --brand-bg-emphasis-hover:     var(--brand-stamp-fill-hover);
+  --brand-bg-emphasis-pressed:   var(--brand-stamp-fill-pressed);
+
+  --brand-border-subtle:         var(--brand-wash-92);
+  --brand-border-subtle-hover:   var(--brand-wash-89);
+  --brand-border-default:            var(--brand-wash-85);
+  --brand-border-default-hover:      var(--brand-mark-74);
+  --brand-border-emphasis:       var(--brand-stamp-fill);
+  --brand-border-emphasis-hover: var(--brand-stamp-fill-hover);
+
+  /* the SYSTEM LINK (one trio per theme — aliases the primary's ink stops unless a custom
+     link color de-conflicts it; --link/-hover/-pressed are emitted per brand) */
+  --fg-link:         var(--link);
+  --fg-link-hover:   var(--link-hover);
+  --fg-link-pressed: var(--link-pressed);
+
+  /* the INVERSE link trio (owner round 2026-08-19): the same link seed re-solved for
+     text on inverted surfaces (an ink-30 fill); always its own emitted values —
+     no stop is anchored against that ground, so there is no alias posture */
+  --fg-link-inverse:         var(--link-inverse);
+  --fg-link-inverse-hover:   var(--link-inverse-hover);
+  --fg-link-inverse-pressed: var(--link-inverse-pressed);
+}
+
+/* ─── role.secondary (the brand's secondary ramp; mirrors brand when none) ──── */
+
+[data-brand] {
+  --brand-alt-fg:                    var(--brand-alt-ink-30);
+  --brand-alt-fg-hover:              var(--brand-alt-lead-53);
+  --brand-alt-fg-alt:                var(--brand-alt-lead-53);
+  --brand-alt-fg-alt-hover:          var(--brand-alt-ink-30);
+  --brand-alt-fg-on-emphasis:        var(--brand-alt-stamp-on);
+
+  --brand-alt-bg-faint:              var(--brand-alt-paper-97);
+  --brand-alt-bg-subtle:             var(--brand-alt-wash-89);
+  --brand-alt-bg-subtle-hover:       var(--brand-alt-wash-85);
+  --brand-alt-bg-emphasis:           var(--brand-alt-stamp-fill);
+  --brand-alt-bg-emphasis-hover:     var(--brand-alt-stamp-fill-hover);
+  --brand-alt-bg-emphasis-pressed:   var(--brand-alt-stamp-fill-pressed);
+
+  --brand-alt-border-subtle:         var(--brand-alt-wash-92);
+  --brand-alt-border-subtle-hover:   var(--brand-alt-wash-89);
+  --brand-alt-border-default:           var(--brand-alt-wash-85);
+  --brand-alt-border-default-hover:     var(--brand-alt-mark-74);
+  --brand-alt-border-emphasis:       var(--brand-alt-stamp-fill);
+  --brand-alt-border-emphasis-hover: var(--brand-alt-stamp-fill-hover);
+}
+
+/* ─── Signal roles ──────────────────────────────────────────────────────────
+   Aliases onto engine-generated signal primitives (dist/signals.css).
+   Mode switching happens at the primitive layer, so one block covers both.
+   Signal families emit by ROLE (owner 2026-07-27: critical/warning/positive/
+   info — the re-pointable in-between tier; identity stays engine-internal),
+   so the role tokens and the family ramp share a prefix: --critical-fg rides
+   --critical-ink-30. The old alert-high/alert-med role prefixes collapsed
+   into critical/warning in the same round.
+
+   -fg-on-emphasis rides --paper-100, NOT a solved on-color: the engine's on-highlight
+   token was deleted with the highlight band (owner 2026-07-29). paper-100 is the
+   mode-flipping paper extreme — white in light, the tinted deep ground in dark — and
+   it clears 4.5 against lead-53 everywhere (agnostic 360-seed sweep, worst 4.96
+   light / 8.04 dark). -bg-emphasis / -border-emphasis moved from highlight-9 to
+   lead-53 (ink-9 pre-Stage-B) with it; in dark that reads lighter (contrast vs
+   paper-95, median 6.01 → 7.72). Stage B (owner 2026-08-07, names only) relabeled
+   every leaf in the block below; the stops themselves did not move. */
+
+[data-brand] {
+  --critical-fg:                    var(--critical-ink-30);
+  --critical-fg-hover:              var(--critical-lead-53);
+  --critical-fg-alt:                var(--critical-lead-53);
+  --critical-fg-alt-hover:          var(--critical-ink-30);
+  --critical-fg-on-emphasis:        var(--paper-100);
+  --critical-bg-faint:              var(--critical-paper-97);
+  --critical-bg-subtle:             var(--critical-wash-89);
+  --critical-bg-subtle-hover:       var(--critical-wash-85);
+  --critical-bg-emphasis:           var(--critical-lead-53);
+  --critical-border-subtle:         var(--critical-wash-92);
+  --critical-border-subtle-hover:   var(--critical-wash-89);
+  --critical-border-default:       var(--critical-wash-85);
+  --critical-border-default-hover: var(--critical-mark-74);
+  --critical-border-emphasis:       var(--critical-lead-53);
+
+  --warning-fg:                     var(--warning-ink-30);
+  --warning-fg-hover:               var(--warning-lead-53);
+  --warning-fg-alt:                 var(--warning-lead-53);
+  --warning-fg-alt-hover:           var(--warning-ink-30);
+  --warning-fg-on-emphasis:         var(--paper-100);
+  --warning-bg-faint:               var(--warning-paper-97);
+  --warning-bg-subtle:              var(--warning-wash-89);
+  --warning-bg-subtle-hover:        var(--warning-wash-85);
+  --warning-bg-emphasis:            var(--warning-lead-53);
+  --warning-border-subtle:          var(--warning-wash-92);
+  --warning-border-subtle-hover:    var(--warning-wash-89);
+  --warning-border-default:        var(--warning-wash-85);
+  --warning-border-default-hover:  var(--warning-mark-74);
+  --warning-border-emphasis:        var(--warning-lead-53);
+
+  --positive-fg:                      var(--positive-ink-30);
+  --positive-fg-hover:                var(--positive-lead-53);
+  --positive-fg-alt:                  var(--positive-lead-53);
+  --positive-fg-alt-hover:            var(--positive-ink-30);
+  --positive-fg-on-emphasis:          var(--paper-100);
+  --positive-bg-faint:                var(--positive-paper-97);
+  --positive-bg-subtle:               var(--positive-wash-89);
+  --positive-bg-subtle-hover:         var(--positive-wash-85);
+  --positive-bg-emphasis:             var(--positive-lead-53);
+  --positive-border-subtle:           var(--positive-wash-92);
+  --positive-border-subtle-hover:     var(--positive-wash-89);
+  --positive-border-default:         var(--positive-wash-85);
+  --positive-border-default-hover:   var(--positive-mark-74);
+  --positive-border-emphasis:         var(--positive-lead-53);
+
+  --info-fg:                          var(--info-ink-30);
+  --info-fg-hover:                    var(--info-lead-53);
+  --info-fg-alt:                      var(--info-lead-53);
+  --info-fg-alt-hover:                var(--info-ink-30);
+  --info-fg-on-emphasis:              var(--paper-100);
+  --info-bg-faint:                    var(--info-paper-97);
+  --info-bg-subtle:                   var(--info-wash-89);
+  --info-bg-subtle-hover:             var(--info-wash-85);
+  --info-bg-emphasis:                 var(--info-lead-53);
+  --info-border-subtle:               var(--info-wash-92);
+  --info-border-subtle-hover:         var(--info-wash-89);
+  --info-border-default:             var(--info-wash-85);
+  --info-border-default-hover:       var(--info-mark-74);
+  --info-border-emphasis:             var(--info-lead-53);
+}