okchroma 0.2.2 → 0.3.0

package/README.md

@@ -1,134 +1,95 @@
 # OKChroma
 
-**A color-system engine.** Give it one (or two) brand color(s) and it generates a complete,
-accessible, theme-ready color system around it.
-
-Each color family is a light and dark ramp built from pre-reserved roles — 3 papers,
-4 highlighters, 1 crayon, 1 pencil, and 2 pens — plus the stamp fill with its hover and
-pressed states and its on-text color, for each brand hex inputted. Alongside the brand color(s), it generates a neutral and the critical / warning / positive / info signal scales. The inputted hex color(s) is/are preserved in identity swatches for logos or other brand identity moments.
-
-The point is **white-label predictability**: every ramps's stops land at the same
-perceived lightness and play the same role, so you map your design tokens to step
-**numbers** once and they hold for any color scale. Contrast is built into the math, not
-bolted on after: the system solves against **WCAG** ratios (every text color guaranteed
-to pass), with **APCA** as an added legibility floor on CTA text (Lc 65 clearance on top
-of the 4.5:1 requirement).
-
-Output comes in two interchangeable forms carrying the same values:
-
-- **CSS custom properties** — per-brand CSS generated live (`brandCss`) + the static
-  `dist/signals.css`, via the semantic layer `tokens/semantic.css`.
-- **Figma variables** — written into a Figma file by the bundled plugin.
-
-The live demo and the Figma plugin are previews/front-ends; the engine and its output are
-the product.
-
-> The "reserved role per step" model is a conceptual nod to
+**A color-system engine.** Give it one brand hex, or two, and it resolves a complete
+light and dark token system whose contrast requirements are solved during generation,
+then emits it as CSS custom properties, Figma variables, or DTCG requirement tokens.
+
+Every family (neutral, brand, brand-alt, critical, warning, positive, info) carries the
+same scale: 3 papers, 4 highlighters, 1 crayon, 1 pencil, 2 pens, plus the stamp (the
+solid fill with its hover and pressed states, its edge, and its text). The neutral adds
+the two poles. Light and dark resolve together and ship on the same names, so a token is
+mapped once and holds for any brand.
+
+Contrast is built into the math, not checked afterwards: `crayon-26` reads on every paper
+at 3:1 (the non-text bar), `pencil-47` at 4.5:1, `pen-58` and `pen-70` at 4.5:1 on every
+paper and highlighter in both directions; the stamp's text passes 4.5:1 on the fill and
+brand and signal fills clear APCA Lc 65 on top. Each claim, its scope, and the audit that
+proves it: [Guarantees](https://egerrity.github.io/okchroma/#/docs/guarantees).
+
+> The reserved-role-per-stop model is a conceptual nod to
 > [Radix Colors](https://www.radix-ui.com/colors/docs/palette-composition/understanding-the-scale).
-> It is **not** a dependency and does not affect the math — all color computation is original.
-
-## Quick start
-
-```bash
-npm install
-npm run demo:build      # generate token CSS + bundle the demo
-npx serve .             # then open http://localhost:3000/demo/index.html
-```
-
-Live editing: `npm run dev` (watch mode). Build the Figma plugin: `npm run plugin:build`,
-then import `plugin/manifest.json` in Figma.
+> It is not a dependency and does not touch the math; the color computation is original.
 
-## Use as an npm package
+## Install
 
 ```bash
 npm install okchroma
 ```
 
-```ts
-import { resolveTheme, brandCss, signalsCss } from 'okchroma'
+ESM and CommonJS builds with TypeScript declarations; no runtime dependencies (the one
+perceptual-distance library the engine uses is bundled in).
 
-const t = resolveTheme({ primaryHex: '#E93D82', name: 'Acme' })
-const css = brandCss('acme', 'Acme', t.themed) + '\n' + signalsCss()
+```ts
+import { resolveTheme, brandCss, signalsCss, neutralTintHue } from 'okchroma'
+
+const theme = resolveTheme({ primaryHex: '#E93D82', name: 'acme', deriveSecondary: true })
+const neutralH = neutralTintHue(theme.themed.scale.brandH)
+const css = brandCss('acme', 'Acme', theme.themed, theme.secondary?.scale ?? null,
+  '', 'default', undefined, theme.secondary?.style, false, null, true, neutralH)
+  + '\n' + signalsCss()
+// put css in a stylesheet; set data-brand="acme" on the themed root,
+// and data-theme="dark" on it for dark mode
 ```
 
-`resolveTheme` solves the full system for a seed (primary, optional secondary, neutral
-source, signal policy). `brandCss` emits the solved light and dark values as CSS custom
-properties scoped to `[data-brand="acme"]`, with dark values under
-`[data-brand="acme"][data-theme="dark"]`; the per-brand neutral is included in the same
-block. Variables are named `--brand-<token>`, `--neutral-<token>`, and
-`--<signal>-<token>`. Inject the string into a `<style>` tag at runtime or write it to a
-file at build time; `signalsCss()` is brand-independent and emitted once.
-
-The same resolved theme feeds the other emitters: `themeToFigma` returns the Figma
-variable payload, and `emitDtcgRamp` returns DTCG JSON carrying the live requirement in
-`$extensions`. ESM and CJS builds ship with TypeScript declarations. The package bundles
-its one runtime dependency (helmlab), so installing it adds nothing transitive.
-
-## How it works (30 seconds)
-
-Every token is a **requirement the engine solves, not a frozen value**. A pure-data
-declaration (`src/engine/requirements/spec.ts`) states each stop's producer (perceptual
-placement, warm drift, chroma ladder) and its requirements (contrast floors, seam
-separations, on-text rules); a resolver executes it per seed — **produce → require →
-refine**. `resolveBrand(hex)` runs that engine, applies **policy** (status-color
-collisions, signal shifts), and an **emitter** (`cssRender` / `figmaRender`) maps the
-resolved stops onto named tokens and picks light vs dark. The declaration also
-round-trips to DTCG tokens (`$value` fallback + the live requirement in `$extensions`).
-
-- **Engine:** `src/engine/*` — pure TypeScript with one runtime dependency (helmlab,
-  the P2 adjacency metric), bundled into the npm package at build time.
-- **Entry points:** `resolveBrand` (`src/engine/resolve.ts`) and `generateScale`
-  (`src/engine/colorEngine.ts`, an adapter over the resolver — same signature as always).
-- **Build:** `src/build.ts` writes the one static output, `dist/signals.css`. There is no
-  brand roster: per-brand CSS is generated live by whichever caller resolves a hex (the
-  demo's hex input, a plugin's form field).
-
-## The Figma plugin
-
-The bundled plugin runs the same engine inside Figma and writes the resolved system into
-your file as variables: **theme** + **mode** collections whose semantic tokens alias onto
-shared primitives — per-brand ramps under `brand/<name>`, with neutrals and signals
-deduplicated across brands, light + dark values on every token.
-
-**Install** — from source:
+The Figma tree comes from `themeToFigma`, the DTCG requirement tokens from
+`emitDtcgRamp`. Signatures, the full input, and an end-to-end example:
+[Install and API](https://egerrity.github.io/okchroma/#/docs/install).
+
+## Run from source
 
 ```bash
-npm install && npm run plugin:build
+npm install
+npm run demo:build      # writes dist/signals.css and bundles the demo
+npx serve .             # open http://localhost:3000/demo/index.html
+npm run dev             # watch mode
 ```
 
-then Figma → Plugins → Development → **Import plugin from manifest** →
-`plugin/manifest.json`.
-
-> The hosted download for **this** plugin is **withdrawn** as of 2026-07-29. The scale
-> changed shape in that round — `highlight-9` and `on-highlight` were removed and the pen
-> stops renumbered — and this plugin does not yet carry the rename table that migrates an
-> existing Figma file across it, so updating an installed copy would orphan its variable
-> bindings. Building from source is unaffected: a fresh file gets the new shape correctly.
->
-> The **extended collections** plugin (Figma Enterprise) does carry the migration and is
-> published as normal — **[install it here](https://egerrity.github.io/okchroma/install.html)**.
-
-**Use** — name the brand, pick a primary, and Apply. Optional before applying:
-
-- **Secondary color** — "+ Add secondary" starts on *From primary* (a pastel derived from
-  your primary); type any hex for a custom secondary in **Tint / Pastel / Outline / Exact**
-  style.
-- **Neutral color** — *Default* (a touch of primary hue), *Medium* (slightly more tint), *Intense*, or *True grey*.
-- **Contrast standard** — **APCA** (default) or **WCAG**. One profile per collection pair:
-  applying the other profile to an existing file forks a clearly-labeled second pair
-  (`theme-wcag`/`mode-wcag`) instead of ever mixing values.
-
-Re-applying the same brand name updates it in place (after a confirm); a new name adds a
-brand to the same collections — two applies with two brand colors is a multi-brand system
-on shared foundations.
+`npm run typecheck` runs the compiler; the audit gates (`npm run req:audit`,
+`npm run audit:guarantee`, and the rest of `package.json`) each sweep agnostic seeds and
+fail on the worst case. What each proves:
+[How it is verified](https://egerrity.github.io/okchroma/#/docs/guarantees/how-it-is-verified).
 
 ## Documentation
 
-Full system documentation — overview, architecture (data flow + design decisions),
-dependencies, setup — is in **[docs/architecture.md](docs/architecture.md)**.
-The scale model and its per-stop targets are in **[docs/scale.md](docs/scale.md)**.
-The requirement-token schema — the DTCG token format, field by field, with real
-emitted examples — is in **[docs/schema.md](docs/schema.md)**.
+The docs site is the source: [egerrity.github.io/okchroma/#/docs](https://egerrity.github.io/okchroma/#/docs).
+
+- [Overview](https://egerrity.github.io/okchroma/#/docs/overview): what goes in, what comes out, the token roster.
+- [Output contract](https://egerrity.github.io/okchroma/#/docs/output): the naming grammar, families and prefixes, modes and selectors, a live CSS block and Figma tree.
+- [Guarantees](https://egerrity.github.io/okchroma/#/docs/guarantees): every claim stated exactly, and how it is verified.
+- [How the theme is generated](https://egerrity.github.io/okchroma/#/docs/generation): the pipeline in execution order, with the constants and the code that runs each step.
+- [Signals and companions](https://egerrity.github.io/okchroma/#/docs/signals), [Requirement tokens](https://egerrity.github.io/okchroma/#/docs/token-schema), [Reference](https://egerrity.github.io/okchroma/#/docs/reference).
+
+In the repo: [docs/architecture.md](docs/architecture.md) (the maintainer's map: modules,
+pipeline stages, data structures, the extended plugin's zones),
+[docs/scale.md](docs/scale.md) (the scale and its declared targets),
+[docs/schema.md](docs/schema.md) (the requirement-token format in the repo),
+[docs/agents.md](docs/agents.md) (how a coding agent consuming the tokens should read
+them), and [CHANGELOG.md](CHANGELOG.md).
+
+## The Figma plugins
+
+- **OKChroma Extended** (`plugin-ext/`) is the shipped Figma front-end. It requires the
+  Figma desktop app and a Figma Enterprise plan: it writes extended variable collections,
+  one base collection with light and dark modes plus one extension per brand that
+  overrides only what differs. Download and install steps:
+  [install page](https://egerrity.github.io/okchroma/install.html). Build from source with
+  `npm run plugin-ext:build`; see [plugin-ext/README.md](plugin-ext/README.md).
+- **OKChroma** (`plugin/`, the community plugin) is withdrawn from download until it
+  carries the rename table that migrates an existing file across the scale change of July
+  2026. It still builds from source with `npm run plugin:build` and imports from
+  `plugin/manifest.json`; a fresh file gets the current shape.
+
+The demo and the plugins are front-ends. The product is the engine and what it emits.
 
 ## License
 

package/dist-lib/index.cjs

@@ -947,9 +947,9 @@ var LIGHT = {
     { stop: 11, rootL: ROOT_L_LIGHT[11], group: groupOf(11), produce: PL_TEXT, chromaMult: SCALE_C_LIGHT[11].textMult, textMaxC: SCALE_C_LIGHT[11].textMaxC, chromaFloor: SCALE_C_LIGHT[11].chromaFloor, require: T11 }
   ],
   roles: [
-    { role: "cta", produce: { hue: "constant", L: "anchor", chroma: "brand" }, floorL: 0, chromaMult: 1 },
-    { role: "cta-hover", produce: { hue: "constant", L: "hover", chroma: "brand" }, floorL: 0, chromaMult: 1 },
-    { role: "cta-pressed", produce: { hue: "constant", L: "pressed", chroma: "brand" }, floorL: 0, chromaMult: 1 }
+    { role: STAMP_FILL, produce: { hue: "constant", L: "anchor", chroma: "brand" }, floorL: 0, chromaMult: 1 },
+    { role: STAMP_FILL_HOVER, produce: { hue: "constant", L: "hover", chroma: "brand" }, floorL: 0, chromaMult: 1 },
+    { role: STAMP_FILL_PRESSED, produce: { hue: "constant", L: "pressed", chroma: "brand" }, floorL: 0, chromaMult: 1 }
   ],
   ons: ONS
 };
@@ -979,9 +979,9 @@ var DARK = {
     { stop: 11, rootL: ROOT_L_DARK[11], group: groupOf(11), produce: P_TEXT, chromaMult: SCALE_C_DARK[11].textMult, textMaxC: SCALE_C_DARK[11].textMaxC, chromaFloor: SCALE_C_DARK[11].chromaFloor, require: T11 }
   ],
   roles: [
-    { role: "cta", produce: { hue: "constant", L: "anchor", chroma: "brand" }, floorL: DARK_CTA_MIN_L, chromaMult: 1 },
-    { role: "cta-hover", produce: { hue: "constant", L: "hover", chroma: "brand" }, floorL: DARK_CTA_MIN_L, chromaMult: 1 },
-    { role: "cta-pressed", produce: { hue: "constant", L: "pressed", chroma: "brand" }, floorL: DARK_CTA_MIN_L, chromaMult: 1 }
+    { role: STAMP_FILL, produce: { hue: "constant", L: "anchor", chroma: "brand" }, floorL: DARK_CTA_MIN_L, chromaMult: 1 },
+    { role: STAMP_FILL_HOVER, produce: { hue: "constant", L: "hover", chroma: "brand" }, floorL: DARK_CTA_MIN_L, chromaMult: 1 },
+    { role: STAMP_FILL_PRESSED, produce: { hue: "constant", L: "pressed", chroma: "brand" }, floorL: DARK_CTA_MIN_L, chromaMult: 1 }
   ],
   ons: ONS
 };
@@ -2360,6 +2360,8 @@ var toHex = (rgb) => "#" + rgb.map((c) => Math.round(c * 255).toString(16).padSt
 var CTA_CLEARANCE_CAPS = [0.05, 0.92];
 var CHROMATIC_W80_WORST_SHIP_Y = { light: 0.459357, dark: 0.074936 };
 var CHROMATIC_P3_WORST_SHIP_Y = { light: 0.836007, dark: 0.016041 };
+var NEUTRAL_P3_WORST_SHIP_Y = { light: 0.845015, dark: 0.014247 };
+var NEUTRAL_W80_WORST_SHIP_Y = { light: 0.506433, dark: 0.074262 };
 function resolveRamp(hex, mode, spec, opts) {
   const o = hexToOklch(hex);
   const seed = { hex, ...o };
@@ -2371,10 +2373,10 @@ function resolveRamp(hex, mode, spec, opts) {
       stops: spec.stops.map((s) => s.stop === 10 && s.require?.metric === "wcag" ? { ...s, require: { ...s.require, target: 6.5 } } : s)
     };
   }
-  const ctaReq = spec.roles.find((r) => r.role === "cta");
-  const hoverReq = spec.roles.find((r) => r.role === "cta-hover");
-  const pressedReq = spec.roles.find((r) => r.role === "cta-pressed");
-  if (!ctaReq) throw new Error("spec has no cta role");
+  const ctaReq = spec.roles.find((r) => r.role === STAMP_FILL);
+  const hoverReq = spec.roles.find((r) => r.role === STAMP_FILL_HOVER);
+  const pressedReq = spec.roles.find((r) => r.role === STAMP_FILL_PRESSED);
+  if (!ctaReq) throw new Error(`spec has no ${STAMP_FILL} role`);
   const onFillEnforce = ctx.opts?.enforceOnFillContrast ?? spec.ons.onFill.enforce;
   const dctx = mode === "dark" ? buildDarkContext(ctx, ctaReq.floorL) : null;
   const stops = [];
@@ -2393,8 +2395,6 @@ function resolveRamp(hex, mode, spec, opts) {
   const textGround = ctx.opts?.textGround?.[mode];
   const groundOf = (req, stop) => textGround && stop >= 9 ? textGround : refOf(wcagAnchorStop(req, stop), stop);
   const apcaGroundOf = (req, stop) => textGround && stop >= 9 ? textGround : refOf(declaredAnchor(req), stop);
-  const NEUTRAL_P3_WORST_SHIP_Y = { light: 0.845015, dark: 0.014247 };
-  const NEUTRAL_W80_WORST_SHIP_Y = { light: 0.506433, dark: 0.074262 };
   const maxLForOf = (req, forWhom, withMargin) => {
     if (req.metric === "wcag") {
       const g2 = groundOf(req, forWhom);
@@ -2579,13 +2579,13 @@ function resolveRamp(hex, mode, spec, opts) {
         repelled = true;
       }
     }
-    cta = emitRole("cta", light9L, ctaCFor(light9L) * ctaCMul, ctaH);
+    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("cta-hover", hL, hCFor(hL), ctaH);
-    ctaPressed = emitRole("cta-pressed", pL, pCFor(pL), ctaH);
+    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;
@@ -2608,19 +2608,19 @@ function resolveRamp(hex, mode, spec, opts) {
     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)];
-    cta = emitRole("cta", cta9L, dCFor(cta9L), ctx.darkCtaH);
+    cta = emitRole(STAMP_FILL, cta9L, dCFor(cta9L), ctx.darkCtaH);
     {
       const [hL, pL] = dTrio(cta9L);
-      ctaHover = emitRole("cta-hover", hL, dCFor(hL), ctx.darkCtaH);
-      ctaPressed = emitRole("cta-pressed", pL, dCFor(pL), ctx.darkCtaH);
+      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("cta", enforcedL, dCFor(enforcedL), ctx.darkCtaH);
+      cta = emitRole(STAMP_FILL, enforcedL, dCFor(enforcedL), ctx.darkCtaH);
       const [hL, pL] = dTrio(enforcedL);
-      ctaHover = emitRole("cta-hover", hL, dCFor(hL), ctx.darkCtaH);
-      ctaPressed = emitRole("cta-pressed", pL, dCFor(pL), ctx.darkCtaH);
+      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;
@@ -2629,10 +2629,10 @@ function resolveRamp(hex, mode, spec, opts) {
       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("cta", clearedL, dCFor(clearedL), ctx.darkCtaH);
+        cta = emitRole(STAMP_FILL, clearedL, dCFor(clearedL), ctx.darkCtaH);
         const [hL, pL] = dTrio(clearedL);
-        ctaHover = emitRole("cta-hover", hL, dCFor(hL), ctx.darkCtaH);
-        ctaPressed = emitRole("cta-pressed", pL, dCFor(pL), ctx.darkCtaH);
+        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;
@@ -2641,10 +2641,10 @@ function resolveRamp(hex, mode, spec, opts) {
     if (ctx.opts?.ctaSolve) {
       const exitL = solveDarkCtaExit(cta, dCFor, ctx.darkCtaH, ctx.opts.ctaSolve.redDark, enforceLc, coLc);
       if (exitL !== null) {
-        cta = emitRole("cta", exitL, dCFor(exitL), ctx.darkCtaH);
+        cta = emitRole(STAMP_FILL, exitL, dCFor(exitL), ctx.darkCtaH);
         const [hL, pL] = dTrio(exitL);
-        ctaHover = emitRole("cta-hover", hL, dCFor(hL), ctx.darkCtaH);
-        ctaPressed = emitRole("cta-pressed", pL, dCFor(pL), ctx.darkCtaH);
+        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;
@@ -3977,9 +3977,14 @@ function themeToFigma(r, input) {
 // src/engine/requirements/dtcg.ts
 var EXT_KEY = "org.okchroma.requirement";
 var RESOLVER_ID = "okchroma-reqtoken@2";
+var LEGACY_ROLE_NAMES = {
+  "cta": STAMP_FILL,
+  "cta-hover": STAMP_FILL_HOVER,
+  "cta-pressed": STAMP_FILL_PRESSED
+};
 var hexToValue = (hex) => {
   const h = hex.replace("#", "");
-  const c = (i) => parseInt(h.slice(i, i + 2), 16) / 255;
+  const c = (i) => Math.round(parseInt(h.slice(i, i + 2), 16) / 255 * 1e4) / 1e4;
   return { colorSpace: "srgb", components: [c(0), c(2), c(4)], alpha: 1, hex: hex.toLowerCase() };
 };
 function emitDtcgRamp(hex, mode, groupName, spec) {
@@ -3995,9 +4000,9 @@ function emitDtcgRamp(hex, mode, groupName, spec) {
     group[String(sp.stop)] = { $type: "color", $value: hexToValue(st.hex), $extensions: { [EXT_KEY]: { resolver: RESOLVER_ID, seed: seedRef, mode, ...sp } } };
   }
   const roleVal = {
-    "cta": ramp.roles.cta,
-    "cta-hover": ramp.roles.ctaHover,
-    "cta-pressed": ramp.roles.ctaPressed
+    [STAMP_FILL]: ramp.roles.cta,
+    [STAMP_FILL_HOVER]: ramp.roles.ctaHover,
+    [STAMP_FILL_PRESSED]: ramp.roles.ctaPressed
   };
   for (const rr of spec.roles) {
     const rv = roleVal[rr.role];
@@ -4017,6 +4022,7 @@ function parseToken(token) {
   if (isRole) {
     for (const k of ["role", "produce", "floorL", "chromaMult"]) if (req[k] === void 0) throw new Error(`role requirement missing "${k}"`);
   }
+  if (isRole && LEGACY_ROLE_NAMES[req.role]) req.role = LEGACY_ROLE_NAMES[req.role];
   return { req, seedRef: seed, mode };
 }
 function resolveDtcgRamp(group) {

package/dist-lib/index.mjs

@@ -868,9 +868,9 @@ var LIGHT = {
     { stop: 11, rootL: ROOT_L_LIGHT[11], group: groupOf(11), produce: PL_TEXT, chromaMult: SCALE_C_LIGHT[11].textMult, textMaxC: SCALE_C_LIGHT[11].textMaxC, chromaFloor: SCALE_C_LIGHT[11].chromaFloor, require: T11 }
   ],
   roles: [
-    { role: "cta", produce: { hue: "constant", L: "anchor", chroma: "brand" }, floorL: 0, chromaMult: 1 },
-    { role: "cta-hover", produce: { hue: "constant", L: "hover", chroma: "brand" }, floorL: 0, chromaMult: 1 },
-    { role: "cta-pressed", produce: { hue: "constant", L: "pressed", chroma: "brand" }, floorL: 0, chromaMult: 1 }
+    { role: STAMP_FILL, produce: { hue: "constant", L: "anchor", chroma: "brand" }, floorL: 0, chromaMult: 1 },
+    { role: STAMP_FILL_HOVER, produce: { hue: "constant", L: "hover", chroma: "brand" }, floorL: 0, chromaMult: 1 },
+    { role: STAMP_FILL_PRESSED, produce: { hue: "constant", L: "pressed", chroma: "brand" }, floorL: 0, chromaMult: 1 }
   ],
   ons: ONS
 };
@@ -900,9 +900,9 @@ var DARK = {
     { stop: 11, rootL: ROOT_L_DARK[11], group: groupOf(11), produce: P_TEXT, chromaMult: SCALE_C_DARK[11].textMult, textMaxC: SCALE_C_DARK[11].textMaxC, chromaFloor: SCALE_C_DARK[11].chromaFloor, require: T11 }
   ],
   roles: [
-    { role: "cta", produce: { hue: "constant", L: "anchor", chroma: "brand" }, floorL: DARK_CTA_MIN_L, chromaMult: 1 },
-    { role: "cta-hover", produce: { hue: "constant", L: "hover", chroma: "brand" }, floorL: DARK_CTA_MIN_L, chromaMult: 1 },
-    { role: "cta-pressed", produce: { hue: "constant", L: "pressed", chroma: "brand" }, floorL: DARK_CTA_MIN_L, chromaMult: 1 }
+    { role: STAMP_FILL, produce: { hue: "constant", L: "anchor", chroma: "brand" }, floorL: DARK_CTA_MIN_L, chromaMult: 1 },
+    { role: STAMP_FILL_HOVER, produce: { hue: "constant", L: "hover", chroma: "brand" }, floorL: DARK_CTA_MIN_L, chromaMult: 1 },
+    { role: STAMP_FILL_PRESSED, produce: { hue: "constant", L: "pressed", chroma: "brand" }, floorL: DARK_CTA_MIN_L, chromaMult: 1 }
   ],
   ons: ONS
 };
@@ -2281,6 +2281,8 @@ var toHex = (rgb) => "#" + rgb.map((c) => Math.round(c * 255).toString(16).padSt
 var CTA_CLEARANCE_CAPS = [0.05, 0.92];
 var CHROMATIC_W80_WORST_SHIP_Y = { light: 0.459357, dark: 0.074936 };
 var CHROMATIC_P3_WORST_SHIP_Y = { light: 0.836007, dark: 0.016041 };
+var NEUTRAL_P3_WORST_SHIP_Y = { light: 0.845015, dark: 0.014247 };
+var NEUTRAL_W80_WORST_SHIP_Y = { light: 0.506433, dark: 0.074262 };
 function resolveRamp(hex, mode, spec, opts) {
   const o = hexToOklch(hex);
   const seed = { hex, ...o };
@@ -2292,10 +2294,10 @@ function resolveRamp(hex, mode, spec, opts) {
       stops: spec.stops.map((s) => s.stop === 10 && s.require?.metric === "wcag" ? { ...s, require: { ...s.require, target: 6.5 } } : s)
     };
   }
-  const ctaReq = spec.roles.find((r) => r.role === "cta");
-  const hoverReq = spec.roles.find((r) => r.role === "cta-hover");
-  const pressedReq = spec.roles.find((r) => r.role === "cta-pressed");
-  if (!ctaReq) throw new Error("spec has no cta role");
+  const ctaReq = spec.roles.find((r) => r.role === STAMP_FILL);
+  const hoverReq = spec.roles.find((r) => r.role === STAMP_FILL_HOVER);
+  const pressedReq = spec.roles.find((r) => r.role === STAMP_FILL_PRESSED);
+  if (!ctaReq) throw new Error(`spec has no ${STAMP_FILL} role`);
   const onFillEnforce = ctx.opts?.enforceOnFillContrast ?? spec.ons.onFill.enforce;
   const dctx = mode === "dark" ? buildDarkContext(ctx, ctaReq.floorL) : null;
   const stops = [];
@@ -2314,8 +2316,6 @@ function resolveRamp(hex, mode, spec, opts) {
   const textGround = ctx.opts?.textGround?.[mode];
   const groundOf = (req, stop) => textGround && stop >= 9 ? textGround : refOf(wcagAnchorStop(req, stop), stop);
   const apcaGroundOf = (req, stop) => textGround && stop >= 9 ? textGround : refOf(declaredAnchor(req), stop);
-  const NEUTRAL_P3_WORST_SHIP_Y = { light: 0.845015, dark: 0.014247 };
-  const NEUTRAL_W80_WORST_SHIP_Y = { light: 0.506433, dark: 0.074262 };
   const maxLForOf = (req, forWhom, withMargin) => {
     if (req.metric === "wcag") {
       const g2 = groundOf(req, forWhom);
@@ -2500,13 +2500,13 @@ function resolveRamp(hex, mode, spec, opts) {
         repelled = true;
       }
     }
-    cta = emitRole("cta", light9L, ctaCFor(light9L) * ctaCMul, ctaH);
+    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("cta-hover", hL, hCFor(hL), ctaH);
-    ctaPressed = emitRole("cta-pressed", pL, pCFor(pL), ctaH);
+    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;
@@ -2529,19 +2529,19 @@ function resolveRamp(hex, mode, spec, opts) {
     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)];
-    cta = emitRole("cta", cta9L, dCFor(cta9L), ctx.darkCtaH);
+    cta = emitRole(STAMP_FILL, cta9L, dCFor(cta9L), ctx.darkCtaH);
     {
       const [hL, pL] = dTrio(cta9L);
-      ctaHover = emitRole("cta-hover", hL, dCFor(hL), ctx.darkCtaH);
-      ctaPressed = emitRole("cta-pressed", pL, dCFor(pL), ctx.darkCtaH);
+      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("cta", enforcedL, dCFor(enforcedL), ctx.darkCtaH);
+      cta = emitRole(STAMP_FILL, enforcedL, dCFor(enforcedL), ctx.darkCtaH);
       const [hL, pL] = dTrio(enforcedL);
-      ctaHover = emitRole("cta-hover", hL, dCFor(hL), ctx.darkCtaH);
-      ctaPressed = emitRole("cta-pressed", pL, dCFor(pL), ctx.darkCtaH);
+      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;
@@ -2550,10 +2550,10 @@ function resolveRamp(hex, mode, spec, opts) {
       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("cta", clearedL, dCFor(clearedL), ctx.darkCtaH);
+        cta = emitRole(STAMP_FILL, clearedL, dCFor(clearedL), ctx.darkCtaH);
         const [hL, pL] = dTrio(clearedL);
-        ctaHover = emitRole("cta-hover", hL, dCFor(hL), ctx.darkCtaH);
-        ctaPressed = emitRole("cta-pressed", pL, dCFor(pL), ctx.darkCtaH);
+        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;
@@ -2562,10 +2562,10 @@ function resolveRamp(hex, mode, spec, opts) {
     if (ctx.opts?.ctaSolve) {
       const exitL = solveDarkCtaExit(cta, dCFor, ctx.darkCtaH, ctx.opts.ctaSolve.redDark, enforceLc, coLc);
       if (exitL !== null) {
-        cta = emitRole("cta", exitL, dCFor(exitL), ctx.darkCtaH);
+        cta = emitRole(STAMP_FILL, exitL, dCFor(exitL), ctx.darkCtaH);
         const [hL, pL] = dTrio(exitL);
-        ctaHover = emitRole("cta-hover", hL, dCFor(hL), ctx.darkCtaH);
-        ctaPressed = emitRole("cta-pressed", pL, dCFor(pL), ctx.darkCtaH);
+        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;
@@ -3898,9 +3898,14 @@ function themeToFigma(r, input) {
 // src/engine/requirements/dtcg.ts
 var EXT_KEY = "org.okchroma.requirement";
 var RESOLVER_ID = "okchroma-reqtoken@2";
+var LEGACY_ROLE_NAMES = {
+  "cta": STAMP_FILL,
+  "cta-hover": STAMP_FILL_HOVER,
+  "cta-pressed": STAMP_FILL_PRESSED
+};
 var hexToValue = (hex) => {
   const h = hex.replace("#", "");
-  const c = (i) => parseInt(h.slice(i, i + 2), 16) / 255;
+  const c = (i) => Math.round(parseInt(h.slice(i, i + 2), 16) / 255 * 1e4) / 1e4;
   return { colorSpace: "srgb", components: [c(0), c(2), c(4)], alpha: 1, hex: hex.toLowerCase() };
 };
 function emitDtcgRamp(hex, mode, groupName, spec) {
@@ -3916,9 +3921,9 @@ function emitDtcgRamp(hex, mode, groupName, spec) {
     group[String(sp.stop)] = { $type: "color", $value: hexToValue(st.hex), $extensions: { [EXT_KEY]: { resolver: RESOLVER_ID, seed: seedRef, mode, ...sp } } };
   }
   const roleVal = {
-    "cta": ramp.roles.cta,
-    "cta-hover": ramp.roles.ctaHover,
-    "cta-pressed": ramp.roles.ctaPressed
+    [STAMP_FILL]: ramp.roles.cta,
+    [STAMP_FILL_HOVER]: ramp.roles.ctaHover,
+    [STAMP_FILL_PRESSED]: ramp.roles.ctaPressed
   };
   for (const rr of spec.roles) {
     const rv = roleVal[rr.role];
@@ -3938,6 +3943,7 @@ function parseToken(token) {
   if (isRole) {
     for (const k of ["role", "produce", "floorL", "chromaMult"]) if (req[k] === void 0) throw new Error(`role requirement missing "${k}"`);
   }
+  if (isRole && LEGACY_ROLE_NAMES[req.role]) req.role = LEGACY_ROLE_NAMES[req.role];
   return { req, seedRef: seed, mode };
 }
 function resolveDtcgRamp(group) {

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

@@ -43,6 +43,7 @@ export type ResolvedRamp = {
     };
 };
 export type { ResolveOpts };
+export declare const CTA_CLEARANCE_CAPS: [number, number];
 export declare const CHROMATIC_W80_WORST_SHIP_Y: {
     readonly light: 0.459357;
     readonly dark: 0.074936;
@@ -51,4 +52,12 @@ export declare const CHROMATIC_P3_WORST_SHIP_Y: {
     readonly light: 0.836007;
     readonly dark: 0.016041;
 };
+export declare const NEUTRAL_P3_WORST_SHIP_Y: {
+    readonly light: 0.845015;
+    readonly dark: 0.014247;
+};
+export declare const NEUTRAL_W80_WORST_SHIP_Y: {
+    readonly light: 0.506433;
+    readonly dark: 0.074262;
+};
 export declare function resolveRamp(hex: string, mode: 'light' | 'dark', spec?: ModeSpec, opts?: ResolveOpts): ResolvedRamp;

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

@@ -1,3 +1,4 @@
+import { STAMP_FILL, STAMP_FILL_HOVER, STAMP_FILL_PRESSED } from '../tokenNames';
 export type Group = 'paper' | 'highlighter' | 'crayon' | 'pencil' | 'pen';
 export declare const textLane: (g: string) => boolean;
 export type Producer = {
@@ -31,7 +32,7 @@ export type StopReq = {
     chromaFloor?: number;
     require?: Require;
 };
-export type RoleName = 'cta' | 'cta-hover' | 'cta-pressed';
+export type RoleName = typeof STAMP_FILL | typeof STAMP_FILL_HOVER | typeof STAMP_FILL_PRESSED;
 export type RoleReq = {
     role: RoleName;
     produce: {

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

@@ -1,8 +1,25 @@
 import { type GeneratedScale, type ContrastProfile } from './colorEngine';
 import type { SignalDef } from './signals';
+type Side = {
+    kind: 'swap';
+    note: string;
+    baseHex: string;
+} | {
+    kind: 'shift';
+    note: string;
+} | {
+    kind: 'none';
+};
+interface SignalShiftRule {
+    splitH: number;
+    below: Side;
+    atOrAbove: Side;
+}
+export declare const SHIFT_RULES: Partial<Record<SignalDef['name'], SignalShiftRule>>;
 export interface ShiftResult {
     scale: GeneratedScale;
     note: string;
 }
 export declare function signalSwapVariants(def: SignalDef, contrastProfile?: ContrastProfile): ShiftResult[];
 export declare function pickSignalShift(brand: GeneratedScale, canonicalSignalScale: GeneratedScale, def: SignalDef, contrastProfile?: ContrastProfile): ShiftResult | null;
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "okchroma",
-  "version": "0.2.2",
+  "version": "0.3.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": {
@@ -53,7 +53,8 @@
     "audit:desc": "esbuild scripts/desc-audit.ts --bundle --platform=node --outfile=dist/desc-audit.js && node dist/desc-audit.js",
     "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"
+    "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"
   },
   "devDependencies": {
     "@types/node": "^25.9.2",