okchroma 0.8.2 → 0.9.1

package/dist-lib/index.mjs

@@ -21,13 +21,13 @@ function stateStepL(restL, _mode, k) {
 }
 var OVERRIDE_LIGHT_BELOW = ARCHETYPES.find((a) => a.name === "rich").min;
 var OVERRIDE_DARK_ABOVE = ARCHETYPES.find((a) => a.name === "light").min;
-function stateFillL(restL, mode, k) {
+function stateFillL(restL, mode, k, keepsPole) {
   const natural = mode === "dark" ? 1 : -1;
   const overridden = mode === "light" ? restL < OVERRIDE_LIGHT_BELOW : restL > OVERRIDE_DARK_ABOVE;
   const preferred = overridden ? -natural : natural;
   const fits = (d) => {
     const p = restL + d * stateStepL(restL, mode, 2);
-    return p >= STATE_L_MIN && p <= STATE_L_MAX;
+    return p >= STATE_L_MIN && p <= STATE_L_MAX && (keepsPole?.(p) ?? true);
   };
   const dir = fits(preferred) ? preferred : fits(-preferred) ? -preferred : preferred;
   const L = restL + dir * stateStepL(restL, mode, k);
@@ -745,32 +745,20 @@ function stopTokenName(stop) {
 }
 var PAPER_0 = "paper-0";
 var PEN_100 = "pen-100";
-var STAMP_FILL = "stamp-fill";
-var STAMP_FILL_HOVER = "stamp-fill-hover";
-var STAMP_FILL_PRESSED = "stamp-fill-pressed";
+var STAMP_FILL = "stamp-0";
+var STAMP_FILL_HOVER = "stamp-1";
+var STAMP_FILL_PRESSED = "stamp-2";
 var STAMP_EDGE = "stamp-edge";
 var STAMP_ON = "stamp-on";
-var STAMP_STATE_LEAVES = {
-  [STAMP_FILL]: "stamp/fill",
-  [STAMP_FILL_HOVER]: "stamp/fill-hover",
-  [STAMP_FILL_PRESSED]: "stamp/fill-pressed",
-  [STAMP_EDGE]: "stamp/edge",
-  [STAMP_ON]: "stamp/on"
-};
-var STAMP_LEAF = {
-  FILL: STAMP_STATE_LEAVES[STAMP_FILL],
-  FILL_HOVER: STAMP_STATE_LEAVES[STAMP_FILL_HOVER],
-  FILL_PRESSED: STAMP_STATE_LEAVES[STAMP_FILL_PRESSED],
-  EDGE: STAMP_STATE_LEAVES[STAMP_EDGE],
-  ON: STAMP_STATE_LEAVES[STAMP_ON]
-};
 var cssVarName = (path) => `--${path.join("-")}`;
 var figmaPathOf = (path) => path.join("/");
-var familyPath = (family, leaf) => [family, ...(STAMP_STATE_LEAVES[leaf] ?? leaf).split("/")];
+var familyPath = (family, leaf) => [family, leaf];
 var LINK_GROUP = "link";
 var LINK_POSTURES = ["default", "inverse"];
 var LINK_STATES = ["enabled", "hover", "pressed"];
-var linkPath = (posture, state) => [LINK_GROUP, posture, state];
+var LINK_STEP = { enabled: 0, hover: 1, pressed: 2 };
+var linkLeaf = (posture, state) => `${posture}-${LINK_STEP[state]}`;
+var linkPath = (posture, state) => [LINK_GROUP, linkLeaf(posture, state)];
 var ABSOLUTE_GROUP = "absolute";
 var absolutePath = (family) => [ABSOLUTE_GROUP, family];
 var COLOR_GROUP = "color";
@@ -2143,6 +2131,20 @@ function ctaDarkDualGateL(base, darkH, onFillTextIsWhite, enforce, coLc, capLoL,
   const lLc = findLForBlackTextLc(startL, C2, darkH, coLc + APCA_SOLVE_MARGIN_LC, capHiL);
   return Math.max(l45, Math.min(lLc, capHiL));
 }
+function stepKeepsPole(mode, white, chromaAt, H2, law) {
+  if (mode === "light") return void 0;
+  if (law.enforceLc !== void 0) {
+    const bar = law.enforceLc;
+    const lcAt = white ? whiteTextLcAt : blackTextLcAt;
+    return (L) => lcAt(L, chromaAt(L), H2) >= bar;
+  }
+  if (law.ratioFloor === void 0) return void 0;
+  const floor = law.ratioFloor, poleY = white ? 1 : 0;
+  return (L) => {
+    const C2 = clampChromaToGamut(L, chromaAt(L), H2);
+    return Math.min(legalRatio(L, C2, H2, poleY), contrastRatio(shippedY(L, C2, H2), poleY)) >= floor;
+  };
+}
 function onFillIsWhiteDarkAt(L, C2, H2, enforce, ratioFloor) {
   return onTextIsWhite(apcaYAt(L, C2, H2), L, C2, H2, enforce, ratioFloor);
 }
@@ -2425,7 +2427,8 @@ function resolveRamp(hex, mode, spec, opts) {
   const enforceLc = spec.ons.onFill.enforceLc;
   const coLc = ctx.opts?.apcaClearance && enforceLc === void 0 ? ctx.opts.apcaClearanceLc ?? spec.ons.onFill.coEnforceLc : void 0;
   const onFloor = enforceLc !== void 0 ? void 0 : spec.ons.onFill.ratioFloor;
-  let cta, ctaHover, ctaPressed, onFillIsWhite;
+  let cta, onFillIsWhite;
+  let stateC, stateH;
   if (mode === "light") {
     onFillIsWhite = onFillIsWhiteLight(ctx, enforceLc !== void 0 ? false : onFillEnforce);
     let light9L = enforceLc !== void 0 ? ctaLightLApca(ctx, onFillIsWhite, onFillEnforce, enforceLc) : ctaLightL(ctx, onFillIsWhite, onFillEnforce);
@@ -2457,21 +2460,14 @@ function resolveRamp(hex, mode, spec, opts) {
       }
     }
     cta = emitRole(STAMP_FILL, light9L, ctaCFor(light9L) * ctaCMul, ctaH);
-    const hCFor = (L) => ctx.cAt("light", L, (hoverReq?.chromaMult ?? 1) * ctx.brandC) * ctaCMul;
-    const pCFor = (L) => ctx.cAt("light", L, (pressedReq?.chromaMult ?? 1) * ctx.brandC) * ctaCMul;
-    const hL = stateFillL(light9L, "light", 1);
-    const pL = stateFillL(light9L, "light", 2);
-    ctaHover = emitRole(STAMP_FILL_HOVER, hL, hCFor(hL), ctaH);
-    ctaPressed = emitRole(STAMP_FILL_PRESSED, pL, pCFor(pL), ctaH);
-    if (light9L !== ctx.scaleL) {
-      cta.enforced = true;
-      ctaHover.enforced = true;
-      ctaPressed.enforced = true;
-    }
+    stateC = {
+      hover: (L) => ctx.cAt("light", L, (hoverReq?.chromaMult ?? 1) * ctx.brandC) * ctaCMul,
+      pressed: (L) => ctx.cAt("light", L, (pressedReq?.chromaMult ?? 1) * ctx.brandC) * ctaCMul
+    };
+    stateH = ctaH;
+    if (light9L !== ctx.scaleL) cta.enforced = true;
     if (repelled) {
       cta.repelled = true;
-      ctaHover.repelled = true;
-      ctaPressed.repelled = true;
       onFillIsWhite = onFillIsWhiteDarkAt(
         cta.L,
         cta.C,
@@ -2484,50 +2480,29 @@ function resolveRamp(hex, mode, spec, opts) {
     const d = dctx;
     const cta9L = ctx.opts?.darkCtaFlatApp !== void 0 ? flatDarkCtaL(d, (L) => ctx.cAt("dark", L, d.darkC9), ctx.darkCtaH, ctx.opts.darkCtaFlatApp) : d.dark9L;
     const dCFor = (L) => ctx.cAt("dark", L, d.darkC9);
-    const dTrio = (baseL) => [stateFillL(baseL, "dark", 1), stateFillL(baseL, "dark", 2)];
+    stateC = { hover: dCFor, pressed: dCFor };
+    stateH = ctx.darkCtaH;
     cta = emitRole(STAMP_FILL, cta9L, dCFor(cta9L), ctx.darkCtaH);
-    {
-      const [hL, pL] = dTrio(cta9L);
-      ctaHover = emitRole(STAMP_FILL_HOVER, hL, dCFor(hL), ctx.darkCtaH);
-      ctaPressed = emitRole(STAMP_FILL_PRESSED, pL, dCFor(pL), ctx.darkCtaH);
-    }
     onFillIsWhite = onFillIsWhiteDarkAt(cta.L, cta.C, cta.H, enforceLc !== void 0 ? false : onFillEnforce);
     const enforcedL = enforceLc !== void 0 ? ctaDarkEnforcedLApca(ctx, cta, onFillIsWhite, onFillEnforce, enforceLc) : ctaDarkEnforcedL(ctx, cta, onFillIsWhite, onFillEnforce);
     if (enforcedL !== null) {
       cta = emitRole(STAMP_FILL, enforcedL, dCFor(enforcedL), ctx.darkCtaH);
-      const [hL, pL] = dTrio(enforcedL);
-      ctaHover = emitRole(STAMP_FILL_HOVER, hL, dCFor(hL), ctx.darkCtaH);
-      ctaPressed = emitRole(STAMP_FILL_PRESSED, pL, dCFor(pL), ctx.darkCtaH);
       cta.enforced = true;
-      ctaHover.enforced = true;
-      ctaPressed.enforced = true;
     }
     if (coLc !== void 0) {
       const [capLoL, capHiL] = CTA_CLEARANCE_CAPS;
       const clearedL = ctaDarkDualGateL(cta, ctx.darkCtaH, onFillIsWhite, onFillEnforce, coLc + APCA_ENFORCE_MARGIN_LC, capLoL, capHiL);
       if (Math.abs(clearedL - cta.L) > 1e-9) {
         cta = emitRole(STAMP_FILL, clearedL, dCFor(clearedL), ctx.darkCtaH);
-        const [hL, pL] = dTrio(clearedL);
-        ctaHover = emitRole(STAMP_FILL_HOVER, hL, dCFor(hL), ctx.darkCtaH);
-        ctaPressed = emitRole(STAMP_FILL_PRESSED, pL, dCFor(pL), ctx.darkCtaH);
         cta.enforced = true;
-        ctaHover.enforced = true;
-        ctaPressed.enforced = true;
       }
     }
     if (ctx.opts?.ctaSolve) {
       const exitL = solveDarkCtaExit(cta, dCFor, ctx.darkCtaH, ctx.opts.ctaSolve.redDark, enforceLc, coLc);
       if (exitL !== null) {
         cta = emitRole(STAMP_FILL, exitL, dCFor(exitL), ctx.darkCtaH);
-        const [hL, pL] = dTrio(exitL);
-        ctaHover = emitRole(STAMP_FILL_HOVER, hL, dCFor(hL), ctx.darkCtaH);
-        ctaPressed = emitRole(STAMP_FILL_PRESSED, pL, dCFor(pL), ctx.darkCtaH);
         cta.enforced = true;
-        ctaHover.enforced = true;
-        ctaPressed.enforced = true;
         cta.repelled = true;
-        ctaHover.repelled = true;
-        ctaPressed.repelled = true;
         onFillIsWhite = onFillIsWhiteDarkAt(
           cta.L,
           cta.C,
@@ -2543,6 +2518,19 @@ function resolveRamp(hex, mode, spec, opts) {
     const other = legalRatio(cta.L, cta.C, cta.H, onFillIsWhite ? 0 : 1);
     if (chosen < onFloor && other >= onFloor) onFillIsWhite = !onFillIsWhite;
   }
+  const keepsPole = stepKeepsPole(mode, onFillIsWhite, stateC.pressed, stateH, { ratioFloor: onFloor, enforceLc });
+  const hL = stateFillL(cta.L, mode, 1, keepsPole);
+  const pL = stateFillL(cta.L, mode, 2, keepsPole);
+  const ctaHover = emitRole(STAMP_FILL_HOVER, hL, stateC.hover(hL), stateH);
+  const ctaPressed = emitRole(STAMP_FILL_PRESSED, pL, stateC.pressed(pL), stateH);
+  if (cta.enforced) {
+    ctaHover.enforced = true;
+    ctaPressed.enforced = true;
+  }
+  if (cta.repelled) {
+    ctaHover.repelled = true;
+    ctaPressed.repelled = true;
+  }
   return { mode, seed, stops, roles: { cta, ctaHover, ctaPressed }, ons: { onFillIsWhite } };
 }
 
@@ -2625,18 +2613,18 @@ function generateNeutralScale(brandH, level = "default", contrastProfile) {
   if (popLift > 1e-6) {
     scale.ctaDark = makeStop(9, scale.dark[3].L + popLift, scale.dark[3].C, scale.dark[3].H);
   }
-  const nState = (stop, mode, rest, k) => {
-    const L = stateFillL(rest.L, mode, k);
-    return makeStop(stop, L, curve(L, mode), rest.H);
-  };
-  scale.ctaHover = nState(10, "light", scale.cta, 1);
-  scale.ctaPressed = nState(11, "light", scale.cta, 2);
-  scale.ctaHoverDark = nState(10, "dark", scale.ctaDark, 1);
-  scale.ctaPressedDark = nState(11, "dark", scale.ctaDark, 2);
   const onEnforce = contrastProfile !== "apca";
   const onFloor = 4.5;
   scale.onFillTextIsWhite = onTextIsWhite(apcaY(scale.cta.r, scale.cta.g, scale.cta.b), scale.cta.L, scale.cta.C, scale.cta.H, onEnforce, onFloor);
   scale.onFillTextIsWhiteDark = onTextIsWhite(apcaY(scale.ctaDark.r, scale.ctaDark.g, scale.ctaDark.b), scale.ctaDark.L, scale.ctaDark.C, scale.ctaDark.H, onEnforce, onFloor);
+  const nState = (stop, mode, rest, k, white) => {
+    const L = stateFillL(rest.L, mode, k, stepKeepsPole(mode, white, (l) => curve(l, mode), rest.H, { ratioFloor: onFloor }));
+    return makeStop(stop, L, curve(L, mode), rest.H);
+  };
+  scale.ctaHover = nState(10, "light", scale.cta, 1, scale.onFillTextIsWhite);
+  scale.ctaPressed = nState(11, "light", scale.cta, 2, scale.onFillTextIsWhite);
+  scale.ctaHoverDark = nState(10, "dark", scale.ctaDark, 1, scale.onFillTextIsWhiteDark);
+  scale.ctaPressedDark = nState(11, "dark", scale.ctaDark, 2, scale.onFillTextIsWhiteDark);
   return scale;
 }
 function generateSubtleSecondary(hex, opts) {
@@ -2649,10 +2637,6 @@ function generateSubtleSecondary(hex, opts) {
   });
   const asCta = (stop, src) => makeStop(stop, src.L, src.C, src.H);
   const mk = (stop, L, mode) => makeStop(stop, L, curve(L, mode), scale.brandH);
-  const st = (stop, mode, rest, k) => {
-    const L = stateFillL(rest.L, mode, k);
-    return makeStop(stop, L, curve(L, mode), rest.H);
-  };
   if (opts?.ctaL) {
     scale.cta = mk(9, opts.ctaL.light, "light");
     scale.ctaDark = mk(9, opts.ctaL.dark, "dark");
@@ -2660,14 +2644,18 @@ function generateSubtleSecondary(hex, opts) {
     scale.cta = asCta(9, scale.light[3]);
     scale.ctaDark = asCta(9, scale.dark[3]);
   }
-  scale.ctaHover = st(10, "light", scale.cta, 1);
-  scale.ctaPressed = st(11, "light", scale.cta, 2);
-  scale.ctaHoverDark = st(10, "dark", scale.ctaDark, 1);
-  scale.ctaPressedDark = st(11, "dark", scale.ctaDark, 2);
   const onEnforce = opts?.contrastProfile !== "apca";
   const onFloor = 4.5;
   scale.onFillTextIsWhite = onTextIsWhite(apcaY(scale.cta.r, scale.cta.g, scale.cta.b), scale.cta.L, scale.cta.C, scale.cta.H, onEnforce, onFloor);
   scale.onFillTextIsWhiteDark = onTextIsWhite(apcaY(scale.ctaDark.r, scale.ctaDark.g, scale.ctaDark.b), scale.ctaDark.L, scale.ctaDark.C, scale.ctaDark.H, onEnforce, onFloor);
+  const st = (stop, mode, rest, k, white) => {
+    const L = stateFillL(rest.L, mode, k, stepKeepsPole(mode, white, (l) => curve(l, mode), rest.H, { ratioFloor: onFloor }));
+    return makeStop(stop, L, curve(L, mode), rest.H);
+  };
+  scale.ctaHover = st(10, "light", scale.cta, 1, scale.onFillTextIsWhite);
+  scale.ctaPressed = st(11, "light", scale.cta, 2, scale.onFillTextIsWhite);
+  scale.ctaHoverDark = st(10, "dark", scale.ctaDark, 1, scale.onFillTextIsWhiteDark);
+  scale.ctaPressedDark = st(11, "dark", scale.ctaDark, 2, scale.onFillTextIsWhiteDark);
   return scale;
 }
 
@@ -2761,20 +2749,21 @@ var SCALE = {
   // ("heavy-emphasis": "high" and "low" are plane words in the community plugin and
   // "strong" carries "on")
   "pen-70": { req: "heavy-emphasis text, inverted backgrounds", contrast: AA_BODY, claim: claimOf("pen"), theming: solved, collides: true },
-  // the stamp family. "CTA" stays in these bodies on purpose: it is not a token label, so
+  // the stamp rows, each a position: the fill at rest and at one and two steps, the edge,
+  // the on-text. No body names a state; a consumer's semantic layer names the states and
+  // aliases the steps. "CTA" stays in these bodies on purpose: it is not a token label, so
   // it floods nothing, and a designer's "cta" query lands on these rows.
   // the usage lines are the owner's guidance, for the document rendering: the fill is
   // misused as a standalone color in the wild
-  "stamp/fill": {
-    req: "CTAs",
+  "stamp-0": {
+    req: "CTAs, the fill at rest",
     theming: (f) => `fully re-solved per theme and family${COLOR_WORD[f]}`,
-    use: "primary button fills; optional for avatars, badges and other elements that carry text. Not a standalone color: it has no contrast guarantee of its own, only its on-text has one. Use it alone or with its hover and pressed states. Always bordered with its edge"
+    use: "primary button fills; optional for avatars, badges and other elements that carry text. Not a standalone color: it has no contrast guarantee of its own, only its on-text has one. Use it alone or with the two steps above it. Always bordered with its edge"
   },
-  "stamp/fill-hover": { req: "CTA pointer-over state", theming: (f) => `follows its rest fill${COLOR_WORD[f]}`, use: "the pointer-over state of the fill, with the fill; for nothing else. Always bordered with the edge" },
-  "stamp/fill-pressed": { req: "CTA pressed state", theming: (f) => `follows its rest fill${COLOR_WORD[f]}`, use: "the pressed state of the fill, with the fill; for nothing else. Always bordered with the edge" },
-  "stamp/edge": { req: "min APCA visibility", theming: (f) => `draws for CTAs that sit close to the page; strength per family tier${COLOR_WORD[f]}`, use: "the border of the fill and its states, always rendered with them and never without them (it resolves to transparent unless the fill sits close to the page); for nothing else" },
-  // ("fill" is a label word and foreign here)
-  "stamp/on": { req: "text over the CTA color", contrast: `${AA_BODY} over its CTA`, theming: (f) => `whichever pole passes; quiet CTAs take the soft pole${COLOR_WORD[f]}`, use: "the only text color over the fill; never elsewhere" }
+  "stamp-1": { req: "CTAs, the fill one step from rest", theming: (f) => `follows the fill at rest${COLOR_WORD[f]}`, use: "the fill one step from rest, with the fill at rest; for nothing else. Always bordered with the edge" },
+  "stamp-2": { req: "CTAs, the fill two steps from rest", theming: (f) => `follows the fill at rest${COLOR_WORD[f]}`, use: "the fill two steps from rest, with the fill at rest; for nothing else. Always bordered with the edge" },
+  "stamp-edge": { req: "min APCA visibility", theming: (f) => `draws for CTAs that sit close to the page; strength per family tier${COLOR_WORD[f]}`, use: "the border of the fill at every step, always rendered with it and never without it (it resolves to transparent unless the fill sits close to the page); for nothing else" },
+  "stamp-on": { req: "text over the CTA color", contrast: `${AA_BODY} over its CTA`, theming: (f) => `whichever pole passes; quiet CTAs take the soft pole${COLOR_WORD[f]}`, use: "the only text color over the fill at every step; never elsewhere" }
 };
 var NEUTRAL_ONLY = {
   // the pole is measured against the neutral's own stops only; as text, it is the on-color
@@ -2783,15 +2772,15 @@ var NEUTRAL_ONLY = {
   // the literal pole carries no tint, so no theming line
   "pen-100": { req: "max-emphasis text", contrast: AA_BODY, claim: () => `${AA_BODY} on every paper and chalk of every family` }
 };
-var LINK = (state, contrast) => ({
-  req: "links" + state,
+var LINK = (step, contrast) => ({
+  req: "links" + step,
   contrast,
   claim: () => `${contrast} on every paper of the neutral`,
   theming: "rides the theme\u2019s link color; custom seed re-solves; overridable per theme",
   use: "hyperlinks; not a text-style CTA, which is the text stops read as states"
 });
-var LINK_INVERSE = (state, contrast) => ({
-  req: "links over inverted backgrounds" + state,
+var LINK_INVERSE = (step, contrast) => ({
+  req: "links over inverted backgrounds" + step,
   contrast,
   claim: () => `${contrast} on any family's pen-70`,
   theming: "same seed as the link, re-solved for inverted backgrounds; overridable per theme",
@@ -2800,12 +2789,12 @@ var LINK_INVERSE = (state, contrast) => ({
 var SYSTEM = {
   "absolute/brand": { req: "identity seed reference", theming: "the theme\u2019s own input, as given", use: "a reference value (logos, swatches of the input); never a UI color, it carries no contrast guarantee" },
   "absolute/brand-alt": { req: "identity seed reference", theming: "the theme\u2019s paired input, as given", use: "a reference value (logos, swatches of the input); never a UI color, it carries no contrast guarantee" },
-  "link/default/enabled": LINK("", AA_BODY),
-  "link/default/hover": LINK(" pointer-over", AA_BODY),
-  "link/default/pressed": LINK(" pressed", AA_BODY),
-  "link/inverse/enabled": LINK_INVERSE("", AA_BODY),
-  "link/inverse/hover": LINK_INVERSE(" pointer-over", AA_BODY),
-  "link/inverse/pressed": LINK_INVERSE(" pressed", AA_BODY)
+  "link/default-0": LINK("", AA_BODY),
+  "link/default-1": LINK(", one step from rest", AA_BODY),
+  "link/default-2": LINK(", two steps from rest", AA_BODY),
+  "link/inverse-0": LINK_INVERSE("", AA_BODY),
+  "link/inverse-1": LINK_INVERSE(", one step from rest", AA_BODY),
+  "link/inverse-2": LINK_INVERSE(", two steps from rest", AA_BODY)
 };
 var PREFIXES = [
   // community spellings first: the family word is a prefix of the community shapes
@@ -3242,11 +3231,12 @@ function escapeCtaFamily(nScale, mode, contrastProfile) {
   if (!strongText) throw new Error("escapeCtaFamily: the neutral scale has no ink-11 stop");
   const mk = (stop, L) => makeStop(stop, L, strongText.C, strongText.H);
   const cta = mk(9, strongText.L);
-  const ctaHover = mk(10, stateFillL(strongText.L, mode, 1));
-  const ctaPressed = mk(11, stateFillL(strongText.L, mode, 2));
   const onEnforce = contrastProfile !== "apca";
   const onFloor = contrastProfile === "apca" ? void 0 : 4.5;
   const onFillIsWhite = onTextIsWhite(apcaY(cta.r, cta.g, cta.b), cta.L, cta.C, cta.H, onEnforce, onFloor);
+  const keepsPole = stepKeepsPole(mode, onFillIsWhite, () => strongText.C, strongText.H, { ratioFloor: onFloor });
+  const ctaHover = mk(10, stateFillL(strongText.L, mode, 1, keepsPole));
+  const ctaPressed = mk(11, stateFillL(strongText.L, mode, 2, keepsPole));
   return { cta, ctaHover, ctaPressed, onFillIsWhite };
 }
 var SECONDARY_DISTINCT_DELTA_E = 0.12;
@@ -3796,9 +3786,6 @@ function colorFromHexString(hex) {
   const h = hex.replace("#", "");
   return color(parseInt(h.slice(0, 2), 16) / 255, parseInt(h.slice(2, 4), 16) / 255, parseInt(h.slice(4, 6), 16) / 255);
 }
-function bandedLeaf(flat) {
-  return STAMP_STATE_LEAVES[flat] ?? flat;
-}
 function groupEntries(g2) {
   const entries = Object.entries(g2);
   const digitLeading = (k) => /^\d/.test(k);
@@ -3806,24 +3793,15 @@ function groupEntries(g2) {
     return entries.sort((a, b) => parseInt(b[0], 10) - parseInt(a[0], 10));
   return entries;
 }
-function putLeaf(g2, flat, tok) {
-  const path = bandedLeaf(flat).split("/");
-  let cur = g2;
-  for (const seg of path.slice(0, -1)) {
-    if (!(seg in cur) || "$type" in cur[seg]) cur[seg] = {};
-    cur = cur[seg];
-  }
-  cur[path[path.length - 1]] = tok;
-}
 function rampGroup(stops, onFillWhite, extra) {
   const g2 = {};
   const leaves = stops.map((s) => ({ name: stopTokenName(s.stop), tok: colorFromStop(s) })).sort((a, b) => tokenOrder(a.name) - tokenOrder(b.name));
-  for (const l of leaves) putLeaf(g2, l.name, l.tok);
-  if (extra?.cta) putLeaf(g2, STAMP_FILL, colorFromStop(extra.cta));
-  if (extra?.ctaHover) putLeaf(g2, STAMP_FILL_HOVER, colorFromStop(extra.ctaHover));
-  if (extra?.ctaPressed) putLeaf(g2, STAMP_FILL_PRESSED, colorFromStop(extra.ctaPressed));
-  if (extra?.cta) putLeaf(g2, STAMP_EDGE, extra.ctaBorder ?? TRANSPARENT_TOKEN);
-  putLeaf(g2, STAMP_ON, pole(onFillWhite));
+  for (const l of leaves) g2[l.name] = l.tok;
+  if (extra?.cta) g2[STAMP_FILL] = colorFromStop(extra.cta);
+  if (extra?.ctaHover) g2[STAMP_FILL_HOVER] = colorFromStop(extra.ctaHover);
+  if (extra?.ctaPressed) g2[STAMP_FILL_PRESSED] = colorFromStop(extra.ctaPressed);
+  if (extra?.cta) g2[STAMP_EDGE] = extra.ctaBorder ?? TRANSPARENT_TOKEN;
+  g2[STAMP_ON] = pole(onFillWhite);
   return g2;
 }
 function themeToFigma(r, input) {
@@ -3862,16 +3840,18 @@ function themeToFigma(r, input) {
     if (input.secondaryStyle === "outline" && input.secondary) {
       const s8 = secondary[mode].find((s) => s.stop === 8);
       const s9 = secondary[mode].find((s) => s.stop === 9);
-      putLeaf(secondaryGroup, STAMP_FILL, TRANSPARENT_TOKEN);
+      secondaryGroup[STAMP_FILL] = TRANSPARENT_TOKEN;
       if (s8) {
         const e = srgbEmitChannels(s8);
-        putLeaf(secondaryGroup, STAMP_FILL_HOVER, color(e.r, e.g, e.b, OUTLINE_HOVER_ALPHA));
-        putLeaf(secondaryGroup, STAMP_FILL_PRESSED, color(e.r, e.g, e.b, OUTLINE_PRESSED_ALPHA));
-        putLeaf(secondaryGroup, STAMP_EDGE, colorFromStop(s8));
+        secondaryGroup[STAMP_FILL_HOVER] = color(e.r, e.g, e.b, OUTLINE_HOVER_ALPHA);
+        secondaryGroup[STAMP_FILL_PRESSED] = color(e.r, e.g, e.b, OUTLINE_PRESSED_ALPHA);
+        secondaryGroup[STAMP_EDGE] = colorFromStop(s8);
       }
-      if (s9) putLeaf(secondaryGroup, STAMP_ON, colorFromStop(s9));
+      if (s9) secondaryGroup[STAMP_ON] = colorFromStop(s9);
     }
-    const softOnCta = (g3, white) => putLeaf(g3, STAMP_ON, pole(white, SOFT_ON_CTA_ALPHA[mode]));
+    const softOnCta = (g3, white) => {
+      g3[STAMP_ON] = pole(white, SOFT_ON_CTA_ALPHA[mode]);
+    };
     softOnCta(neutralGroup, mode === "light" ? nScale.onFillTextIsWhite : nScale.onFillTextIsWhiteDark);
     if (input.secondary && input.secondaryStyle !== "outline" && softOnCtaPasses(input.secondary, mode))
       softOnCta(secondaryGroup, mode === "light" ? secondaryOnFillLight : secondaryOnFillDark);
@@ -3879,10 +3859,10 @@ function themeToFigma(r, input) {
     const esc = input.ctaEscape ? escapeCtaFamily(nScale, mode, input.contrastProfile) : null;
     if (esc) {
       for (const g3 of input.secondary ? [brandGroup] : [brandGroup, secondaryGroup]) {
-        putLeaf(g3, STAMP_FILL, colorFromStop(esc.cta));
-        putLeaf(g3, STAMP_FILL_HOVER, colorFromStop(esc.ctaHover));
-        putLeaf(g3, STAMP_FILL_PRESSED, colorFromStop(esc.ctaPressed));
-        putLeaf(g3, STAMP_ON, pole(esc.onFillIsWhite));
+        g3[STAMP_FILL] = colorFromStop(esc.cta);
+        g3[STAMP_FILL_HOVER] = colorFromStop(esc.ctaHover);
+        g3[STAMP_FILL_PRESSED] = colorFromStop(esc.ctaPressed);
+        g3[STAMP_ON] = pole(esc.onFillIsWhite);
       }
     }
     const scaleTextAt = (n) => {
@@ -3892,7 +3872,7 @@ function themeToFigma(r, input) {
     };
     const trio = (posture) => {
       const t = posture === "default" ? lt ? mode === "light" ? [lt.link, lt.linkHover, lt.linkPressed] : [lt.linkDark, lt.linkHoverDark, lt.linkPressedDark] : [scaleTextAt(9), scaleTextAt(10), scaleTextAt(11)] : mode === "light" ? [invLt.link, invLt.linkHover, invLt.linkPressed] : [invLt.linkDark, invLt.linkHoverDark, invLt.linkPressedDark];
-      return Object.fromEntries(LINK_STATES.map((state, i) => [state, colorFromStop(t[i])]));
+      return Object.fromEntries(LINK_STATES.map((state, i) => [linkLeaf(posture, state), colorFromStop(t[i])]));
     };
     const g2 = {
       [CSS_FAMILY.neutral]: neutralGroup,
@@ -3907,7 +3887,7 @@ function themeToFigma(r, input) {
         ctaFamily(sig.scale, mode, role)
       );
     }
-    g2[LINK_GROUP] = { default: trio("default"), inverse: trio("inverse") };
+    g2[LINK_GROUP] = { ...trio("default"), ...trio("inverse") };
     g2[ABSOLUTE_GROUP] = {
       [CSS_FAMILY.brandPrimary]: colorFromHexString(scale.identityHex ?? invSeed),
       [CSS_FAMILY.brandSecondary]: colorFromHexString((input.secondary ?? scale).identityHex ?? invSeed)
@@ -4008,6 +3988,7 @@ export {
   LINK_GROUP,
   LINK_POSTURES,
   LINK_STATES,
+  LINK_STEP,
   MODE_SPECS,
   OFFSET_ALPHAS,
   OUTLINE_HOVER_ALPHA,
@@ -4022,9 +4003,7 @@ export {
   STAMP_FILL,
   STAMP_FILL_HOVER,
   STAMP_FILL_PRESSED,
-  STAMP_LEAF,
   STAMP_ON,
-  STAMP_STATE_LEAVES,
   SUBTLE_PASTEL_K,
   SUBTLE_TINT_MULT,
   absolutePath,
@@ -4045,6 +4024,7 @@ export {
   generateScale,
   generateSubtleSecondary,
   groupEntries,
+  linkLeaf,
   linkPath,
   neutralCss,
   neutralTintHue,

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

@@ -10,4 +10,4 @@ export declare function medianLForArchetype(archetype: Archetype): number;
 export declare function hoverL(L: number): number;
 export declare function pressedL(L: number): number;
 export declare function stateStepL(restL: number, _mode: 'light' | 'dark', k: 1 | 2): number;
-export declare function stateFillL(restL: number, mode: 'light' | 'dark', k: 1 | 2): number;
+export declare function stateFillL(restL: number, mode: 'light' | 'dark', k: 1 | 2, keepsPole?: (L: number) => boolean): number;

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

@@ -18,11 +18,11 @@ export type DtcgGroup = {
 export type DtcgDocument = DtcgGroup;
 /**
  * Every primitive's path, in document order: the neutral with its poles, the brand, the
- * alt, the four signals by role, the link trios, the seed absolutes. This roster is the
+ * alt, the four signals by role, the link rows, the seed absolutes. This roster is the
  * definition of what the engine emits; the emitters and the audit ride it.
  */
 export declare function tokenPaths(): TokenPath[];
-/** the path of a structured-emit name (`brand-stamp-fill`), or undefined when it is not a primitive */
+/** the path of a structured-emit name (`brand-stamp-0`), or undefined when it is not a primitive */
 export declare function tokenPathOf(name: string): TokenPath | undefined;
 /** the description key of a structured-emit name: its slash-joined path */
 export declare function descriptionPathOf(name: string): string | undefined;

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

@@ -14,7 +14,6 @@ export type FigmaGroup = {
     [key: string]: FigmaLeaf | FigmaGroup;
 };
 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/producers.d.ts

@@ -133,6 +133,10 @@ export declare function ctaDarkDualGateL(base: {
     L: number;
     C: number;
 }, darkH: number, onFillTextIsWhite: boolean, enforce: boolean, coLc: number, capLoL: number, capHiL: number): number;
+export declare function stepKeepsPole(mode: 'light' | 'dark', white: boolean, chromaAt: (L: number) => number, H: number, law: {
+    ratioFloor?: number;
+    enforceLc?: number;
+}): ((L: number) => boolean) | undefined;
 export declare function onFillIsWhiteDarkAt(L: number, C: number, H: number, enforce: boolean, ratioFloor?: number): boolean;
 export interface BrandExitLanding {
     L: number;

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

@@ -2,29 +2,25 @@ export declare const SCALE_STOP_COUNT: number;
 export declare function stopTokenName(stop: number): string;
 export declare const PAPER_0 = "paper-0";
 export declare const PEN_100 = "pen-100";
-export declare const STAMP_FILL = "stamp-fill";
-export declare const STAMP_FILL_HOVER = "stamp-fill-hover";
-export declare const STAMP_FILL_PRESSED = "stamp-fill-pressed";
+export declare const STAMP_FILL = "stamp-0";
+export declare const STAMP_FILL_HOVER = "stamp-1";
+export declare const STAMP_FILL_PRESSED = "stamp-2";
 export declare const STAMP_EDGE = "stamp-edge";
 export declare const STAMP_ON = "stamp-on";
-export declare const STAMP_STATE_LEAVES: Record<string, string>;
-export declare const STAMP_LEAF: {
-    readonly FILL: string;
-    readonly FILL_HOVER: string;
-    readonly FILL_PRESSED: string;
-    readonly EDGE: string;
-    readonly ON: string;
-};
 export type TokenPath = readonly string[];
 export declare const cssVarName: (path: TokenPath) => string;
 export declare const figmaPathOf: (path: TokenPath) => string;
-/** a family row: a scale stop, a pole, or a stamp token (nested under stamp/) */
+/** a family row: a scale stop, a pole, or a stamp row, flat in the family group */
 export declare const familyPath: (family: string, leaf: string) => string[];
 export declare const LINK_GROUP = "link";
 export declare const LINK_POSTURES: readonly ["default", "inverse"];
 export type LinkPosture = (typeof LINK_POSTURES)[number];
 export declare const LINK_STATES: readonly ["enabled", "hover", "pressed"];
 export type LinkState = (typeof LINK_STATES)[number];
+/** the step each state is emitted as: rest 0, one step 1, two steps 2 */
+export declare const LINK_STEP: Record<LinkState, number>;
+/** the one word a link row has: its posture at its step (`default-1`) */
+export declare const linkLeaf: (posture: LinkPosture, state: LinkState) => string;
 export declare const linkPath: (posture: LinkPosture, state: LinkState) => string[];
 export declare const ABSOLUTE_GROUP = "absolute";
 export declare const absolutePath: (family: string) => string[];

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

@@ -6,7 +6,7 @@ export { themeTokens, tokensFromEmission, readEmission, resolveReferences, type
 export { themeToFigma, groupEntries, type FigmaGroup, type FigmaColorToken, type FigmaLeaf, type ThemeInput, } from './engine/figmaRender';
 export { tokensToDtcg, tokenPathOf, descriptionPathOf, type DtcgDocument, type DtcgGroup, type DtcgToken, type DtcgColorValue, type DtcgOptions, } from './engine/dtcgRender';
 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, STAMP_LEAF, cssVarName, figmaPathOf, familyPath, linkPath, absolutePath, LINK_GROUP, LINK_POSTURES, LINK_STATES, ABSOLUTE_GROUP, COLOR_GROUP, type TokenPath, type LinkPosture, type LinkState, } from './engine/tokenNames';
+export { stopTokenName, tokenOrder, SCALE_STOP_COUNT, PAPER_0, PEN_100, STAMP_FILL, STAMP_FILL_HOVER, STAMP_FILL_PRESSED, STAMP_EDGE, STAMP_ON, cssVarName, figmaPathOf, familyPath, linkLeaf, linkPath, LINK_STEP, absolutePath, LINK_GROUP, LINK_POSTURES, LINK_STATES, ABSOLUTE_GROUP, COLOR_GROUP, type TokenPath, type LinkPosture, type LinkState, } from './engine/tokenNames';
 export { SIGNAL_EMIT_NAME } from './engine/signals';
 export { classifyArchetype, type Archetype } from './engine/archetypes';
 export { SIGNALS, type SignalDef } from './engine/signals';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "okchroma",
-  "version": "0.8.2",
+  "version": "0.9.1",
   "license": "MIT",
   "description": "Color-system engine: one brand hex in, a light and dark set of color primitives out, with the contrast requirements solved during generation; emitted as CSS custom properties, DTCG documents, and Figma variables",
   "repository": {