okchroma 0.3.1 → 0.5.0

package/dist-lib/index.mjs

@@ -318,7 +318,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],
@@ -326,7 +326,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],
@@ -352,7 +352,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],
@@ -727,18 +727,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
@@ -790,13 +790,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.
@@ -809,6 +808,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 = {
@@ -841,14 +853,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) => ({
@@ -879,7 +891,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
@@ -1824,7 +1836,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 };
@@ -2310,7 +2322,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];
@@ -2424,13 +2436,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;
@@ -2446,7 +2458,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);
@@ -2638,6 +2650,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);
@@ -2648,9 +2666,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);
@@ -2747,7 +2765,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",
@@ -2761,13 +2779,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
@@ -2788,6 +2806,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,
@@ -2809,8 +2829,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" },
@@ -2818,7 +2847,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,
@@ -2885,15 +2914,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));
@@ -2902,15 +2931,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;
@@ -3303,7 +3332,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;
   };
@@ -3353,7 +3382,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)
       },
@@ -3378,7 +3407,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
       },
@@ -3390,7 +3419,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`);
@@ -3435,21 +3464,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")};`)
 ];
@@ -3461,7 +3498,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;
@@ -3476,14 +3513,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) {
@@ -3550,7 +3587,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,
     `}`,
@@ -3599,8 +3637,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 +3673,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 +3716,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 +3728,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)),
@@ -3878,7 +3909,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));
@@ -3968,8 +4000,10 @@ export {
   DEFAULT_LINK_HEX,
   DISABLED_OPACITY,
   EXT_KEY,
+  INTERACTION_RUNGS,
   MODE_SPECS,
   OFFSET_ALPHAS,
+  OPACITY_RUNGS,
   OUTLINE_HOVER_ALPHA,
   PAPER_0,
   PEN_100,
@@ -4003,6 +4037,10 @@ export {
   generateScale,
   generateSubtleSecondary,
   neutralCss,
+  neutralTintHue,
+  opacityLeafName,
+  opacityTokenPath,
+  opacityVarName,
   pageStopFor,
   parseToken,
   resolveBrand,

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

@@ -15,16 +15,16 @@ export interface CollisionCheck {
 }
 export declare function stopDeltaE(s1: ColorStop, s2: ColorStop): number;
 export declare function checkCollision(brand: GeneratedScale, signalScale: GeneratedScale, signalDef: SignalDef, mode: Mode): CollisionCheck;
-export declare const HUE_COLLISION_HIGHLIGHTER_DEG = 15;
+export declare const HUE_COLLISION_CHALK_DEG = 15;
 export declare const HUE_COLLISION_MIN_V = 0.5;
 export declare const SECONDARY_NOTE_MIN_V: number;
 export interface HueCollisionCheck {
     signal: SignalDef['name'];
-    dHueHighlighter: {
+    dHueChalk: {
         light: number;
         dark: number;
     };
-    highlighterDeltaE: {
+    chalkDeltaE: {
         light: number;
         dark: number;
     };

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

@@ -89,7 +89,7 @@ export interface GenerateOptions {
             H: number;
         };
     };
-    crossHighlighterBoundY?: {
+    crossChalkBoundY?: {
         light: number;
         dark: number;
     };

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

@@ -17,6 +17,21 @@ export declare const ctaBorderRung: (prefix: string) => OffsetRung;
 export declare const offsetLeafName: (rung: OffsetRung) => string;
 export declare const offsetVarName: (rung: OffsetRung) => string;
 export declare const offsetTokenPath: (rung: OffsetRung) => string;
+export declare const OPACITY_RUNGS: {
+    readonly 4: 0.04;
+    readonly 8: 0.08;
+    readonly 12: 0.12;
+    readonly 16: 0.16;
+    readonly 24: 0.24;
+    readonly 32: 0.32;
+    readonly 48: 0.48;
+    readonly 64: 0.64;
+};
+export type OpacityRung = keyof typeof OPACITY_RUNGS;
+export declare const INTERACTION_RUNGS: readonly OpacityRung[];
+export declare const opacityLeafName: (rung: OpacityRung) => string;
+export declare const opacityVarName: (rung: OpacityRung) => string;
+export declare const opacityTokenPath: (rung: OpacityRung) => string;
 export declare const SHADOW_ALPHAS: {
     readonly 4: {
         readonly light: 0.04;
@@ -32,14 +47,14 @@ export declare const SHADOW_ALPHAS: {
     };
 };
 export type ShadowRung = keyof typeof SHADOW_ALPHAS;
-export declare const SCRIM_ALPHA = 0.6;
+export declare const SCRIM_ALPHA: 0.64;
 export declare const DISABLED_OPACITY = 0.38;
 export declare const TRANSPARENT_VAR = "--alpha-transparent";
 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/engine/figmaRender.d.ts

@@ -9,11 +9,16 @@ export interface FigmaColorToken {
         hex: string;
     };
 }
+export interface FigmaNumberToken {
+    $type: 'number';
+    $value: number;
+}
+export type FigmaLeaf = FigmaColorToken | FigmaNumberToken;
 export type FigmaGroup = {
-    [key: string]: FigmaColorToken | FigmaGroup;
+    [key: string]: FigmaLeaf | FigmaGroup;
 };
-export declare function groupEntries(g: FigmaGroup): Array<[string, FigmaColorToken | FigmaGroup]>;
-export declare function putLeaf(g: FigmaGroup, flat: string, tok: FigmaColorToken): void;
+export declare function groupEntries(g: FigmaGroup): Array<[string, FigmaLeaf | FigmaGroup]>;
+export declare function putLeaf(g: FigmaGroup, flat: string, tok: FigmaLeaf): void;
 export interface ThemeInput {
     secondary?: GeneratedScale | null;
     secondaryStyle?: SecondaryStyle;

package/dist-lib/types/engine/requirements/spec.d.ts

@@ -1,5 +1,5 @@
 import { STAMP_FILL, STAMP_FILL_HOVER, STAMP_FILL_PRESSED } from '../tokenNames';
-export type Group = 'paper' | 'highlighter' | 'crayon' | 'pencil' | 'pen';
+export type Group = 'paper' | 'chalk' | 'highlighter' | 'pencil' | 'pen';
 export declare const textLane: (g: string) => boolean;
 export type Producer = {
     hue: 'warm-drift' | 'warm-torsion' | 'constant';
@@ -8,7 +8,7 @@ export type Producer = {
 };
 export type Require = {
     metric: 'wcag';
-    against: 'paper-1' | 'paper-3' | 'paper-5' | 'highlighter-20';
+    against: 'paper-1' | 'paper-3' | 'paper-5' | 'chalk-20';
     target: number;
     level: 'AA' | 'AAA';
 } | {

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

@@ -26,7 +26,6 @@ export declare const SYSTEM_LEAF: {
     };
     readonly ALPHA: {
         readonly TRANSPARENT: "system/alpha/transparent";
-        readonly SCRIM: "system/alpha/abs-black-060";
         readonly INK: "system/alpha/ink";
         readonly AWAY_FROM_BG_06: "system/alpha/away-from-bg/06";
         readonly AWAY_FROM_BG_08: "system/alpha/away-from-bg/08";
@@ -38,6 +37,7 @@ export declare const SYSTEM_LEAF: {
         readonly SHADOW_08: "system/alpha/shadow-08";
         readonly SHADOW_12: "system/alpha/shadow-12";
     };
+    readonly OPACITY: Record<string, string>;
 };
 export declare const SURFACE_PLANE_LAW: Record<string, {
     light: string;

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

@@ -1,8 +1,8 @@
-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, OPACITY_RUNGS, INTERACTION_RUNGS, opacityLeafName, opacityVarName, opacityTokenPath, type OpacityRung, 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 { themeToFigma, type FigmaGroup, type FigmaColorToken, type FigmaNumberToken, type FigmaLeaf, 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';
 export { stopTokenName, tokenOrder, SCALE_STOP_COUNT, PAPER_0, PEN_100, STAMP_FILL, STAMP_FILL_HOVER, STAMP_FILL_PRESSED, STAMP_EDGE, STAMP_ON, STAMP_STATE_LEAVES, SYSTEM_LEAF, SURFACE_PLANE_LAW, } from './engine/tokenNames';

package/package.json

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