okchroma 0.8.2 → 0.9.0

package/README.md

@@ -7,7 +7,7 @@ variables, every token spelled the same way in each.
 
 Every family (neutral, brand, brand-alt, critical, warning, positive, info) carries 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
+solid fill at rest and at one and two steps, its edge, and its text). The neutral adds
 the two poles. Two link trios and the two brand seeds complete the set. Light and dark
 resolve together and ship on the same names, so a token is mapped once and holds for any
 brand.
@@ -60,18 +60,21 @@ example: [Install and API](https://egerrity.github.io/okchroma/#/docs/install).
 
 ## What it emits
 
-Every token has one path, and every output spells it: `brand/stamp/fill`,
-`neutral/paper-0`, `link/default/enabled`, `absolute/brand`. Joined with hyphens it is the
-CSS custom property (`--brand-stamp-fill`); joined with slashes it is the Figma variable
-and the DTCG token path. A consumer whose paths start with the category puts a `color`
-group in front: the extended plugin writes `color/brand/stamp/fill`, and the DTCG
-documents nest under the same word when asked. The CSS names never carry it.
+Every token has one path, and every output spells it: `brand/stamp-0`,
+`neutral/paper-0`, `link/default-0`, `absolute/brand`. A path is a group and one word, and
+the word is a position: a band at a lightness, the stamp at a step, a link posture at a
+step. No name carries a state word; a semantic layer names the states and aliases the
+steps. Joined with hyphens the path is the CSS custom property (`--brand-stamp-0`); joined
+with slashes it is the Figma variable and the DTCG token path. A consumer whose paths
+start with the category puts a `color` group in front: the extended plugin writes
+`color/brand/stamp-0`, and the DTCG documents nest under the same word when asked. The
+CSS names never carry it.
 
 | Group | Tokens |
 |---|---|
-| `neutral` | `paper-0`, `paper-1`, `paper-3`, `paper-5`, `chalk-8`, `chalk-11`, `chalk-15`, `chalk-20`, `highlighter-26`, `pencil-47`, `pen-58`, `pen-70`, `pen-100`, and the stamp: `stamp/fill`, `stamp/fill-hover`, `stamp/fill-pressed`, `stamp/edge`, `stamp/on` |
+| `neutral` | `paper-0`, `paper-1`, `paper-3`, `paper-5`, `chalk-8`, `chalk-11`, `chalk-15`, `chalk-20`, `highlighter-26`, `pencil-47`, `pen-58`, `pen-70`, `pen-100`, and the stamp: `stamp-0`, `stamp-1`, `stamp-2`, `stamp-edge`, `stamp-on` |
 | `brand`, `brand-alt`, `critical`, `warning`, `positive`, `info` | the same eleven stops and the same five stamp tokens |
-| `link` | `default/enabled`, `default/hover`, `default/pressed` for text on the papers; `inverse/enabled`, `inverse/hover`, `inverse/pressed` for text on the pen ground |
+| `link` | `default-0`, `default-1`, `default-2` for text on the papers; `inverse-0`, `inverse-1`, `inverse-2` for text on the pen ground; the link at rest, one step from rest, two steps |
 | `absolute` | `brand`, `brand-alt`: the seeds as given, reference values |
 
 What each name means, which stop to read for which job, and the rules for an agent
@@ -84,9 +87,10 @@ borders and illustration, never text; the highlighter is the non-text contrast s
 rings, icons, large text, and the one stop to build translucent state layers on); the
 pencil and the pens are text, and the pencil doubles as the emphasis fill.
 
-**The stamp.** `stamp/fill` is the call-to-action fill, re-solved per family and theme;
-`fill-hover` and `fill-pressed` are its states; `stamp/on` is the text over it, the pole
-that passes (the pole at alpha on a quiet fill); `stamp/edge` is a stroke that resolves to
+**The stamp.** `stamp-0` is the call-to-action fill at rest, re-solved per family and
+theme; `stamp-1` and `stamp-2` are the fill one and two steps from rest, one apparent step
+each; `stamp-on` is the text over it, the pole that passes (the pole at alpha on a quiet
+fill); `stamp-edge` is a stroke that resolves to
 a visible offset only where the fill sits close to the page, else transparent, so a
 component renders the border unconditionally and layout never shifts.
 

package/dist-lib/index.cjs

@@ -29,6 +29,7 @@ __export(index_exports, {
   LINK_GROUP: () => LINK_GROUP,
   LINK_POSTURES: () => LINK_POSTURES,
   LINK_STATES: () => LINK_STATES,
+  LINK_STEP: () => LINK_STEP,
   MODE_SPECS: () => MODE_SPECS,
   OFFSET_ALPHAS: () => OFFSET_ALPHAS,
   OUTLINE_HOVER_ALPHA: () => OUTLINE_HOVER_ALPHA,
@@ -43,9 +44,7 @@ __export(index_exports, {
   STAMP_FILL: () => STAMP_FILL,
   STAMP_FILL_HOVER: () => STAMP_FILL_HOVER,
   STAMP_FILL_PRESSED: () => STAMP_FILL_PRESSED,
-  STAMP_LEAF: () => STAMP_LEAF,
   STAMP_ON: () => STAMP_ON,
-  STAMP_STATE_LEAVES: () => STAMP_STATE_LEAVES,
   SUBTLE_PASTEL_K: () => SUBTLE_PASTEL_K,
   SUBTLE_TINT_MULT: () => SUBTLE_TINT_MULT,
   absolutePath: () => absolutePath,
@@ -66,6 +65,7 @@ __export(index_exports, {
   generateScale: () => generateScale,
   generateSubtleSecondary: () => generateSubtleSecondary,
   groupEntries: () => groupEntries,
+  linkLeaf: () => linkLeaf,
   linkPath: () => linkPath,
   neutralCss: () => neutralCss,
   neutralTintHue: () => neutralTintHue,
@@ -838,32 +838,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";
@@ -2854,20 +2842,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
@@ -2876,15 +2865,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",
@@ -2893,12 +2882,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
@@ -3889,9 +3878,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);
@@ -3899,24 +3885,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) {
@@ -3955,16 +3932,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);
@@ -3972,10 +3951,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) => {
@@ -3985,7 +3964,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,
@@ -4000,7 +3979,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)

package/dist-lib/index.mjs

@@ -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";
@@ -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
@@ -3796,9 +3785,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 +3792,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 +3839,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 +3858,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 +3871,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 +3886,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 +3987,7 @@ export {
   LINK_GROUP,
   LINK_POSTURES,
   LINK_STATES,
+  LINK_STEP,
   MODE_SPECS,
   OFFSET_ALPHAS,
   OUTLINE_HOVER_ALPHA,
@@ -4022,9 +4002,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 +4023,7 @@ export {
   generateScale,
   generateSubtleSecondary,
   groupEntries,
+  linkLeaf,
   linkPath,
   neutralCss,
   neutralTintHue,

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/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.0",
   "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": {