okchroma 0.3.1 → 0.5.0

package/README.md

@@ -5,13 +5,13 @@ light and dark token system whose contrast requirements are solved during genera
 then emits it as CSS custom properties or Figma variables.
 
 Every family (neutral, brand, brand-alt, critical, warning, positive, info) carries the
-same scale: 3 papers, 4 highlighters, 1 crayon, 1 pencil, 2 pens, plus the stamp (the
+same scale: 3 papers, 4 chalks, 1 highlighter, 1 pencil, 2 pens, plus the stamp (the
 solid fill with its hover and pressed states, its edge, and its text). The neutral adds
 the two poles. Light and dark resolve together and ship on the same names, so a token is
 mapped once and holds for any brand.
 
-Contrast is built into the math, not checked afterwards: crayon reads on every paper at
-3:1 (the non-text bar), pencil at 4.5:1, pen at 4.5:1 on every paper and highlighter in
+Contrast is built into the math, not checked afterwards: highlighter reads on every paper at
+3:1 (the non-text bar), pencil at 4.5:1, pen at 4.5:1 on every paper and chalk in
 both directions; the stamp's text passes 4.5:1 on its fill. APCA is used once, as a booster
 that nudges the stamp fill until its text reads at Lc 65. Each claim, its scope, and the audit that
 proves it: [Guarantees](https://egerrity.github.io/okchroma/#/docs/guarantees).

package/dist-lib/index.cjs

@@ -24,8 +24,10 @@ __export(index_exports, {
   DEFAULT_LINK_HEX: () => DEFAULT_LINK_HEX,
   DISABLED_OPACITY: () => DISABLED_OPACITY,
   EXT_KEY: () => EXT_KEY,
+  INTERACTION_RUNGS: () => INTERACTION_RUNGS,
   MODE_SPECS: () => MODE_SPECS,
   OFFSET_ALPHAS: () => OFFSET_ALPHAS,
+  OPACITY_RUNGS: () => OPACITY_RUNGS,
   OUTLINE_HOVER_ALPHA: () => OUTLINE_HOVER_ALPHA,
   PAPER_0: () => PAPER_0,
   PEN_100: () => PEN_100,
@@ -59,6 +61,10 @@ __export(index_exports, {
   generateScale: () => generateScale,
   generateSubtleSecondary: () => generateSubtleSecondary,
   neutralCss: () => neutralCss,
+  neutralTintHue: () => neutralTintHue,
+  opacityLeafName: () => opacityLeafName,
+  opacityTokenPath: () => opacityTokenPath,
+  opacityVarName: () => opacityVarName,
   pageStopFor: () => pageStopFor,
   parseToken: () => parseToken,
   resolveBrand: () => resolveBrand,
@@ -397,7 +403,7 @@ var NEUTRAL_TINT_POINTS = {
     [0.95, 0.895],
     // paper-3  ─┘
     [0.924, 1],
-    // wash-4   ─┐ peak: the mid-highlighter band, the neutral's most-branded moment
+    // wash-4   ─┐ peak: the mid-chalk band, the neutral's most-branded moment
     [0.892, 1],
     // wash-5   ─┘
     [0.852, 0.842],
@@ -405,7 +411,7 @@ var NEUTRAL_TINT_POINTS = {
     [0.801, 0.653],
     // wash-7    │
     [0.738, 0.505],
-    // crayon-26
+    // highlighter-26
     [0.6, 0.4],
     // knee (ex-scaffold)   the drop-off: hue fades as you climb
     [0.56, 0.347],
@@ -431,7 +437,7 @@ var NEUTRAL_TINT_POINTS = {
     [0.42, 0.653],
     // wash-7
     [0.55, 0.505],
-    // crayon-26
+    // highlighter-26
     [0.6, 0.4],
     // knee (ex-scaffold)
     [0.64, 0.347],
@@ -806,18 +812,18 @@ var SHARED_NAMES = {
   2: "paper-3",
   // stop 3 renamed wash-3 → paper-3 (owner 2026-07-24, elevation round): it is a
   // PLANE in both themes (light sink / dark pop), so it belongs to the surface band.
-  // NAME ONLY — generation is index-keyed and unchanged; the highlighter-collision machinery
-  // (collision.ts HIGHLIGHTER_STOPS) deliberately still spans stops 3–7. (The requirement
+  // NAME ONLY — generation is index-keyed and unchanged; the chalk-collision machinery
+  // (collision.ts CHALK_STOPS) deliberately still spans stops 3–7. (The requirement
   // spec's `group` label followed the band to 'paper' on 2026-08-31 — labels only,
   // the spans never moved; see spec.ts groupOf.)
   // Stage B (owner 2026-08-07, names only): relabeled to the ROOT_L-derived digit,
   // paper-5 — same band, same index.
   3: "paper-5",
-  4: "highlighter-8",
-  5: "highlighter-11",
-  6: "highlighter-15",
-  7: "highlighter-20",
-  8: "crayon-26",
+  4: "chalk-8",
+  5: "chalk-11",
+  6: "chalk-15",
+  7: "chalk-20",
+  8: "highlighter-26",
   // THE PEN BAND (C49, owner 2026-08-05): the first text stop + emphasis fill (the
   // 2026-07-29 highlight collapse — the old highlight-9 and on-highlight are
   // deleted; this stop carries both jobs, its on-color a paper token), the between
@@ -869,13 +875,12 @@ var SYSTEM_LEAF = {
   },
   ALPHA: {
     TRANSPARENT: "system/alpha/transparent",
-    SCRIM: "system/alpha/abs-black-060",
     INK: "system/alpha/ink",
     // the DIRECTIONAL ladders (owner 2026-08-31, renaming the 2026-08-18 bare rungs
     // and the 2026-08-29 inverse ladder): away-from-bg is the page-polarity pole
     // (black in light, white in dark), toward-bg the flipped pole — STATE LAYERS for
     // INVERTED grounds, whose polarity is opposite the page's. (Never call toward-bg
-    // a "highlighter": that word belongs to the tinted band stops.) The reversal lives in
+    // a "chalk": that word belongs to the tinted band stops.) The reversal lives in
     // the engine: a consumer on an inverted ground names one token and never picks a
     // pole. Colored fills never ride these; their states stay engine-solved stops.
     // Rungs are two-digit percent, harmonizing with shadow-04/08/12.
@@ -888,6 +893,19 @@ var SYSTEM_LEAF = {
     SHADOW_04: "system/alpha/shadow-04",
     SHADOW_08: "system/alpha/shadow-08",
     SHADOW_12: "system/alpha/shadow-12"
+  },
+  // the OPACITY LADDER's rows: bare numbers, never colors. `alpha` above is the group
+  // of colors that carry transparency; `opacity` is the numbers they compose with
+  // (values in cssRender OPACITY_RUNGS; the ext plugin zones these under utility/).
+  OPACITY: {
+    "004": "system/opacity/004",
+    "008": "system/opacity/008",
+    "012": "system/opacity/012",
+    "016": "system/opacity/016",
+    "024": "system/opacity/024",
+    "032": "system/opacity/032",
+    "048": "system/opacity/048",
+    "064": "system/opacity/064"
   }
 };
 var SURFACE_PLANE_LAW = {
@@ -920,14 +938,14 @@ var P_FIXED = { hue: "warm-torsion", L: "fixed", chroma: "ladder" };
 var P_TEXT = { hue: "warm-torsion", L: "perceptual", chroma: "brand" };
 var S8 = { metric: "wcag", against: "paper-5", target: STOP_8_NONTEXT_CONTRAST, level: "AA" };
 var T9 = { metric: "wcag", against: "paper-5", target: PENCIL_9_CONTRAST, level: "AA" };
-var T10 = { metric: "wcag", against: "highlighter-20", target: PEN_10_CONTRAST, level: "AA" };
+var T10 = { metric: "wcag", against: "chalk-20", target: PEN_10_CONTRAST, level: "AA" };
 var T11 = { metric: "wcag", against: "paper-5", target: PEN_11_CONTRAST_FLOOR, level: "AAA" };
 var ONS = { onFill: { metric: "apca-pole", enforce: true, ratioFloor: 4.5, coEnforceLc: 65 } };
 var LIGHT = {
   stops: [
     // paper-0 (paper-0 pre-Stage-B): the resolved ladder extreme — in light it genuinely is white (rootL 1.0, zero chroma)
     { stop: 0, rootL: 1, group: groupOf(0), produce: { hue: "warm-drift", L: "fixed", chroma: "ladder" }, satFraction: SCALE_C_LIGHT[0].sat, baseC: SCALE_C_LIGHT[0].base },
-    // paper/highlighter/crayon-26: perceptual ladder/envelope blend on the geometric ROOT_L_LIGHT scaffold. Separation
+    // paper/chalk/highlighter-26: perceptual ladder/envelope blend on the geometric ROOT_L_LIGHT scaffold. Separation
     // falls out of the shape (see above) — no min-separation require. Only stop 8 carries a require: the WCAG
     // 3:1 vs the resolved paper-3 (paper-2) (re-solves automatically since it references paper-3 (paper-2)).
     ...[1, 2, 3, 4, 5, 6, 7, 8].map((stop) => ({
@@ -958,7 +976,7 @@ var DARK = {
     // paper-0 (paper-0 pre-Stage-B): the resolved ladder extreme — one seam BELOW paper-1 (paper-1), deep and brand-tinted, never the
     // absolute void (the old hard-coded #000000 was "too much"). Lift applies like the rest of the scale.
     { stop: 0, rootL: PAPER0_DARK_ROOT_L, group: groupOf(0), produce: P_LIFT, satFraction: SCALE_C_DARK[0].sat },
-    // paper/highlighter 1–7: perceptual on the dark scaffold. stop 8: FIXED at the hand-placed scaffold BUT with the
+    // paper/chalk 1–7: perceptual on the dark scaffold. stop 8: FIXED at the hand-placed scaffold BUT with the
     // 3:1 non-text require DECLARED (the Stage-5 flip, owner-approved) — the blue-recede failure is prevented
     // BY RULE, not by patch. The require now genuinely PLACES the stop rather than catching a few low-luminance
     // hues: on the delta-carry path it solves from the sentinel every time, and the old claim that "most hues
@@ -1903,7 +1921,7 @@ function p2Diff(a, b) {
 var DEFAULT_APCA_LC_MAP = { 3: 30, 4.5: 75, 6.5: 85, 7: 90 };
 function toApca(req, lcMap) {
   if (req.metric !== "wcag") return req;
-  if (req.against === "highlighter-20") return { metric: "apca", against: "paper-3", targetLc: 85 };
+  if (req.against === "chalk-20") return { metric: "apca", against: "paper-3", targetLc: 85 };
   const targetLc = lcMap[req.target];
   if (targetLc === void 0) throw new Error(`apca profile: no Lc mapping for wcag target ${req.target}`);
   return { metric: "apca", against: req.against, targetLc };
@@ -2389,7 +2407,7 @@ function resolveRamp(hex, mode, spec, opts) {
     if (!ref) throw new Error(`stop ${forWhom}: require against stop ${stopNum} but it is not resolved yet`);
     return ref;
   };
-  const AGAINST_STOP = { "paper-1": 1, "paper-3": 2, "paper-5": 3, "highlighter-20": 7 };
+  const AGAINST_STOP = { "paper-1": 1, "paper-3": 2, "paper-5": 3, "chalk-20": 7 };
   const declaredAnchor = (req) => req.metric === "min-separation" ? 1 : AGAINST_STOP[req.against] ?? 2;
   const wcagAnchorStop = (req, stop) => stop >= 9 && declaredAnchor(req) <= 3 ? 3 : declaredAnchor(req);
   const textGround = ctx.opts?.textGround?.[mode];
@@ -2503,13 +2521,13 @@ function resolveRamp(hex, mode, spec, opts) {
         const own = contrastRatio(y2, anchorShipY);
         return paperBound ? Math.min(own, contrastRatio(y2, crossBoundY)) : own;
       };
-      const highlighterBoundY = ctx.opts?.crossHighlighterBoundY && sp.stop >= 10 && !textGround ? ctx.opts.crossHighlighterBoundY[mode] : void 0;
-      const highlighterRatio = (L) => highlighterBoundY === void 0 ? Infinity : contrastRatio(shippedY(L, placed.C, placed.H), highlighterBoundY);
+      const chalkBoundY = ctx.opts?.crossChalkBoundY && sp.stop >= 10 && !textGround ? ctx.opts.crossChalkBoundY[mode] : void 0;
+      const chalkRatio = (L) => chalkBoundY === void 0 ? Infinity : contrastRatio(shippedY(L, placed.C, placed.H), chalkBoundY);
       const paperBoundY = ctx.opts?.crossPaperBoundY && sp.stop >= 8 && !textGround ? ctx.opts.crossPaperBoundY[mode] : void 0;
       const paperBar = sp.stop === 8 ? STOP_8_NONTEXT_CONTRAST : sp.stop === 9 ? PENCIL_9_CONTRAST : PEN_10_CONTRAST;
       const paperRatio = (L) => paperBoundY === void 0 ? Infinity : contrastRatio(shippedY(L, placed.C, placed.H), paperBoundY);
       const target = sp.require.target;
-      const clears = (L) => shipRatio(L) >= target && highlighterRatio(L) >= PEN_10_CONTRAST && paperRatio(L) >= paperBar;
+      const clears = (L) => shipRatio(L) >= target && chalkRatio(L) >= PEN_10_CONTRAST && paperRatio(L) >= paperBar;
       if (!clears(placed.L)) {
         const away = shippedY(placed.L, placed.C, placed.H) < anchorShipY ? -1 : 1;
         let L2 = placed.L;
@@ -2525,7 +2543,7 @@ function resolveRamp(hex, mode, spec, opts) {
         shipRatio(placed.L)
       );
       if (got < sp.require.target - 1e-3) unresolvable = `stop ${sp.stop}: contrast ${got.toFixed(2)} < required ${sp.require.target}`;
-      else if (highlighterRatio(placed.L) < PEN_10_CONTRAST - 1e-3) unresolvable = `stop ${sp.stop}: contrast ${highlighterRatio(placed.L).toFixed(2)} < required ${PEN_10_CONTRAST} on the worst chromatic highlighter-20`;
+      else if (chalkRatio(placed.L) < PEN_10_CONTRAST - 1e-3) unresolvable = `stop ${sp.stop}: contrast ${chalkRatio(placed.L).toFixed(2)} < required ${PEN_10_CONTRAST} on the worst chromatic chalk-20`;
       else if (paperRatio(placed.L) < paperBar - 1e-3) unresolvable = `stop ${sp.stop}: contrast ${paperRatio(placed.L).toFixed(2)} < required ${paperBar} on the worst chromatic paper-5`;
     } else if (sp.require?.metric === "apca") {
       const ga = apcaGroundOf(sp.require, sp.stop);
@@ -2717,6 +2735,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);
@@ -2727,9 +2751,9 @@ function generateNeutralScale(brandH, level = "default", contrastProfile) {
     chromaCurve: curve,
     enforceOnFillContrast: true,
     contrastProfile,
-    // T13: the neutral's pens clear every chromatic family's highlighter-20 (the symmetric
+    // T13: the neutral's pens clear every chromatic family's chalk-20 (the symmetric
     // pen guarantee); the chromatic ramps clear the neutral's through NEUTRAL_W80_WORST_SHIP_Y
-    crossHighlighterBoundY: CHROMATIC_W80_WORST_SHIP_Y,
+    crossChalkBoundY: CHROMATIC_W80_WORST_SHIP_Y,
     crossPaperBoundY: CHROMATIC_P3_WORST_SHIP_Y
   });
   const asCta = (stop, src) => makeStop(stop, src.L, src.C, src.H);
@@ -2826,7 +2850,7 @@ var COLOR_WORD = {
   [FAMILY.info]: " (blue)"
 };
 var PAPER = { req: "backgrounds, inverted text", theming: (f) => TINT[f], collides: true };
-var HIGHLIGHTER = { req: "subtle interactive states, decorative borders, illos, signal hierarchy", theming: (f) => TINT[f], collides: true };
+var CHALK = { req: "decorative borders, inverted text, 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",
@@ -2840,13 +2864,13 @@ var SCALE = {
   "paper-97-overlay": OVERLAY,
   "paper-5": { req: "backgrounds, inverted text", theming: (f) => `${TINT[f]}. Worst background text stops must clear.`, collides: true },
   "paper-95-overlay": OVERLAY,
-  "highlighter-8": HIGHLIGHTER,
-  "highlighter-11": HIGHLIGHTER,
-  "highlighter-15": HIGHLIGHTER,
-  "highlighter-20": HIGHLIGHTER,
+  "chalk-8": CHALK,
+  "chalk-11": CHALK,
+  "chalk-15": CHALK,
+  "chalk-20": CHALK,
   // ("icons" KEPT through the 2026-08-28 on-flood strip (owner): an "icon" query
-  // landing on the crayon rows is worth its ic-ON-s noise — the one surviving body carrier)
-  "crayon-26": { req: "focus rings, icons, large text", contrast: AA_LARGE, theming: solved, collides: true },
+  // landing on the highlighter rows is worth its ic-ON-s noise — the one surviving body carrier)
+  "highlighter-26": { req: "focus rings, icons, large text, translucent state layers over any ground", contrast: AA_LARGE, theming: solved, collides: true },
   "pencil-47": { req: "regular text, inverted backgrounds", contrast: AA_BODY, theming: solved, collides: true },
   "pen-58": { 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
@@ -2867,6 +2891,8 @@ 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 OFFSET_INVERSE = { req: "state layers over inverted backgrounds", theming: "the offset ladder with its pole flipped, so inverted grounds keep the same rungs" };
 var SHADOW = { req: "drop shadows" };
+var OPACITY_RUNG = { req: "translucency weight for any color", theming: "a bare number; a translucent row composes its color with one rung" };
+var OPACITY_STATE = { req: "translucency weight for any color; the state layer weight of the non-text stop over any ground", theming: "a bare number; a translucent row composes its color with one rung" };
 var PLANE = (req) => ({ req, theming: "aliased to the gray ramp" });
 var LINK = (state, contrast) => ({
   req: "links" + state,
@@ -2888,8 +2914,17 @@ var SYSTEM = {
   // ("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" },
+  // the OPACITY LADDER: bare numbers a translucent color row composes with (the
+  // scrim is the absolute black at the top rung). No conformance line of its own:
+  // the state-layer claim rides the non-text stop these weights apply to
+  "system/opacity/004": OPACITY_RUNG,
+  "system/opacity/008": OPACITY_STATE,
+  "system/opacity/012": OPACITY_STATE,
+  "system/opacity/016": OPACITY_STATE,
+  "system/opacity/024": OPACITY_STATE,
+  "system/opacity/032": OPACITY_STATE,
+  "system/opacity/048": OPACITY_RUNG,
+  "system/opacity/064": OPACITY_RUNG,
   // ("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" },
@@ -2897,7 +2932,7 @@ var SYSTEM = {
   "system/alpha/away-from-bg/08": OFFSET,
   "system/alpha/away-from-bg/16": OFFSET,
   // the inverse ladder: the offset rungs with the pole flipped per mode, for
-  // highlighters and edges over inverted backgrounds ("interaction" avoided in the
+  // chalks and edges over inverted backgrounds ("interaction" avoided in the
   // bodies: acti-ON would feed the "on" flood)
   "system/alpha/toward-bg/06": OFFSET_INVERSE,
   "system/alpha/toward-bg/08": OFFSET_INVERSE,
@@ -2964,15 +2999,15 @@ function checkCollision(brand, signalScale, signalDef, mode) {
     collides: hueGate && deltaE <= threshold
   };
 }
-var HUE_COLLISION_HIGHLIGHTER_DEG = 15;
+var HUE_COLLISION_CHALK_DEG = 15;
 var HUE_COLLISION_MIN_V = 0.5;
 var SECONDARY_NOTE_MIN_V = HUE_NOISE_C / VIVID_C;
-var HIGHLIGHTER_STOPS = [3, 4, 5, 6, 7];
-function highlighterProximity(brand, sig, mode) {
+var CHALK_STOPS = [3, 4, 5, 6, 7];
+function chalkProximity(brand, sig, mode) {
   const b = mode === "light" ? brand.light : brand.dark;
   const s = mode === "light" ? sig.light : sig.dark;
   let dH = Infinity, dE = Infinity;
-  for (const k of HIGHLIGHTER_STOPS) {
+  for (const k of CHALK_STOPS) {
     const bs = b.find((x2) => x2.stop === k), ss = s.find((x2) => x2.stop === k);
     if (!bs || !ss) continue;
     dH = Math.min(dH, hueDistance(bs.H, ss.H));
@@ -2981,15 +3016,15 @@ function highlighterProximity(brand, sig, mode) {
   return { dH, dE };
 }
 function checkHueCollision(brand, signalScale, signalDef, opts) {
-  const l = highlighterProximity(brand, signalScale, "light");
-  const d = highlighterProximity(brand, signalScale, "dark");
+  const l = chalkProximity(brand, signalScale, "light");
+  const d = chalkProximity(brand, signalScale, "dark");
   const vividness = Math.min(1, brand.brandC / VIVID_C);
   return {
     signal: signalDef.name,
-    dHueHighlighter: { light: l.dH, dark: d.dH },
-    highlighterDeltaE: { light: l.dE, dark: d.dE },
+    dHueChalk: { light: l.dH, dark: d.dH },
+    chalkDeltaE: { light: l.dE, dark: d.dE },
     vividness,
-    collides: vividness >= (opts?.minV ?? HUE_COLLISION_MIN_V) && Math.min(l.dH, d.dH) <= HUE_COLLISION_HIGHLIGHTER_DEG
+    collides: vividness >= (opts?.minV ?? HUE_COLLISION_MIN_V) && Math.min(l.dH, d.dH) <= HUE_COLLISION_CHALK_DEG
   };
 }
 var YELLOW_SPLIT_H = 96;
@@ -3382,7 +3417,7 @@ function resolveTheme(input) {
     for (const def of SIGNALS2) {
       if (adoptedForSecondary.has(def.name)) continue;
       const h = checkHueCollision(scale2, effectiveOf(def.name), def, { minV: SECONDARY_NOTE_MIN_V });
-      if (h.collides) out.push(wording(def.name, Math.min(h.highlighterDeltaE.light, h.highlighterDeltaE.dark)));
+      if (h.collides) out.push(wording(def.name, Math.min(h.chalkDeltaE.light, h.chalkDeltaE.dark)));
     }
     return out;
   };
@@ -3432,7 +3467,7 @@ function resolveTheme(input) {
         derived: true,
         notes: [
           `secondary derived from the brand color (default model, seed ${liftedHex})`,
-          ...signalNotesFor(scale2, (name, dE) => `derived secondary sits on the ${name} signal's hue (highlighter \u0394E ${dE.toFixed(3)}) \u2014 it tracks the brand color`)
+          ...signalNotesFor(scale2, (name, dE) => `derived secondary sits on the ${name} signal's hue (chalk \u0394E ${dE.toFixed(3)}) \u2014 it tracks the brand color`)
         ],
         distinctness: ctaDistinctness(primary.scale, scale2)
       },
@@ -3457,7 +3492,7 @@ function resolveTheme(input) {
         derived: false,
         notes: [
           `secondary keeps your color through the ramp; the cta is a tint of it (tint seed ${tintedHex})`,
-          ...signalNotesFor(scale2, (name, dE) => `secondary sits on the ${name} signal's hue (highlighter \u0394E ${dE.toFixed(3)}) \u2014 it tracks your color`)
+          ...signalNotesFor(scale2, (name, dE) => `secondary sits on the ${name} signal's hue (chalk \u0394E ${dE.toFixed(3)}) \u2014 it tracks your color`)
         ],
         distinctness: distinctness2
       },
@@ -3469,7 +3504,7 @@ function resolveTheme(input) {
   const scale = rSec.scale;
   const level = "standard";
   mergeSecondarySignals(scale, input.secondaryHex);
-  const secNotes = signalNotesFor(scale, (name, dE) => `secondary reads close to the ${name} signal (highlighter \u0394E ${dE.toFixed(3)}) \u2014 your color ships untouched`);
+  const secNotes = signalNotesFor(scale, (name, dE) => `secondary reads close to the ${name} signal (chalk \u0394E ${dE.toFixed(3)}) \u2014 your color ships untouched`);
   const distinctness = ctaDistinctness(primary.scale, scale);
   if (distinctness.close)
     notes.push(`secondary reads close to the primary (\u0394E ${Math.min(distinctness.light, distinctness.dark).toFixed(2)}) \u2014 consider a more distinct color`);
@@ -3514,21 +3549,29 @@ var OFFSET_ALPHAS = { 6: 0.06, 8: 0.08, 16: 0.16 };
 var ctaBorderRung = (prefix) => prefix === CSS_NEUTRAL ? 8 : prefix === CSS_SECONDARY ? 6 : 16;
 var offsetLeafName = (rung) => String(rung).padStart(2, "0");
 var offsetVarName = (rung) => `--alpha-away-from-bg-${offsetLeafName(rung)}`;
+var OPACITY_RUNGS = { 4: 0.04, 8: 0.08, 12: 0.12, 16: 0.16, 24: 0.24, 32: 0.32, 48: 0.48, 64: 0.64 };
+var INTERACTION_RUNGS = [8, 12, 16, 24, 32];
+var opacityLeafName = (rung) => String(rung).padStart(3, "0");
+var opacityVarName = (rung) => `--opacity-${opacityLeafName(rung)}`;
+var opacityTokenPath = (rung) => SYSTEM_LEAF.OPACITY[opacityLeafName(rung)];
 var SHADOW_ALPHAS = {
-  4: { light: 0.04, dark: 0.32 },
-  8: { light: 0.08, dark: 0.48 },
-  12: { light: 0.12, dark: 0.64 }
+  4: { light: OPACITY_RUNGS[4], dark: OPACITY_RUNGS[32] },
+  8: { light: OPACITY_RUNGS[8], dark: OPACITY_RUNGS[48] },
+  12: { light: OPACITY_RUNGS[12], dark: OPACITY_RUNGS[64] }
 };
-var SCRIM_ALPHA = 0.6;
+var SCRIM_ALPHA = OPACITY_RUNGS[64];
 var DISABLED_OPACITY = 0.38;
 var TRANSPARENT_VAR = "--alpha-transparent";
 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;`,
+  // the opacity ladder, mode-invariant like transparent; repeated in the dark block to
+  // keep the set together
+  ...Object.keys(OPACITY_RUNGS).map(Number).map((r) => `  ${opacityVarName(r)}: ${OPACITY_RUNGS[r]};`),
   ...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
-  // called a "highlighter" — that word is the tinted band's). One spelling with the Figma
+  // called a "chalk" — that word is the tinted band's). One spelling with the Figma
   // row: --alpha-toward-bg-06 ↔ system/alpha/toward-bg/06.
   ...Object.keys(OFFSET_ALPHAS).map(Number).sort((a, b) => a - b).map((r) => `  --alpha-toward-bg-${offsetLeafName(r)}: ${offsetRgba(r, mode === "light" ? "dark" : "light")};`)
 ];
@@ -3540,7 +3583,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;
@@ -3555,14 +3598,14 @@ function brandKindBody(prefix, s, mode, page) {
     `  --${prefix}-stamp-fill-pressed: ${stopHex(f.ctaPressed)};`,
     `  --${prefix}-stamp-edge: var(${border ? offsetVarName(ctaBorderRung(prefix)) : TRANSPARENT_VAR});`,
     // the SOFT on-cta (owner 2026-08-04: "neutral cta on's should also be the alpha"): the
-    // neutral's cta is the scale-fed HIGHLIGHTER-level fill, the system's other quiet cta, so its
+    // neutral's cta is the scale-fed CHALK-level fill, the system's other quiet cta, so its
     // 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 +3672,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 opacity ladder (mode-invariant) repeat
+    // harmlessly and keep the set together.
     ...alphaRootVars("light"),
     ...lightBlocks,
     `}`,
@@ -3678,8 +3722,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 +3758,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 +3801,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 +3813,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)),
@@ -3957,7 +3994,8 @@ function themeToFigma(r, input) {
       if (tok && "$type" in tok) putLeaf(g2, path, tok);
     }
     putLeaf(g2, SYSTEM_LEAF.ALPHA.TRANSPARENT, pole(true, 0));
-    putLeaf(g2, SYSTEM_LEAF.ALPHA.SCRIM, pole(false, SCRIM_ALPHA));
+    for (const rung of Object.keys(OPACITY_RUNGS).map(Number))
+      putLeaf(g2, opacityTokenPath(rung), { $type: "number", $value: OPACITY_RUNGS[rung] });
     putLeaf(g2, SYSTEM_LEAF.ALPHA.INK, pole(mode === "dark", SOFT_ON_CTA_ALPHA[mode]));
     putLeaf(g2, SYSTEM_LEAF.ALPHA.AWAY_FROM_BG_06, OFFSET_TOKEN(6, mode));
     putLeaf(g2, SYSTEM_LEAF.ALPHA.AWAY_FROM_BG_08, OFFSET_TOKEN(8, mode));