okchroma 0.5.0 → 0.6.0

package/README.md

@@ -41,7 +41,7 @@ const css = brandCss('acme', 'Acme', theme.themed, theme.secondary?.scale ?? nul
 // and data-theme="dark" on it for dark mode
 ```
 
-The Figma tree comes from `themeToFigma`. Signatures, the full input, and an end-to-end example:
+The same values as one object per mode come from `themeTokens`, and the state layer as named rows from `interactionCss` and `interactionTokens` (`docs/agents.md` lists the rows). The Figma tree comes from `themeToFigma`. Signatures, the full input, and an end-to-end example:
 [Install and API](https://egerrity.github.io/okchroma/#/docs/install).
 
 ## Run from source

package/dist-lib/index.cjs

@@ -24,7 +24,12 @@ __export(index_exports, {
   DEFAULT_LINK_HEX: () => DEFAULT_LINK_HEX,
   DISABLED_OPACITY: () => DISABLED_OPACITY,
   EXT_KEY: () => EXT_KEY,
+  INTERACTION_FAMILIES: () => INTERACTION_FAMILIES,
+  INTERACTION_LADDER: () => INTERACTION_LADDER,
+  INTERACTION_POLE_FAMILY: () => INTERACTION_POLE_FAMILY,
+  INTERACTION_ROWS: () => INTERACTION_ROWS,
   INTERACTION_RUNGS: () => INTERACTION_RUNGS,
+  INTERACTION_STATES: () => INTERACTION_STATES,
   MODE_SPECS: () => MODE_SPECS,
   OFFSET_ALPHAS: () => OFFSET_ALPHAS,
   OPACITY_RUNGS: () => OPACITY_RUNGS,
@@ -60,6 +65,11 @@ __export(index_exports, {
   generateNeutralScale: () => generateNeutralScale,
   generateScale: () => generateScale,
   generateSubtleSecondary: () => generateSubtleSecondary,
+  interactionCss: () => interactionCss,
+  interactionRows: () => interactionRows,
+  interactionTintName: () => interactionTintName,
+  interactionTokens: () => interactionTokens,
+  interactionVarName: () => interactionVarName,
   neutralCss: () => neutralCss,
   neutralTintHue: () => neutralTintHue,
   opacityLeafName: () => opacityLeafName,
@@ -67,19 +77,24 @@ __export(index_exports, {
   opacityVarName: () => opacityVarName,
   pageStopFor: () => pageStopFor,
   parseToken: () => parseToken,
+  readEmission: () => readEmission,
   resolveBrand: () => resolveBrand,
   resolveDtcgRamp: () => resolveDtcgRamp,
   resolveLinkInverseTrio: () => resolveLinkInverseTrio,
   resolveLinkTrio: () => resolveLinkTrio,
+  resolveReferences: () => resolveReferences,
   resolveTheme: () => resolveTheme,
   signalScalesFor: () => signalScalesFor,
   signalsCss: () => signalsCss,
   stopHex: () => stopHex,
   stopTokenName: () => stopTokenName,
   stopsToVars: () => stopsToVars,
+  systemCss: () => systemCss,
   themeToFigma: () => themeToFigma,
+  themeTokens: () => themeTokens,
   toHex: () => toHex2,
-  tokenOrder: () => tokenOrder
+  tokenOrder: () => tokenOrder,
+  tokensFromEmission: () => tokensFromEmission
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -3828,6 +3843,229 @@ function brandCss(slug, displayName, r, secondary, noteSuffix = "", neutralLevel
   ].join("\n");
 }
 
+// src/engine/tokensRender.ts
+var DARK_MARK = '[data-theme="dark"]';
+function readEmission(css) {
+  const light = /* @__PURE__ */ new Map();
+  const dark = /* @__PURE__ */ new Map();
+  const order = [];
+  let depth = 0;
+  let skipUntilDepth = -1;
+  let inDark = false;
+  let inBlock = false;
+  for (const line of css.split("\n")) {
+    const t = line.trim();
+    if (t.endsWith("{")) {
+      if (t.startsWith("@")) {
+        if (skipUntilDepth < 0) skipUntilDepth = depth;
+        depth++;
+        continue;
+      }
+      depth++;
+      if (skipUntilDepth < 0) {
+        inBlock = true;
+        inDark = t.includes(DARK_MARK);
+      }
+      continue;
+    }
+    if (t === "}") {
+      depth--;
+      if (skipUntilDepth >= 0 && depth === skipUntilDepth) skipUntilDepth = -1;
+      inBlock = false;
+      continue;
+    }
+    if (skipUntilDepth >= 0 || !inBlock || !t.startsWith("--")) continue;
+    const colon = t.indexOf(":");
+    if (colon === -1) continue;
+    const name = t.slice(2, colon).trim();
+    const value = t.slice(colon + 1).replace(/;$/, "").trim();
+    const target = inDark ? dark : light;
+    if (!light.has(name) && !dark.has(name)) order.push(name);
+    target.set(name, value);
+  }
+  return { light, dark, order };
+}
+var VAR_REF = /var\(--([a-z0-9-]+)(?:\s*,\s*([^)]*))?\)/g;
+function resolveReferences(own, shared) {
+  const out = {};
+  const lookup = (name) => own.get(name) ?? shared.get(name);
+  const resolve = (value, depth) => depth > 12 ? value : value.replace(VAR_REF, (_, ref, fallback) => {
+    const target = lookup(ref);
+    if (target !== void 0) return resolve(target, depth + 1);
+    return fallback !== void 0 ? resolve(fallback.trim(), depth + 1) : `var(--${ref})`;
+  });
+  for (const name of /* @__PURE__ */ new Set([...own.keys(), ...shared.keys()])) out[name] = resolve(lookup(name), 0);
+  return out;
+}
+function systemCss() {
+  const planeRef = (stop) => stop === PAPER_0 ? `var(--${PAPER_0})` : `var(--${CSS_FAMILY.neutral}-${stop})`;
+  const pad = (r) => String(r).padStart(2, "0");
+  const lines = (mode) => [
+    ...Object.entries(SURFACE_PLANE_LAW).map(([leaf, stops]) => `  --surface-${leaf.split("/").pop()}: ${planeRef(stops[mode])};`),
+    ...Object.keys(SHADOW_ALPHAS).map(Number).map((r) => `  --shadow-${pad(r)}: rgba(0, 0, 0, ${SHADOW_ALPHAS[r][mode]});`),
+    `  --scrim: rgba(0, 0, 0, ${SCRIM_ALPHA});`,
+    `  --disabled-opacity: ${DISABLED_OPACITY};`
+  ];
+  return [":root {", ...lines("light"), "}", `:root${DARK_MARK}, ${DARK_MARK} {`, ...lines("dark"), "}"].join("\n");
+}
+function tokensFromEmission(slug, css) {
+  const { light, dark, order } = readEmission(css);
+  const resolvedLight = resolveReferences(light, /* @__PURE__ */ new Map());
+  const resolvedDark = resolveReferences(dark, light);
+  const invariant = order.filter((n) => !dark.has(n) || light.has(n) && light.get(n) === dark.get(n));
+  const raw = { light: Object.fromEntries(light), dark: Object.fromEntries(dark) };
+  return { slug, names: order, light: resolvedLight, dark: resolvedDark, invariant, raw };
+}
+function themeTokens(input) {
+  const css = [
+    signalsCss(input.contrastProfile),
+    systemCss(),
+    brandCss(
+      input.slug,
+      input.displayName ?? input.slug,
+      input.brand,
+      input.secondary ?? null,
+      "",
+      input.neutralLevel ?? "default",
+      input.contrastProfile,
+      input.secondaryStyle,
+      input.ctaEscape,
+      input.linkHex ?? null,
+      input.ctaBorder ?? true,
+      input.neutralH
+    )
+  ].join("\n");
+  return tokensFromEmission(input.slug, css);
+}
+
+// src/engine/interaction.ts
+var INTERACTION_POLE_FAMILY = { strong: "neutral-strong", inverse: "neutral-inverse" };
+var INTERACTION_FAMILIES = [
+  CSS_FAMILY.neutral,
+  CSS_FAMILY.brandPrimary,
+  CSS_FAMILY.brandSecondary,
+  ...SIGNALS2.map((s) => s.emitName),
+  INTERACTION_POLE_FAMILY.strong,
+  INTERACTION_POLE_FAMILY.inverse
+];
+var INTERACTION_STATES = ["enabled", "hover", "pressed", "selected"];
+var INTERACTION_LADDER = {
+  subtle: { enabled: 8, hover: 12, pressed: 16, selected: 24 },
+  hint: { enabled: null, hover: 8, pressed: 12, selected: 16 }
+};
+var INTERACTION_ROWS = [
+  "fg",
+  "fg-strong",
+  "fg-on-hint",
+  "solid-bg-enabled",
+  "solid-bg-hover",
+  "solid-bg-pressed",
+  "solid-border",
+  "solid-fg",
+  "subtle-bg-enabled",
+  "subtle-bg-hover",
+  "subtle-bg-pressed",
+  "subtle-bg-selected",
+  "hint-bg-enabled",
+  "hint-bg-hover",
+  "hint-bg-pressed",
+  "hint-bg-selected"
+];
+var interactionVarName = (family, row) => `--${family}-${row}`;
+var isPole = (family) => family === INTERACTION_POLE_FAMILY.strong || family === INTERACTION_POLE_FAMILY.inverse;
+var hexChannels = (hex) => {
+  const m = /^#([0-9a-f]{2})([0-9a-f]{2})([0-9a-f]{2})$/i.exec(hex.trim());
+  return m ? [parseInt(m[1], 16), parseInt(m[2], 16), parseInt(m[3], 16)] : null;
+};
+function interactionTintName(family) {
+  if (family === INTERACTION_POLE_FAMILY.strong) return PEN_100;
+  if (family === INTERACTION_POLE_FAMILY.inverse) return PAPER_0;
+  return `${family}-${stopTokenName(8)}`;
+}
+function interactionRows(family, mode, tokens) {
+  const neutral = CSS_FAMILY.neutral;
+  const v2 = (name) => `var(--${name})`;
+  const pen = (stop) => `${family}-${stopTokenName(stop)}`;
+  const tintHex = tokens[mode][interactionTintName(family)];
+  const ch = tintHex ? hexChannels(tintHex) : null;
+  if (!ch) throw new Error(`interactionRows: no sRGB hex for ${interactionTintName(family)} in ${mode}`);
+  const at = (rung) => rung === null ? v2(TRANSPARENT_VAR.slice(2)) : `rgba(${ch[0]}, ${ch[1]}, ${ch[2]}, ${OPACITY_RUNGS[rung]})`;
+  const text = isPole(family) ? [["fg", v2(interactionTintName(family))], ["fg-strong", v2(interactionTintName(family))], ["fg-on-hint", v2(interactionTintName(family))]] : [["fg", v2(pen(10))], ["fg-strong", v2(pen(11))], ["fg-on-hint", v2(pen(9))]];
+  const solid = family === INTERACTION_POLE_FAMILY.strong ? [
+    ["solid-bg-enabled", v2(PEN_100)],
+    ["solid-bg-hover", v2(`${neutral}-${stopTokenName(11)}`)],
+    ["solid-bg-pressed", v2(`${neutral}-${stopTokenName(10)}`)],
+    ["solid-border", v2(TRANSPARENT_VAR.slice(2))],
+    ["solid-fg", v2(PAPER_0)]
+  ] : family === INTERACTION_POLE_FAMILY.inverse ? [
+    ["solid-bg-enabled", v2(PAPER_0)],
+    ["solid-bg-hover", v2(`${neutral}-${stopTokenName(2)}`)],
+    ["solid-bg-pressed", v2(`${neutral}-${stopTokenName(3)}`)],
+    ["solid-border", v2(TRANSPARENT_VAR.slice(2))],
+    ["solid-fg", v2(PEN_100)]
+  ] : [
+    ["solid-bg-enabled", v2(`${family}-${STAMP_FILL}`)],
+    ["solid-bg-hover", v2(`${family}-${STAMP_FILL_HOVER}`)],
+    ["solid-bg-pressed", v2(`${family}-${STAMP_FILL_PRESSED}`)],
+    ["solid-border", v2(`${family}-${STAMP_EDGE}`)],
+    ["solid-fg", v2(`${family}-${STAMP_ON}`)]
+  ];
+  const ladder = (tier) => INTERACTION_STATES.map((state) => [`${tier}-bg-${state}`, at(INTERACTION_LADDER[tier][state])]);
+  return [...text, ...solid, ...ladder("subtle"), ...ladder("hint")];
+}
+var rowVariesByMode = (row) => /^(subtle|hint)-bg-/.test(row) && row !== "hint-bg-enabled";
+function interactionCss(slug, tokens) {
+  const scope = `[data-brand="${slug}"]`;
+  const light = [];
+  const dark = [];
+  for (const family of INTERACTION_FAMILIES) {
+    for (const [row, value] of interactionRows(family, "light", tokens)) light.push(`  ${interactionVarName(family, row)}: ${value};`);
+    for (const [row, value] of interactionRows(family, "dark", tokens)) if (rowVariesByMode(row)) dark.push(`  ${interactionVarName(family, row)}: ${value};`);
+  }
+  const scoped = INTERACTION_FAMILIES.flatMap((family) => [
+    `${scope} [data-family="${family}"], ${scope}[data-family="${family}"] {`,
+    ...INTERACTION_ROWS.map((row) => `  --${row}: var(${interactionVarName(family, row)});`),
+    `}`
+  ]);
+  return [
+    `/* Interaction register: solid, subtle and hint tiers per family, the translucent rows at the engine's opacity rungs */`,
+    `${scope} {`,
+    ...light,
+    `}`,
+    `${scope}[data-theme="dark"] {`,
+    ...dark,
+    `}`,
+    ...scoped
+  ].join("\n");
+}
+function interactionTokens(tokens) {
+  const add = (mode) => {
+    const m = /* @__PURE__ */ new Map();
+    for (const family of INTERACTION_FAMILIES)
+      for (const [row, value] of interactionRows(family, mode, tokens)) m.set(interactionVarName(family, row).slice(2), value);
+    return m;
+  };
+  const rawLight = add("light");
+  const rawDark = add("dark");
+  const baseLight = new Map(Object.entries(tokens.light));
+  const baseDark = new Map(Object.entries(tokens.dark));
+  const light = resolveReferences(rawLight, baseLight);
+  const dark = resolveReferences(rawDark, baseDark);
+  const names = [...tokens.names, ...rawLight.keys()];
+  const invariant = [...tokens.invariant, ...[...rawLight.keys()].filter((n) => rawLight.get(n) === rawDark.get(n))];
+  return {
+    slug: tokens.slug,
+    names,
+    light: { ...tokens.light, ...Object.fromEntries([...rawLight.keys()].map((n) => [n, light[n]])) },
+    dark: { ...tokens.dark, ...Object.fromEntries([...rawDark.keys()].map((n) => [n, dark[n]])) },
+    invariant,
+    raw: {
+      light: { ...tokens.raw.light, ...Object.fromEntries(rawLight) },
+      dark: { ...tokens.raw.dark, ...Object.fromEntries(rawDark) }
+    }
+  };
+}
+
 // src/engine/figmaRender.ts
 var clamp01 = (v2) => Math.min(1, Math.max(0, v2));
 var TRANSPARENT_TOKEN = {
@@ -3995,7 +4233,7 @@ function themeToFigma(r, input) {
     }
     putLeaf(g2, SYSTEM_LEAF.ALPHA.TRANSPARENT, pole(true, 0));
     for (const rung of Object.keys(OPACITY_RUNGS).map(Number))
-      putLeaf(g2, opacityTokenPath(rung), { $type: "number", $value: OPACITY_RUNGS[rung] });
+      putLeaf(g2, opacityTokenPath(rung), { $type: "number", $value: 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));

package/dist-lib/index.mjs

@@ -3743,6 +3743,229 @@ function brandCss(slug, displayName, r, secondary, noteSuffix = "", neutralLevel
   ].join("\n");
 }
 
+// src/engine/tokensRender.ts
+var DARK_MARK = '[data-theme="dark"]';
+function readEmission(css) {
+  const light = /* @__PURE__ */ new Map();
+  const dark = /* @__PURE__ */ new Map();
+  const order = [];
+  let depth = 0;
+  let skipUntilDepth = -1;
+  let inDark = false;
+  let inBlock = false;
+  for (const line of css.split("\n")) {
+    const t = line.trim();
+    if (t.endsWith("{")) {
+      if (t.startsWith("@")) {
+        if (skipUntilDepth < 0) skipUntilDepth = depth;
+        depth++;
+        continue;
+      }
+      depth++;
+      if (skipUntilDepth < 0) {
+        inBlock = true;
+        inDark = t.includes(DARK_MARK);
+      }
+      continue;
+    }
+    if (t === "}") {
+      depth--;
+      if (skipUntilDepth >= 0 && depth === skipUntilDepth) skipUntilDepth = -1;
+      inBlock = false;
+      continue;
+    }
+    if (skipUntilDepth >= 0 || !inBlock || !t.startsWith("--")) continue;
+    const colon = t.indexOf(":");
+    if (colon === -1) continue;
+    const name = t.slice(2, colon).trim();
+    const value = t.slice(colon + 1).replace(/;$/, "").trim();
+    const target = inDark ? dark : light;
+    if (!light.has(name) && !dark.has(name)) order.push(name);
+    target.set(name, value);
+  }
+  return { light, dark, order };
+}
+var VAR_REF = /var\(--([a-z0-9-]+)(?:\s*,\s*([^)]*))?\)/g;
+function resolveReferences(own, shared) {
+  const out = {};
+  const lookup = (name) => own.get(name) ?? shared.get(name);
+  const resolve = (value, depth) => depth > 12 ? value : value.replace(VAR_REF, (_, ref, fallback) => {
+    const target = lookup(ref);
+    if (target !== void 0) return resolve(target, depth + 1);
+    return fallback !== void 0 ? resolve(fallback.trim(), depth + 1) : `var(--${ref})`;
+  });
+  for (const name of /* @__PURE__ */ new Set([...own.keys(), ...shared.keys()])) out[name] = resolve(lookup(name), 0);
+  return out;
+}
+function systemCss() {
+  const planeRef = (stop) => stop === PAPER_0 ? `var(--${PAPER_0})` : `var(--${CSS_FAMILY.neutral}-${stop})`;
+  const pad = (r) => String(r).padStart(2, "0");
+  const lines = (mode) => [
+    ...Object.entries(SURFACE_PLANE_LAW).map(([leaf, stops]) => `  --surface-${leaf.split("/").pop()}: ${planeRef(stops[mode])};`),
+    ...Object.keys(SHADOW_ALPHAS).map(Number).map((r) => `  --shadow-${pad(r)}: rgba(0, 0, 0, ${SHADOW_ALPHAS[r][mode]});`),
+    `  --scrim: rgba(0, 0, 0, ${SCRIM_ALPHA});`,
+    `  --disabled-opacity: ${DISABLED_OPACITY};`
+  ];
+  return [":root {", ...lines("light"), "}", `:root${DARK_MARK}, ${DARK_MARK} {`, ...lines("dark"), "}"].join("\n");
+}
+function tokensFromEmission(slug, css) {
+  const { light, dark, order } = readEmission(css);
+  const resolvedLight = resolveReferences(light, /* @__PURE__ */ new Map());
+  const resolvedDark = resolveReferences(dark, light);
+  const invariant = order.filter((n) => !dark.has(n) || light.has(n) && light.get(n) === dark.get(n));
+  const raw = { light: Object.fromEntries(light), dark: Object.fromEntries(dark) };
+  return { slug, names: order, light: resolvedLight, dark: resolvedDark, invariant, raw };
+}
+function themeTokens(input) {
+  const css = [
+    signalsCss(input.contrastProfile),
+    systemCss(),
+    brandCss(
+      input.slug,
+      input.displayName ?? input.slug,
+      input.brand,
+      input.secondary ?? null,
+      "",
+      input.neutralLevel ?? "default",
+      input.contrastProfile,
+      input.secondaryStyle,
+      input.ctaEscape,
+      input.linkHex ?? null,
+      input.ctaBorder ?? true,
+      input.neutralH
+    )
+  ].join("\n");
+  return tokensFromEmission(input.slug, css);
+}
+
+// src/engine/interaction.ts
+var INTERACTION_POLE_FAMILY = { strong: "neutral-strong", inverse: "neutral-inverse" };
+var INTERACTION_FAMILIES = [
+  CSS_FAMILY.neutral,
+  CSS_FAMILY.brandPrimary,
+  CSS_FAMILY.brandSecondary,
+  ...SIGNALS2.map((s) => s.emitName),
+  INTERACTION_POLE_FAMILY.strong,
+  INTERACTION_POLE_FAMILY.inverse
+];
+var INTERACTION_STATES = ["enabled", "hover", "pressed", "selected"];
+var INTERACTION_LADDER = {
+  subtle: { enabled: 8, hover: 12, pressed: 16, selected: 24 },
+  hint: { enabled: null, hover: 8, pressed: 12, selected: 16 }
+};
+var INTERACTION_ROWS = [
+  "fg",
+  "fg-strong",
+  "fg-on-hint",
+  "solid-bg-enabled",
+  "solid-bg-hover",
+  "solid-bg-pressed",
+  "solid-border",
+  "solid-fg",
+  "subtle-bg-enabled",
+  "subtle-bg-hover",
+  "subtle-bg-pressed",
+  "subtle-bg-selected",
+  "hint-bg-enabled",
+  "hint-bg-hover",
+  "hint-bg-pressed",
+  "hint-bg-selected"
+];
+var interactionVarName = (family, row) => `--${family}-${row}`;
+var isPole = (family) => family === INTERACTION_POLE_FAMILY.strong || family === INTERACTION_POLE_FAMILY.inverse;
+var hexChannels = (hex) => {
+  const m = /^#([0-9a-f]{2})([0-9a-f]{2})([0-9a-f]{2})$/i.exec(hex.trim());
+  return m ? [parseInt(m[1], 16), parseInt(m[2], 16), parseInt(m[3], 16)] : null;
+};
+function interactionTintName(family) {
+  if (family === INTERACTION_POLE_FAMILY.strong) return PEN_100;
+  if (family === INTERACTION_POLE_FAMILY.inverse) return PAPER_0;
+  return `${family}-${stopTokenName(8)}`;
+}
+function interactionRows(family, mode, tokens) {
+  const neutral = CSS_FAMILY.neutral;
+  const v2 = (name) => `var(--${name})`;
+  const pen = (stop) => `${family}-${stopTokenName(stop)}`;
+  const tintHex = tokens[mode][interactionTintName(family)];
+  const ch = tintHex ? hexChannels(tintHex) : null;
+  if (!ch) throw new Error(`interactionRows: no sRGB hex for ${interactionTintName(family)} in ${mode}`);
+  const at = (rung) => rung === null ? v2(TRANSPARENT_VAR.slice(2)) : `rgba(${ch[0]}, ${ch[1]}, ${ch[2]}, ${OPACITY_RUNGS[rung]})`;
+  const text = isPole(family) ? [["fg", v2(interactionTintName(family))], ["fg-strong", v2(interactionTintName(family))], ["fg-on-hint", v2(interactionTintName(family))]] : [["fg", v2(pen(10))], ["fg-strong", v2(pen(11))], ["fg-on-hint", v2(pen(9))]];
+  const solid = family === INTERACTION_POLE_FAMILY.strong ? [
+    ["solid-bg-enabled", v2(PEN_100)],
+    ["solid-bg-hover", v2(`${neutral}-${stopTokenName(11)}`)],
+    ["solid-bg-pressed", v2(`${neutral}-${stopTokenName(10)}`)],
+    ["solid-border", v2(TRANSPARENT_VAR.slice(2))],
+    ["solid-fg", v2(PAPER_0)]
+  ] : family === INTERACTION_POLE_FAMILY.inverse ? [
+    ["solid-bg-enabled", v2(PAPER_0)],
+    ["solid-bg-hover", v2(`${neutral}-${stopTokenName(2)}`)],
+    ["solid-bg-pressed", v2(`${neutral}-${stopTokenName(3)}`)],
+    ["solid-border", v2(TRANSPARENT_VAR.slice(2))],
+    ["solid-fg", v2(PEN_100)]
+  ] : [
+    ["solid-bg-enabled", v2(`${family}-${STAMP_FILL}`)],
+    ["solid-bg-hover", v2(`${family}-${STAMP_FILL_HOVER}`)],
+    ["solid-bg-pressed", v2(`${family}-${STAMP_FILL_PRESSED}`)],
+    ["solid-border", v2(`${family}-${STAMP_EDGE}`)],
+    ["solid-fg", v2(`${family}-${STAMP_ON}`)]
+  ];
+  const ladder = (tier) => INTERACTION_STATES.map((state) => [`${tier}-bg-${state}`, at(INTERACTION_LADDER[tier][state])]);
+  return [...text, ...solid, ...ladder("subtle"), ...ladder("hint")];
+}
+var rowVariesByMode = (row) => /^(subtle|hint)-bg-/.test(row) && row !== "hint-bg-enabled";
+function interactionCss(slug, tokens) {
+  const scope = `[data-brand="${slug}"]`;
+  const light = [];
+  const dark = [];
+  for (const family of INTERACTION_FAMILIES) {
+    for (const [row, value] of interactionRows(family, "light", tokens)) light.push(`  ${interactionVarName(family, row)}: ${value};`);
+    for (const [row, value] of interactionRows(family, "dark", tokens)) if (rowVariesByMode(row)) dark.push(`  ${interactionVarName(family, row)}: ${value};`);
+  }
+  const scoped = INTERACTION_FAMILIES.flatMap((family) => [
+    `${scope} [data-family="${family}"], ${scope}[data-family="${family}"] {`,
+    ...INTERACTION_ROWS.map((row) => `  --${row}: var(${interactionVarName(family, row)});`),
+    `}`
+  ]);
+  return [
+    `/* Interaction register: solid, subtle and hint tiers per family, the translucent rows at the engine's opacity rungs */`,
+    `${scope} {`,
+    ...light,
+    `}`,
+    `${scope}[data-theme="dark"] {`,
+    ...dark,
+    `}`,
+    ...scoped
+  ].join("\n");
+}
+function interactionTokens(tokens) {
+  const add = (mode) => {
+    const m = /* @__PURE__ */ new Map();
+    for (const family of INTERACTION_FAMILIES)
+      for (const [row, value] of interactionRows(family, mode, tokens)) m.set(interactionVarName(family, row).slice(2), value);
+    return m;
+  };
+  const rawLight = add("light");
+  const rawDark = add("dark");
+  const baseLight = new Map(Object.entries(tokens.light));
+  const baseDark = new Map(Object.entries(tokens.dark));
+  const light = resolveReferences(rawLight, baseLight);
+  const dark = resolveReferences(rawDark, baseDark);
+  const names = [...tokens.names, ...rawLight.keys()];
+  const invariant = [...tokens.invariant, ...[...rawLight.keys()].filter((n) => rawLight.get(n) === rawDark.get(n))];
+  return {
+    slug: tokens.slug,
+    names,
+    light: { ...tokens.light, ...Object.fromEntries([...rawLight.keys()].map((n) => [n, light[n]])) },
+    dark: { ...tokens.dark, ...Object.fromEntries([...rawDark.keys()].map((n) => [n, dark[n]])) },
+    invariant,
+    raw: {
+      light: { ...tokens.raw.light, ...Object.fromEntries(rawLight) },
+      dark: { ...tokens.raw.dark, ...Object.fromEntries(rawDark) }
+    }
+  };
+}
+
 // src/engine/figmaRender.ts
 var clamp01 = (v2) => Math.min(1, Math.max(0, v2));
 var TRANSPARENT_TOKEN = {
@@ -3910,7 +4133,7 @@ function themeToFigma(r, input) {
     }
     putLeaf(g2, SYSTEM_LEAF.ALPHA.TRANSPARENT, pole(true, 0));
     for (const rung of Object.keys(OPACITY_RUNGS).map(Number))
-      putLeaf(g2, opacityTokenPath(rung), { $type: "number", $value: OPACITY_RUNGS[rung] });
+      putLeaf(g2, opacityTokenPath(rung), { $type: "number", $value: 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));
@@ -4000,7 +4223,12 @@ export {
   DEFAULT_LINK_HEX,
   DISABLED_OPACITY,
   EXT_KEY,
+  INTERACTION_FAMILIES,
+  INTERACTION_LADDER,
+  INTERACTION_POLE_FAMILY,
+  INTERACTION_ROWS,
   INTERACTION_RUNGS,
+  INTERACTION_STATES,
   MODE_SPECS,
   OFFSET_ALPHAS,
   OPACITY_RUNGS,
@@ -4036,6 +4264,11 @@ export {
   generateNeutralScale,
   generateScale,
   generateSubtleSecondary,
+  interactionCss,
+  interactionRows,
+  interactionTintName,
+  interactionTokens,
+  interactionVarName,
   neutralCss,
   neutralTintHue,
   opacityLeafName,
@@ -4043,17 +4276,22 @@ export {
   opacityVarName,
   pageStopFor,
   parseToken,
+  readEmission,
   resolveBrand,
   resolveDtcgRamp,
   resolveLinkInverseTrio,
   resolveLinkTrio,
+  resolveReferences,
   resolveTheme,
   signalScalesFor,
   signalsCss,
   stopHex,
   stopTokenName,
   stopsToVars,
+  systemCss,
   themeToFigma,
+  themeTokens,
   toHex2 as toHex,
-  tokenOrder
+  tokenOrder,
+  tokensFromEmission
 };

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

@@ -0,0 +1,35 @@
+import { type OpacityRung } from './cssRender';
+import { type ThemeTokens, type TokenMode } from './tokensRender';
+export declare const INTERACTION_POLE_FAMILY: {
+    readonly strong: "neutral-strong";
+    readonly inverse: "neutral-inverse";
+};
+export type InteractionPoleFamily = (typeof INTERACTION_POLE_FAMILY)[keyof typeof INTERACTION_POLE_FAMILY];
+/** every family the register emits, color families first, the two pole families last */
+export declare const INTERACTION_FAMILIES: readonly string[];
+export type InteractionState = 'enabled' | 'hover' | 'pressed' | 'selected';
+export declare const INTERACTION_STATES: readonly InteractionState[];
+/** the rung each translucent tier takes per state; null is the transparent rest */
+export declare const INTERACTION_LADDER: Record<'subtle' | 'hint', Record<InteractionState, OpacityRung | null>>;
+export declare const INTERACTION_ROWS: readonly ["fg", "fg-strong", "fg-on-hint", "solid-bg-enabled", "solid-bg-hover", "solid-bg-pressed", "solid-border", "solid-fg", "subtle-bg-enabled", "subtle-bg-hover", "subtle-bg-pressed", "subtle-bg-selected", "hint-bg-enabled", "hint-bg-hover", "hint-bg-pressed", "hint-bg-selected"];
+export type InteractionRow = (typeof INTERACTION_ROWS)[number];
+/** the CSS custom property a family's row lives under */
+export declare const interactionVarName: (family: string, row: InteractionRow) => string;
+/**
+ * The name whose channels a family's translucent rows ride: the family's
+ * highlighter-26, or the pole for the pole families.
+ */
+export declare function interactionTintName(family: string): string;
+/** One family's rows for one mode as [name, value] pairs, aliases as var() and rungs as rgba. */
+export declare function interactionRows(family: string, mode: TokenMode, tokens: ThemeTokens): Array<[InteractionRow, string]>;
+/**
+ * The register as CSS for one brand: every family's rows under the brand scope, the
+ * rung rows per mode, then one scope block per family that maps the family-agnostic
+ * names (`--solid-bg-enabled`, `--fg`) onto that family, so a component reads one set
+ * of names and `data-family` picks the family, the way a mode does on a Figma instance.
+ */
+export declare function interactionCss(slug: string, tokens: ThemeTokens): string;
+/** The base tokens plus the register's rows, resolved to literals per mode. */
+export declare function interactionTokens(tokens: ThemeTokens): ThemeTokens;
+/** every rung the register uses is one of the engine's interaction rungs */
+export declare const interactionLadderIsLegal: () => boolean;

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

@@ -0,0 +1,51 @@
+import type { GeneratedScale, NeutralLevel, ContrastProfile } from './colorEngine';
+import type { ResolvedBrand, SecondaryStyle } from './resolve';
+export type TokenMode = 'light' | 'dark';
+export interface ThemeTokens {
+    slug: string;
+    /** every emitted name, in emission order */
+    names: string[];
+    /** resolved literal values per mode; mode-invariant names appear in both */
+    light: Record<string, string>;
+    dark: Record<string, string>;
+    /** names whose value does not depend on the mode */
+    invariant: string[];
+    /** the declarations as emitted, var() references intact, per block */
+    raw: {
+        light: Record<string, string>;
+        dark: Record<string, string>;
+    };
+}
+export interface ThemeTokensInput {
+    slug: string;
+    displayName?: string;
+    /** the resolved brand; for a resolved theme pass `theme.themed` */
+    brand: ResolvedBrand;
+    secondary?: GeneratedScale | null;
+    neutralLevel?: NeutralLevel;
+    contrastProfile?: ContrastProfile;
+    secondaryStyle?: SecondaryStyle;
+    ctaEscape?: boolean;
+    linkHex?: string | null;
+    ctaBorder?: boolean;
+    neutralH?: number;
+}
+/**
+ * Reads the engine's CSS emission into one declaration map per mode. Only the
+ * emitters' own grammar is understood: a line ending in `{` opens a block, a line
+ * that is `}` closes one, `--name: value;` lines declare. At-rule groups (the
+ * display-p3 re-emission) are skipped whole.
+ */
+export declare function readEmission(css: string): {
+    light: Map<string, string>;
+    dark: Map<string, string>;
+    order: string[];
+};
+/** Resolves var() references against `own`, falling back to `shared` for names declared once. */
+export declare function resolveReferences(own: Map<string, string>, shared: Map<string, string>): Record<string, string>;
+/** The system rows tokens/semantic.css states as static aliases, as engine-table projections. */
+export declare function systemCss(): string;
+/** Builds a ThemeTokens object from an emission's declaration maps. */
+export declare function tokensFromEmission(slug: string, css: string): ThemeTokens;
+/** The whole page's token set for one brand: signals, system rows, and the brand block. */
+export declare function themeTokens(input: ThemeTokensInput): ThemeTokens;

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

@@ -2,6 +2,8 @@ export { generateScale, generateNeutralScale, generateSubtleSecondary, neutralTi
 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, 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 { themeTokens, tokensFromEmission, readEmission, resolveReferences, systemCss, type ThemeTokens, type ThemeTokensInput, type TokenMode, } from './engine/tokensRender';
+export { interactionCss, interactionTokens, interactionRows, interactionVarName, interactionTintName, INTERACTION_FAMILIES, INTERACTION_POLE_FAMILY, INTERACTION_ROWS, INTERACTION_STATES, INTERACTION_LADDER, type InteractionRow, type InteractionState, type InteractionPoleFamily, } from './engine/interaction';
 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';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "okchroma",
-  "version": "0.5.0",
+  "version": "0.6.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": {
@@ -54,7 +54,8 @@
     "name-lint": "esbuild scripts/name-lint.ts --bundle --platform=node --outfile=dist/name-lint.js && node dist/name-lint.js",
     "typecheck": "tsc --noEmit",
     "typecheck:ext": "tsc --noEmit -p plugin-ext",
-    "docs:lint": "esbuild scripts/docs-lint.ts --bundle --platform=node --outfile=dist/docs-lint.js && node dist/docs-lint.js"
+    "docs:lint": "esbuild scripts/docs-lint.ts --bundle --platform=node --outfile=dist/docs-lint.js && node dist/docs-lint.js",
+    "audit:tokens": "esbuild scripts/tokens-audit.ts --bundle --platform=node --outfile=dist/tokens-audit.js && node dist/tokens-audit.js"
   },
   "devDependencies": {
     "@types/node": "^25.9.2",