okchroma 0.3.1 → 0.4.0

package/dist-lib/index.cjs

@@ -32,6 +32,7 @@ __export(index_exports, {
   RESOLVER_ID: () => RESOLVER_ID,
   SCALE_STOP_COUNT: () => SCALE_STOP_COUNT,
   SCRIM_ALPHA: () => SCRIM_ALPHA,
+  SCRIM_VAR: () => SCRIM_VAR,
   SECONDARY_DISTINCT_DELTA_E: () => SECONDARY_DISTINCT_DELTA_E,
   SHADOW_ALPHAS: () => SHADOW_ALPHAS,
   SIGNALS: () => SIGNALS2,
@@ -59,6 +60,7 @@ __export(index_exports, {
   generateScale: () => generateScale,
   generateSubtleSecondary: () => generateSubtleSecondary,
   neutralCss: () => neutralCss,
+  neutralTintHue: () => neutralTintHue,
   pageStopFor: () => pageStopFor,
   parseToken: () => parseToken,
   resolveBrand: () => resolveBrand,
@@ -2717,6 +2719,12 @@ function generateScale(hex, scaleName, forcedArchetype, opts) {
     pen100Dark: penPole(dark, 1)
   };
 }
+function neutralTintHue(primaryH, source, secondaryH, customHex) {
+  if (source === "secondary" && secondaryH !== void 0) return secondaryH;
+  if (source === "custom" && customHex && /^#?[0-9a-fA-F]{6}$/.test(customHex))
+    return hexToOklch(customHex.startsWith("#") ? customHex : `#${customHex}`).H;
+  return primaryH;
+}
 function generateNeutralScale(brandH, level = "default", contrastProfile) {
   const h = (brandH % 360 + 360) % 360;
   const { r, g: g2, b } = oklchToSrgbUnclamped(0.5, 6e-3, h);
@@ -3522,9 +3530,12 @@ var SHADOW_ALPHAS = {
 var SCRIM_ALPHA = 0.6;
 var DISABLED_OPACITY = 0.38;
 var TRANSPARENT_VAR = "--alpha-transparent";
+var SCRIM_VAR = "--abs-black-060";
 var offsetRgba = (rung, mode) => mode === "light" ? `rgba(0, 0, 0, ${OFFSET_ALPHAS[rung]})` : `rgba(255, 255, 255, ${OFFSET_ALPHAS[rung]})`;
 var alphaRootVars = (mode) => [
   `  ${TRANSPARENT_VAR}: transparent;`,
+  // mode-invariant like transparent; repeated in the dark block to keep the set together
+  `  ${SCRIM_VAR}: rgba(0, 0, 0, ${SCRIM_ALPHA});`,
   ...Object.keys(OFFSET_ALPHAS).map(Number).sort((a, b) => a - b).map((r) => `  ${offsetVarName(r)}: ${offsetRgba(r, mode)};`),
   // the toward-bg ladder (the 2026-08-29 inverse ladder, renamed 2026-08-31): the
   // same rungs, pole flipped per mode — state layers for INVERTED grounds (never
@@ -3540,7 +3551,7 @@ function ctaNeedsBorder(s, mode, page) {
   if (!page) return false;
   return ctaPageLc(s, mode, page) < CTA_BORDER_LC_FLOOR;
 }
-function brandKindBody(prefix, s, mode, page) {
+function brandKindBody(prefix, s, mode, page, on = prefix === CSS_NEUTRAL ? "soft" : "solid") {
   const stops = mode === "light" ? s.light : s.dark;
   const f = ctaFamilyOf(s, mode);
   const onCta = mode === "light" ? s.onFillTextIsWhite : s.onFillTextIsWhiteDark;
@@ -3559,10 +3570,10 @@ function brandKindBody(prefix, s, mode, page) {
     // button text takes the pole AT ALPHA like the default-model secondary's — composited
     // over whatever state the fill is in, so hover/pressed carry their own legibility. Same
     // register both families (SOFT_ON_CTA_ALPHA), so both alias the ONE system/alpha/ink
-    // primitive. Emitted HERE rather than as a post-body override because the neutral's is
-    // unconditional — the secondary's rides the cascade only because it gates on the style
-    // chip. Loud fills (brand, signals, the cta escape) keep the solid pole.
-    prefix === CSS_NEUTRAL ? `  --${CSS_NEUTRAL}-stamp-on: rgba(${onCta ? "255, 255, 255" : "0, 0, 0"}, ${SOFT_ON_CTA_ALPHA[mode]});` : `  --${prefix}-stamp-on: ${onColor(onCta)};`
+    // primitive. The neutral's is unconditional (the parameter default); the secondary's is
+    // the caller's per-mode verdict. Loud fills (brand, signals, the cta escape) keep the
+    // solid pole.
+    on === "soft" ? `  --${prefix}-stamp-on: rgba(${onCta ? "255, 255, 255" : "0, 0, 0"}, ${SOFT_ON_CTA_ALPHA[mode]});` : `  --${prefix}-stamp-on: ${onColor(onCta)};`
   ];
 }
 function ctaFamilyOf(s, mode) {
@@ -3629,7 +3640,8 @@ function signalsCss(contrastProfile) {
     // the system alpha variables every family's cta-border aliases (owner 2026-07-29) — this is
     // the engine's one global :root, the CSS counterpart of the Figma side's system/alpha/* rows.
     // Emitted in BOTH blocks because the offset rungs are scheme-DIVERGENT (black in light,
-    // white in dark); --alpha-transparent repeats harmlessly and keeps the set together.
+    // white in dark); --alpha-transparent and the scrim (both mode-invariant) repeat
+    // harmlessly and keep the set together.
     ...alphaRootVars("light"),
     ...lightBlocks,
     `}`,
@@ -3678,8 +3690,9 @@ function brandCss(slug, displayName, r, secondary, noteSuffix = "", neutralLevel
       alias("stamp-on")
     ];
   };
-  const secondaryLight = secondary ? brandKindBody(CSS_SECONDARY, secondary, "light", page.light) : mirrorBody(CSS_SECONDARY, "light");
-  const secondaryDark = secondary ? brandKindBody(CSS_SECONDARY, secondary, "dark", page.dark) : mirrorBody(CSS_SECONDARY, "dark");
+  const secondaryOn = (mode) => secondary && secondaryStyle !== "outline" && softOnCtaPasses(secondary, mode) ? "soft" : "solid";
+  const secondaryLight = secondary ? brandKindBody(CSS_SECONDARY, secondary, "light", page.light, secondaryOn("light")) : mirrorBody(CSS_SECONDARY, "light");
+  const secondaryDark = secondary ? brandKindBody(CSS_SECONDARY, secondary, "dark", page.dark, secondaryOn("dark")) : mirrorBody(CSS_SECONDARY, "dark");
   const brandIdentity = `  --${CSS_BRAND}-identity: ${scale.identityHex};`;
   const secondaryIdentity = secondary ? `  --${CSS_SECONDARY}-identity: ${secondary.identityHex};` : `  --${CSS_SECONDARY}-identity: var(--${CSS_BRAND}-identity);`;
   const p0hex = (s, fallback) => s ? stopHex(s) : fallback;
@@ -3713,12 +3726,6 @@ function brandCss(slug, displayName, r, secondary, noteSuffix = "", neutralLevel
       `  --${CSS_BRAND}-stamp-on: ${onColor(esc.onFillIsWhite)};`
     ];
   };
-  const softOnCta = (mode) => {
-    if (!secondary || secondaryStyle === "outline") 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]});`];
-  };
   const outline = (mode) => {
     if (secondaryStyle !== "outline" || !secondary) return [];
     const s8 = (mode === "light" ? secondary.light : secondary.dark).find((s) => s.stop === 8);
@@ -3762,7 +3769,6 @@ function brandCss(slug, displayName, r, secondary, noteSuffix = "", neutralLevel
     ...linkInverse("light"),
     brandIdentity,
     ...secondaryLight,
-    ...softOnCta("light"),
     ...outline("light"),
     secondaryIdentity,
     ...brandKindBody(CSS_NEUTRAL, nScale, "light", page.light),
@@ -3775,7 +3781,6 @@ function brandCss(slug, displayName, r, secondary, noteSuffix = "", neutralLevel
     ...link("dark"),
     ...linkInverse("dark"),
     ...secondaryDark,
-    ...softOnCta("dark"),
     ...outline("dark"),
     ...brandKindBody(CSS_NEUTRAL, nScale, "dark", page.dark),
     ...effOverrides.flatMap((o) => brandKindBody(SIGNAL_EMIT_NAME[o.name], o.scale, "dark", page.dark)),

package/dist-lib/index.mjs

@@ -2638,6 +2638,12 @@ function generateScale(hex, scaleName, forcedArchetype, opts) {
     pen100Dark: penPole(dark, 1)
   };
 }
+function neutralTintHue(primaryH, source, secondaryH, customHex) {
+  if (source === "secondary" && secondaryH !== void 0) return secondaryH;
+  if (source === "custom" && customHex && /^#?[0-9a-fA-F]{6}$/.test(customHex))
+    return hexToOklch(customHex.startsWith("#") ? customHex : `#${customHex}`).H;
+  return primaryH;
+}
 function generateNeutralScale(brandH, level = "default", contrastProfile) {
   const h = (brandH % 360 + 360) % 360;
   const { r, g: g2, b } = oklchToSrgbUnclamped(0.5, 6e-3, h);
@@ -3443,9 +3449,12 @@ var SHADOW_ALPHAS = {
 var SCRIM_ALPHA = 0.6;
 var DISABLED_OPACITY = 0.38;
 var TRANSPARENT_VAR = "--alpha-transparent";
+var SCRIM_VAR = "--abs-black-060";
 var offsetRgba = (rung, mode) => mode === "light" ? `rgba(0, 0, 0, ${OFFSET_ALPHAS[rung]})` : `rgba(255, 255, 255, ${OFFSET_ALPHAS[rung]})`;
 var alphaRootVars = (mode) => [
   `  ${TRANSPARENT_VAR}: transparent;`,
+  // mode-invariant like transparent; repeated in the dark block to keep the set together
+  `  ${SCRIM_VAR}: rgba(0, 0, 0, ${SCRIM_ALPHA});`,
   ...Object.keys(OFFSET_ALPHAS).map(Number).sort((a, b) => a - b).map((r) => `  ${offsetVarName(r)}: ${offsetRgba(r, mode)};`),
   // the toward-bg ladder (the 2026-08-29 inverse ladder, renamed 2026-08-31): the
   // same rungs, pole flipped per mode — state layers for INVERTED grounds (never
@@ -3461,7 +3470,7 @@ function ctaNeedsBorder(s, mode, page) {
   if (!page) return false;
   return ctaPageLc(s, mode, page) < CTA_BORDER_LC_FLOOR;
 }
-function brandKindBody(prefix, s, mode, page) {
+function brandKindBody(prefix, s, mode, page, on = prefix === CSS_NEUTRAL ? "soft" : "solid") {
   const stops = mode === "light" ? s.light : s.dark;
   const f = ctaFamilyOf(s, mode);
   const onCta = mode === "light" ? s.onFillTextIsWhite : s.onFillTextIsWhiteDark;
@@ -3480,10 +3489,10 @@ function brandKindBody(prefix, s, mode, page) {
     // button text takes the pole AT ALPHA like the default-model secondary's — composited
     // over whatever state the fill is in, so hover/pressed carry their own legibility. Same
     // register both families (SOFT_ON_CTA_ALPHA), so both alias the ONE system/alpha/ink
-    // primitive. Emitted HERE rather than as a post-body override because the neutral's is
-    // unconditional — the secondary's rides the cascade only because it gates on the style
-    // chip. Loud fills (brand, signals, the cta escape) keep the solid pole.
-    prefix === CSS_NEUTRAL ? `  --${CSS_NEUTRAL}-stamp-on: rgba(${onCta ? "255, 255, 255" : "0, 0, 0"}, ${SOFT_ON_CTA_ALPHA[mode]});` : `  --${prefix}-stamp-on: ${onColor(onCta)};`
+    // primitive. The neutral's is unconditional (the parameter default); the secondary's is
+    // the caller's per-mode verdict. Loud fills (brand, signals, the cta escape) keep the
+    // solid pole.
+    on === "soft" ? `  --${prefix}-stamp-on: rgba(${onCta ? "255, 255, 255" : "0, 0, 0"}, ${SOFT_ON_CTA_ALPHA[mode]});` : `  --${prefix}-stamp-on: ${onColor(onCta)};`
   ];
 }
 function ctaFamilyOf(s, mode) {
@@ -3550,7 +3559,8 @@ function signalsCss(contrastProfile) {
     // the system alpha variables every family's cta-border aliases (owner 2026-07-29) — this is
     // the engine's one global :root, the CSS counterpart of the Figma side's system/alpha/* rows.
     // Emitted in BOTH blocks because the offset rungs are scheme-DIVERGENT (black in light,
-    // white in dark); --alpha-transparent repeats harmlessly and keeps the set together.
+    // white in dark); --alpha-transparent and the scrim (both mode-invariant) repeat
+    // harmlessly and keep the set together.
     ...alphaRootVars("light"),
     ...lightBlocks,
     `}`,
@@ -3599,8 +3609,9 @@ function brandCss(slug, displayName, r, secondary, noteSuffix = "", neutralLevel
       alias("stamp-on")
     ];
   };
-  const secondaryLight = secondary ? brandKindBody(CSS_SECONDARY, secondary, "light", page.light) : mirrorBody(CSS_SECONDARY, "light");
-  const secondaryDark = secondary ? brandKindBody(CSS_SECONDARY, secondary, "dark", page.dark) : mirrorBody(CSS_SECONDARY, "dark");
+  const secondaryOn = (mode) => secondary && secondaryStyle !== "outline" && softOnCtaPasses(secondary, mode) ? "soft" : "solid";
+  const secondaryLight = secondary ? brandKindBody(CSS_SECONDARY, secondary, "light", page.light, secondaryOn("light")) : mirrorBody(CSS_SECONDARY, "light");
+  const secondaryDark = secondary ? brandKindBody(CSS_SECONDARY, secondary, "dark", page.dark, secondaryOn("dark")) : mirrorBody(CSS_SECONDARY, "dark");
   const brandIdentity = `  --${CSS_BRAND}-identity: ${scale.identityHex};`;
   const secondaryIdentity = secondary ? `  --${CSS_SECONDARY}-identity: ${secondary.identityHex};` : `  --${CSS_SECONDARY}-identity: var(--${CSS_BRAND}-identity);`;
   const p0hex = (s, fallback) => s ? stopHex(s) : fallback;
@@ -3634,12 +3645,6 @@ function brandCss(slug, displayName, r, secondary, noteSuffix = "", neutralLevel
       `  --${CSS_BRAND}-stamp-on: ${onColor(esc.onFillIsWhite)};`
     ];
   };
-  const softOnCta = (mode) => {
-    if (!secondary || secondaryStyle === "outline") 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]});`];
-  };
   const outline = (mode) => {
     if (secondaryStyle !== "outline" || !secondary) return [];
     const s8 = (mode === "light" ? secondary.light : secondary.dark).find((s) => s.stop === 8);
@@ -3683,7 +3688,6 @@ function brandCss(slug, displayName, r, secondary, noteSuffix = "", neutralLevel
     ...linkInverse("light"),
     brandIdentity,
     ...secondaryLight,
-    ...softOnCta("light"),
     ...outline("light"),
     secondaryIdentity,
     ...brandKindBody(CSS_NEUTRAL, nScale, "light", page.light),
@@ -3696,7 +3700,6 @@ function brandCss(slug, displayName, r, secondary, noteSuffix = "", neutralLevel
     ...link("dark"),
     ...linkInverse("dark"),
     ...secondaryDark,
-    ...softOnCta("dark"),
     ...outline("dark"),
     ...brandKindBody(CSS_NEUTRAL, nScale, "dark", page.dark),
     ...effOverrides.flatMap((o) => brandKindBody(SIGNAL_EMIT_NAME[o.name], o.scale, "dark", page.dark)),
@@ -3976,6 +3979,7 @@ export {
   RESOLVER_ID,
   SCALE_STOP_COUNT,
   SCRIM_ALPHA,
+  SCRIM_VAR,
   SECONDARY_DISTINCT_DELTA_E,
   SHADOW_ALPHAS,
   SIGNALS2 as SIGNALS,
@@ -4003,6 +4007,7 @@ export {
   generateScale,
   generateSubtleSecondary,
   neutralCss,
+  neutralTintHue,
   pageStopFor,
   parseToken,
   resolveBrand,

package/dist-lib/types/engine/cssRender.d.ts

@@ -35,11 +35,12 @@ export type ShadowRung = keyof typeof SHADOW_ALPHAS;
 export declare const SCRIM_ALPHA = 0.6;
 export declare const DISABLED_OPACITY = 0.38;
 export declare const TRANSPARENT_VAR = "--alpha-transparent";
+export declare const SCRIM_VAR = "--abs-black-060";
 export declare const offsetRgba: (rung: OffsetRung, mode: "light" | "dark") => string;
 export declare const alphaRootVars: (mode: "light" | "dark") => string[];
 export declare function ctaPageLc(s: GeneratedScale, mode: 'light' | 'dark', page: ColorStop): number;
 export declare function ctaNeedsBorder(s: GeneratedScale, mode: 'light' | 'dark', page: ColorStop | undefined): boolean;
-export declare function brandKindBody(prefix: string, s: GeneratedScale, mode: 'light' | 'dark', page: ColorStop | undefined): string[];
+export declare function brandKindBody(prefix: string, s: GeneratedScale, mode: 'light' | 'dark', page: ColorStop | undefined, on?: 'soft' | 'solid'): string[];
 export declare function brandKindP3Body(prefix: string, s: GeneratedScale, mode: 'light' | 'dark'): string[];
 export declare function neutralCss(selector: string, brandH: number, level?: NeutralLevel, contrastProfile?: ContrastProfile, ctaBorder?: boolean): string;
 export declare function signalsCss(contrastProfile?: ContrastProfile): string;

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

@@ -1,6 +1,6 @@
-export { generateScale, generateNeutralScale, generateSubtleSecondary, type GeneratedScale, type ColorStop, type GenerateOptions, type NeutralLevel, type ContrastProfile, } from './engine/colorEngine';
+export { generateScale, generateNeutralScale, generateSubtleSecondary, neutralTintHue, type NeutralSource, 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, SHADOW_ALPHAS, SCRIM_ALPHA, DISABLED_OPACITY, type ShadowRung, ctaNeedsBorder, ctaBorderRung, pageStopFor, } from './engine/cssRender';
+export { brandCss, neutralCss, signalsCss, stopsToVars, toHex, stopHex, OFFSET_ALPHAS, SHADOW_ALPHAS, SCRIM_ALPHA, SCRIM_VAR, DISABLED_OPACITY, type ShadowRung, 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';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "okchroma",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "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": {

package/tokens/semantic.css

@@ -1,20 +1,18 @@
 /*
-  Semantic token layer — maps role names to primitive tokens.
+  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-0's side of the ramp. Light descends the ramp as elevation rises
-     (sunken paper-5 → high paper-0 white); dark ascends it (sunken paper-0
-     black → high paper-5). paper-0 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. */
+  /* Elevation planes dim, low, mid, high: mid is the raised plane components sit on,
+     the page behind it is low, and the two extremes are edge cases. Both themes use
+     the SAME four stops in reversed order, so elevation always moves toward paper-0's
+     side of the ramp. Light descends the ramp as elevation rises (dim paper-5 to high
+     paper-0, white); dark ascends it (dim paper-0, the deep tinted ground, to high
+     paper-5). paper-0 flips with the mode, so it is always the extreme pole: the high
+     in light, the dim in dark. */
   --surface-dim:        var(--neutral-paper-5);
   --surface-low:         var(--neutral-paper-3);
   --surface-mid:       var(--neutral-paper-1);
@@ -22,41 +20,40 @@
 
   --fg-default:           var(--neutral-pen-70);
   --fg-subtle:            var(--neutral-pencil-47);
-  /* --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 pen 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 crayon-26, 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; crayon-26 is where the
-     requirement actually lives, and it is the one stop this round does not move.
-     Decorative borders are --border-subtle (highlighter-11) and the per-family
-     --*-border-default (highlighter-15). */
+
+  /* --border-default IS THE ACCESSIBILITY BORDER: a border that has to be there (inputs
+     and other controls), so it rides crayon-26, the stop that carries the 3:1 non-text
+     contrast requirement. Decorative borders are --border-subtle (highlighter-11) and
+     the per-family --*-border-default (highlighter-15). */
   --border-default:       var(--neutral-crayon-26);
   --border-subtle:        var(--neutral-highlighter-11);
 
-  /* 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 transparencies: pure black, the engine's SHADOW_ALPHAS, the same rows the
+     plugins write as shadow-04|08|12. Dark is heavier by necessity: near black a
+     light-mode alpha vanishes, so the dark values carry the same roles at heavier
+     alphas. Elevation recipes 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);
 
-  /* Disabled opacity (owner 2026-08-29): disabled is a COMPONENT-LEVEL opacity —
-     colors stay the enabled ones and never swap. Mode-invariant; mirrors the JS
-     API's DISABLED_OPACITY constant 1:1. */
+  /* The scrim: the modal veil, black at 60% in both modes. The primitive
+     (--abs-black-060) rides signalsCss's :root, the same row the plugins write
+     as abs-black-060; this alias is the job word. */
+  --scrim: var(--abs-black-060);
+
+  /* Disabled opacity: disabled is a COMPONENT-LEVEL opacity. Colors stay the enabled
+     ones and never swap. Mode-invariant; mirrors the JS API's DISABLED_OPACITY
+     constant 1:1. */
   --disabled-opacity: 0.38;
 }
 
 [data-brand][data-theme="dark"] {
-  /* Dark runs the same four stops upward: sunken paper-0 (black) → low paper-1 →
-     base paper-3 → high paper-5 — the one-level highest background (C27: every
+  /* Dark runs the same four stops upward: dim paper-0 (the deep tinted ground), low
+     paper-1, mid paper-3, high paper-5, the one-level highest background: every
      family's paper-5 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-3 (the light value); the stops themselves did not move. */
+     plane by construction. Low needs its own override here because the shared
+     block's low is paper-3, the light value. */
   --surface-dim:        var(--paper-0, #000000);
   --surface-low:         var(--neutral-paper-1);
   --surface-mid:       var(--neutral-paper-3);
@@ -90,15 +87,15 @@
   --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 pen stops unless a custom
+  /* the SYSTEM LINK (one trio per theme; aliases the primary's pen 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 (a pen-70 fill); always its own emitted values —
-     no stop is anchored against that ground, so there is no alias posture */
+  /* the INVERSE link trio: the same link seed re-solved for text on inverted surfaces
+     (a pen-70 fill); always its own emitted values, since no stop is anchored against
+     that ground and 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);
@@ -131,20 +128,15 @@
 /* ─── 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-pen-70. The old alert-high/alert-med role prefixes collapsed
-   into critical/warning in the same round.
-
-   -fg-on-emphasis rides --paper-0, NOT a solved on-color: the engine's on-highlight
-   token was deleted with the highlight band (owner 2026-07-29). paper-0 is the
-   mode-flipping paper extreme — white in light, the tinted deep ground in dark — and
-   it clears 4.5 against pencil-47 everywhere (agnostic 360-seed sweep, worst 4.96
-   light / 8.04 dark). -bg-emphasis / -border-emphasis moved from highlight-9 to
-   pencil-47 (ink-9 pre-Stage-B) with it; in dark that reads lighter (contrast vs
-   paper-5, 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. */
+   Signal families emit by ROLE (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-pen-70.
+
+   -fg-on-emphasis rides --paper-0, NOT a solved on-color. paper-0 is the
+   mode-flipping paper extreme (white in light, the deep tinted ground in dark) and
+   it clears the 4.5:1 text bar against pencil-47 in every family and both modes;
+   the band audit holds that floor over an agnostic sweep. -bg-emphasis and
+   -border-emphasis ride pencil-47. */
 
 [data-brand] {
   --critical-fg:                    var(--critical-pen-70);