okchroma 0.9.0 → 0.9.1

package/README.md

@@ -1,30 +1,18 @@
 # OKChroma
 
-**A color-system engine.** Give it one brand hex, or two, and it resolves a complete set
-of light and dark color primitives whose contrast requirements are solved during
-generation, then emits it as CSS custom properties, as DTCG documents, and as Figma
-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 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.
-
-Contrast is built into the math, not checked afterwards: highlighter reads on every paper at
-3:1 (the non-text bar), pencil at 4.5:1, pen at 4.5:1 on every paper and chalk in
-both directions; the stamp's text passes 4.5:1 on its fill. APCA is used once, as a booster
-that nudges the stamp fill until its text reads at Lc 65. Each claim, its scope, and the audit that
-proves it: [Guarantees](https://egerrity.github.io/okchroma/#/docs/guarantees).
-
-The engine emits primitives only: values it calculates from the seed. Elevation planes,
-shadows, opacity ladders and state layers are a design system's to author on top of these,
-and [docs/agents.md](docs/agents.md) says which primitive each of those decisions reads.
+okchroma is a color engine. A fixed set of formulas generates a color system's base
+tokens from a seed color and a set of options. Each token gets a light and a dark value,
+and the contrast requirements are solved while the values are generated. The set is
+emitted as CSS custom properties, as DTCG documents, and as Figma variables.
 
-> 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 touch the math; the color computation is original.
+The seed is one brand hex. The options add a second seed or derive a companion from the
+first, pin a family's fill to a lightness anchor, and pick the contrast profile. They are
+listed with the API: [Install and API](https://egerrity.github.io/okchroma/#/docs/install).
+
+okchroma writes base tokens, designed for use under any semantic layer, including one
+that must cover many themes. It writes no semantic tokens. The semantic tokens in this
+repo, in [demo/semantic.css](demo/semantic.css), style the demo site and are not engine
+output.
 
 ## Install
 
@@ -32,8 +20,9 @@ and [docs/agents.md](docs/agents.md) says which primitive each of those decision
 npm install okchroma
 ```
 
-ESM and CommonJS builds with TypeScript declarations; no runtime dependencies (the one
-perceptual-distance library the engine uses is bundled in). Node 18 or later; no DOM.
+The package ships ESM and CommonJS builds with TypeScript declarations. It has no
+runtime dependencies: the one library the engine uses, for perceptual color distance, is
+bundled at build time. Node 18 or later; no DOM.
 
 ```ts
 import { resolveTheme, brandCss, signalsCss, themeTokens, tokensToDtcg, neutralTintHue } from 'okchroma'
@@ -58,107 +47,149 @@ const { light, dark } = tokensToDtcg(tokens)
 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).
 
-## What it emits
-
-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-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-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
-writing UI against these: [docs/agents.md](docs/agents.md). The scale and its declared
-targets: [docs/scale.md](docs/scale.md).
-
-**The stops.** The instrument word is the job, the number is 100 minus the light-mode
-lightness target, and bigger is stronger. Papers are backgrounds; chalks are decorative
-borders and illustration, never text; the highlighter is the non-text contrast stop (focus
-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-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.
-
-**The outputs.**
-
-- CSS: `brandCss` writes `[data-brand="acme"]` and `[data-brand="acme"][data-theme="dark"]`
-  blocks, `signalsCss` the brand-independent signal block at `:root`. Values are sRGB
-  hexes (or `rgba()` where a token carries alpha); stops whose chroma exceeds sRGB get a
-  `color(display-p3 …)` override behind a browser gate. The repo's `npm run generate`
-  writes the signal block to `dist/signals.css`.
-- The structured emit: `themeTokens` reads the CSS emission back into one object per
-  mode with every reference resolved, for consumers with no cascade.
-- DTCG: `tokensToDtcg` returns one Design Tokens Format Module 2025.10 document per mode,
-  every token with `$type`, an sRGB `$value` whose components and hex are the same 8-bit
-  color (or an alias where the CSS writes a reference), and a `$description`. The two join
-  through a resolver document. The format: [docs/schema.md](docs/schema.md). The repo's
-  `npm run tokens:emit -- '#E93D82' acme` writes both files. Pass `{ rootGroup: 'color' }`,
-  or `--root color` to the script, to nest every path and alias under that group.
-- Figma: `themeToFigma` returns a light and a dark group tree on the same paths; the
-  extended plugin writes it into a file.
+## The tokens
+
+Every family emits the same set of names, so a name says the token's job whichever
+family carries it. The families are `neutral`, `brand`, `brand-alt`, `critical`,
+`warning`, `positive` and `info`; the neutral adds the two poles. The link rows and the
+seeds sit outside the families.
+
+| Token | Job | Contrast guarantee |
+|---|---|---|
+| `{family}/paper-1` | background | none; the contrast stops are measured against the papers |
+| `{family}/paper-3` | background | none |
+| `{family}/paper-5` | background; the paper the contrast stops are solved against | none |
+| `{family}/chalk-8` | decorative border, illustration, ground for inverted text; never text | none; the pens are measured against the chalks |
+| `{family}/chalk-11` | the same | none |
+| `{family}/chalk-15` | the same | none |
+| `{family}/chalk-20` | the same | none |
+| `{family}/highlighter-26` | focus ring, icon, large text; at a translucency, the state layer | 3:1 on the papers, the non-text bar |
+| `{family}/pencil-47` | regular text; the emphasis fill | 4.5:1 on the papers |
+| `{family}/pen-58` | text; inverted background | 4.5:1 on the papers and the chalks, both directions |
+| `{family}/pen-70` | heavy-emphasis text; inverted background | 4.5:1 on the papers and the chalks, both directions |
+| `neutral/paper-0` | white in light; in dark, the plane one seam below `paper-1` | none stated |
+| `neutral/pen-100` | black in light, white in dark; the strongest text | none stated |
+| `{family}/stamp-0` | the call-to-action fill at rest, solved per family and mode | `stamp-on` reads on it at 4.5:1 |
+| `{family}/stamp-1` | the fill one step from rest | `stamp-on` reads on it at 4.5:1 |
+| `{family}/stamp-2` | the fill two steps from rest | `stamp-on` reads on it at 4.5:1 |
+| `{family}/stamp-edge` | a stroke: an offset where the fill sits close to the page, transparent elsewhere, so a component always renders it | none stated |
+| `{family}/stamp-on` | the text on the fill, whichever pole passes; at alpha on a quiet fill | 4.5:1 on the three fills |
+| `link/default-0` | link text on the papers, at rest | none stated |
+| `link/default-1` | one step from rest | none stated |
+| `link/default-2` | two steps from rest | none stated |
+| `link/inverse-0` | link text on the pen ground, at rest | none stated |
+| `link/inverse-1` | one step from rest | none stated |
+| `link/inverse-2` | two steps from rest | none stated |
+| `absolute/brand` | the seed as given; a reference value, not a UI color | none stated |
+| `absolute/brand-alt` | the second seed as given | none stated |
+
+The papers and chalks a stop is measured against are its own family's and the neutral's.
+APCA is used once: the stamp fill also moves until its text clears Lc 65. The full
+claims and their audits: [Guarantees](https://egerrity.github.io/okchroma/#/docs/guarantees).
+The lightness targets behind the numbers: [docs/scale.md](docs/scale.md).
 
-## Run from source
+> 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 touch the math; the color computation is original.
+
+## The grammar
+
+A name is a group and a leaf:
 
-```bash
-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
+```
+group/leaf
 ```
 
-`npm run typecheck` runs the compiler; the audit gates (`npm run req:audit`,
-`npm run audit:guarantee`, `npm run audit:dtcg`, 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).
+The group is a family, `link`, or `absolute`. The leaf names a position, never a state;
+a consumer's semantic layer names the states and aliases the positions.
+
+| Leaf | Pattern | Example |
+|---|---|---|
+| a scale stop | `{instrument}-{number}` | `pen-58` |
+| a stamp fill | `stamp-{step}` | `stamp-0` |
+| the stamp's edge and text | `stamp-edge`, `stamp-on` | `stamp-on` |
+| a link | `{posture}-{step}`, the postures `default` and `inverse` | `default-1` |
+| a seed | the family word | `brand-alt` |
+
+The instrument is the job. On the scale (paper, chalk, highlighter, pencil, pen) the
+number is 100 minus the light-mode lightness target, so a bigger number is a stronger
+color. In the brand identity (stamp, link) the number is the step from rest: 0 at rest,
+1 one step away, 2 two steps.
+
+Each output spells the same name its own way:
+
+| Output | Spelling | `brand/stamp-0` becomes |
+|---|---|---|
+| CSS custom property | `--group-leaf` | `--brand-stamp-0` |
+| Figma variable | `group/leaf`; the extended plugin writes it under `color/` | `color/brand/stamp-0` |
+| DTCG token | nested as `group.leaf`, referenced as `{group.leaf}`; `rootGroup: 'color'` nests it under `color` | `{brand.stamp-0}` |
+
+Which token to use for which job: [docs/agents.md](docs/agents.md).
+
+## The outputs
+
+- CSS: `brandCss` writes a `[data-brand="your-brand"]` block and a
+  `[data-brand="your-brand"][data-theme="dark"]` block; `signalsCss` writes the
+  brand-independent signal block at `:root`. Values are sRGB hexes, or `rgba()` where a
+  token carries alpha. A stop whose chroma exceeds sRGB gets a `color(display-p3 …)`
+  override behind a browser gate. In the repo, `npm run generate` writes the signal block
+  to `dist/signals.css`.
+- Objects: `themeTokens` returns one object per mode with every reference resolved, for a
+  consumer with no cascade.
+- DTCG: `tokensToDtcg` returns one document per mode. Each token has a `$type`, an sRGB
+  `$value` (or an alias where the CSS writes a reference) and a `$description`; a
+  resolver document joins the two modes. The format: [docs/schema.md](docs/schema.md).
+  In the repo, `npm run tokens:emit -- '#E93D82' your-brand` writes both files; `--root color`
+  (or `{ rootGroup: 'color' }` in code) nests the paths under that group.
+- Figma: `themeToFigma` returns a light and a dark group tree on the same paths; the
+  extended plugin writes them into a file.
 
 ## Documentation
 
 The docs site renders the mechanisms with live values from the engine:
 [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.
+- [Overview](https://egerrity.github.io/okchroma/#/docs/overview): the input the engine needs, and the token roster it makes from it.
 - [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.
+- [Guarantees](https://egerrity.github.io/okchroma/#/docs/guarantees): each claim as stated, 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) and the [Reference](https://egerrity.github.io/okchroma/#/docs/reference): glossary, constants, option types.
 
-In the repo: [docs/agents.md](docs/agents.md) (the consumer contract: what every token
-means and the rules for using it), [docs/schema.md](docs/schema.md) (the DTCG documents),
-[docs/scale.md](docs/scale.md) (the scale and its declared targets),
-[docs/architecture.md](docs/architecture.md) (the maintainer's map: modules, pipeline
-stages, data structures, the extended plugin's write path), and
-[CHANGELOG.md](CHANGELOG.md).
+In the repo:
+
+- [docs/agents.md](docs/agents.md): the consumer contract, what each token means and the rules for using it.
+- [docs/schema.md](docs/schema.md): the DTCG documents.
+- [docs/scale.md](docs/scale.md): the scale and its declared targets.
+- [docs/architecture.md](docs/architecture.md): the maintainer's map, modules, pipeline stages, data structures, the extended plugin's write path.
+- [CHANGELOG.md](CHANGELOG.md).
+
+## Run from source
+
+```bash
+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
+```
+
+`npm run typecheck` runs the compiler. The audit scripts in `package.json`
+(`npm run req:audit`, `npm run audit:guarantee`, `npm run audit:dtcg`, and the rest)
+check the guarantees and the outputs. What each proves:
+[How it is verified](https://egerrity.github.io/okchroma/#/docs/guarantees/how-it-is-verified).
 
 ## 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
+- OKChroma Extended (`plugin-ext/`) is the shipped Figma plugin. It needs the Figma
+  desktop app and a Figma Enterprise plan, because it writes extended variable
+  collections: one collection with light and dark modes, and an 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
+- OKChroma (`plugin/`, the community plugin) is not offered for download. It has no
+  rename table for the last scale change, so updating an installed copy would leave the
+  old names in the file. It builds 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
 
 MIT

package/dist-lib/index.cjs

@@ -114,13 +114,13 @@ function stateStepL(restL, _mode, k) {
 }
 var OVERRIDE_LIGHT_BELOW = ARCHETYPES.find((a) => a.name === "rich").min;
 var OVERRIDE_DARK_ABOVE = ARCHETYPES.find((a) => a.name === "light").min;
-function stateFillL(restL, mode, k) {
+function stateFillL(restL, mode, k, keepsPole) {
   const natural = mode === "dark" ? 1 : -1;
   const overridden = mode === "light" ? restL < OVERRIDE_LIGHT_BELOW : restL > OVERRIDE_DARK_ABOVE;
   const preferred = overridden ? -natural : natural;
   const fits = (d) => {
     const p = restL + d * stateStepL(restL, mode, 2);
-    return p >= STATE_L_MIN && p <= STATE_L_MAX;
+    return p >= STATE_L_MIN && p <= STATE_L_MAX && (keepsPole?.(p) ?? true);
   };
   const dir = fits(preferred) ? preferred : fits(-preferred) ? -preferred : preferred;
   const L = restL + dir * stateStepL(restL, mode, k);
@@ -2224,6 +2224,20 @@ function ctaDarkDualGateL(base, darkH, onFillTextIsWhite, enforce, coLc, capLoL,
   const lLc = findLForBlackTextLc(startL, C2, darkH, coLc + APCA_SOLVE_MARGIN_LC, capHiL);
   return Math.max(l45, Math.min(lLc, capHiL));
 }
+function stepKeepsPole(mode, white, chromaAt, H2, law) {
+  if (mode === "light") return void 0;
+  if (law.enforceLc !== void 0) {
+    const bar = law.enforceLc;
+    const lcAt = white ? whiteTextLcAt : blackTextLcAt;
+    return (L) => lcAt(L, chromaAt(L), H2) >= bar;
+  }
+  if (law.ratioFloor === void 0) return void 0;
+  const floor = law.ratioFloor, poleY = white ? 1 : 0;
+  return (L) => {
+    const C2 = clampChromaToGamut(L, chromaAt(L), H2);
+    return Math.min(legalRatio(L, C2, H2, poleY), contrastRatio(shippedY(L, C2, H2), poleY)) >= floor;
+  };
+}
 function onFillIsWhiteDarkAt(L, C2, H2, enforce, ratioFloor) {
   return onTextIsWhite(apcaYAt(L, C2, H2), L, C2, H2, enforce, ratioFloor);
 }
@@ -2506,7 +2520,8 @@ function resolveRamp(hex, mode, spec, opts) {
   const enforceLc = spec.ons.onFill.enforceLc;
   const coLc = ctx.opts?.apcaClearance && enforceLc === void 0 ? ctx.opts.apcaClearanceLc ?? spec.ons.onFill.coEnforceLc : void 0;
   const onFloor = enforceLc !== void 0 ? void 0 : spec.ons.onFill.ratioFloor;
-  let cta, ctaHover, ctaPressed, onFillIsWhite;
+  let cta, onFillIsWhite;
+  let stateC, stateH;
   if (mode === "light") {
     onFillIsWhite = onFillIsWhiteLight(ctx, enforceLc !== void 0 ? false : onFillEnforce);
     let light9L = enforceLc !== void 0 ? ctaLightLApca(ctx, onFillIsWhite, onFillEnforce, enforceLc) : ctaLightL(ctx, onFillIsWhite, onFillEnforce);
@@ -2538,21 +2553,14 @@ function resolveRamp(hex, mode, spec, opts) {
       }
     }
     cta = emitRole(STAMP_FILL, light9L, ctaCFor(light9L) * ctaCMul, ctaH);
-    const hCFor = (L) => ctx.cAt("light", L, (hoverReq?.chromaMult ?? 1) * ctx.brandC) * ctaCMul;
-    const pCFor = (L) => ctx.cAt("light", L, (pressedReq?.chromaMult ?? 1) * ctx.brandC) * ctaCMul;
-    const hL = stateFillL(light9L, "light", 1);
-    const pL = stateFillL(light9L, "light", 2);
-    ctaHover = emitRole(STAMP_FILL_HOVER, hL, hCFor(hL), ctaH);
-    ctaPressed = emitRole(STAMP_FILL_PRESSED, pL, pCFor(pL), ctaH);
-    if (light9L !== ctx.scaleL) {
-      cta.enforced = true;
-      ctaHover.enforced = true;
-      ctaPressed.enforced = true;
-    }
+    stateC = {
+      hover: (L) => ctx.cAt("light", L, (hoverReq?.chromaMult ?? 1) * ctx.brandC) * ctaCMul,
+      pressed: (L) => ctx.cAt("light", L, (pressedReq?.chromaMult ?? 1) * ctx.brandC) * ctaCMul
+    };
+    stateH = ctaH;
+    if (light9L !== ctx.scaleL) cta.enforced = true;
     if (repelled) {
       cta.repelled = true;
-      ctaHover.repelled = true;
-      ctaPressed.repelled = true;
       onFillIsWhite = onFillIsWhiteDarkAt(
         cta.L,
         cta.C,
@@ -2565,50 +2573,29 @@ function resolveRamp(hex, mode, spec, opts) {
     const d = dctx;
     const cta9L = ctx.opts?.darkCtaFlatApp !== void 0 ? flatDarkCtaL(d, (L) => ctx.cAt("dark", L, d.darkC9), ctx.darkCtaH, ctx.opts.darkCtaFlatApp) : d.dark9L;
     const dCFor = (L) => ctx.cAt("dark", L, d.darkC9);
-    const dTrio = (baseL) => [stateFillL(baseL, "dark", 1), stateFillL(baseL, "dark", 2)];
+    stateC = { hover: dCFor, pressed: dCFor };
+    stateH = ctx.darkCtaH;
     cta = emitRole(STAMP_FILL, cta9L, dCFor(cta9L), ctx.darkCtaH);
-    {
-      const [hL, pL] = dTrio(cta9L);
-      ctaHover = emitRole(STAMP_FILL_HOVER, hL, dCFor(hL), ctx.darkCtaH);
-      ctaPressed = emitRole(STAMP_FILL_PRESSED, pL, dCFor(pL), ctx.darkCtaH);
-    }
     onFillIsWhite = onFillIsWhiteDarkAt(cta.L, cta.C, cta.H, enforceLc !== void 0 ? false : onFillEnforce);
     const enforcedL = enforceLc !== void 0 ? ctaDarkEnforcedLApca(ctx, cta, onFillIsWhite, onFillEnforce, enforceLc) : ctaDarkEnforcedL(ctx, cta, onFillIsWhite, onFillEnforce);
     if (enforcedL !== null) {
       cta = emitRole(STAMP_FILL, enforcedL, dCFor(enforcedL), ctx.darkCtaH);
-      const [hL, pL] = dTrio(enforcedL);
-      ctaHover = emitRole(STAMP_FILL_HOVER, hL, dCFor(hL), ctx.darkCtaH);
-      ctaPressed = emitRole(STAMP_FILL_PRESSED, pL, dCFor(pL), ctx.darkCtaH);
       cta.enforced = true;
-      ctaHover.enforced = true;
-      ctaPressed.enforced = true;
     }
     if (coLc !== void 0) {
       const [capLoL, capHiL] = CTA_CLEARANCE_CAPS;
       const clearedL = ctaDarkDualGateL(cta, ctx.darkCtaH, onFillIsWhite, onFillEnforce, coLc + APCA_ENFORCE_MARGIN_LC, capLoL, capHiL);
       if (Math.abs(clearedL - cta.L) > 1e-9) {
         cta = emitRole(STAMP_FILL, clearedL, dCFor(clearedL), ctx.darkCtaH);
-        const [hL, pL] = dTrio(clearedL);
-        ctaHover = emitRole(STAMP_FILL_HOVER, hL, dCFor(hL), ctx.darkCtaH);
-        ctaPressed = emitRole(STAMP_FILL_PRESSED, pL, dCFor(pL), ctx.darkCtaH);
         cta.enforced = true;
-        ctaHover.enforced = true;
-        ctaPressed.enforced = true;
       }
     }
     if (ctx.opts?.ctaSolve) {
       const exitL = solveDarkCtaExit(cta, dCFor, ctx.darkCtaH, ctx.opts.ctaSolve.redDark, enforceLc, coLc);
       if (exitL !== null) {
         cta = emitRole(STAMP_FILL, exitL, dCFor(exitL), ctx.darkCtaH);
-        const [hL, pL] = dTrio(exitL);
-        ctaHover = emitRole(STAMP_FILL_HOVER, hL, dCFor(hL), ctx.darkCtaH);
-        ctaPressed = emitRole(STAMP_FILL_PRESSED, pL, dCFor(pL), ctx.darkCtaH);
         cta.enforced = true;
-        ctaHover.enforced = true;
-        ctaPressed.enforced = true;
         cta.repelled = true;
-        ctaHover.repelled = true;
-        ctaPressed.repelled = true;
         onFillIsWhite = onFillIsWhiteDarkAt(
           cta.L,
           cta.C,
@@ -2624,6 +2611,19 @@ function resolveRamp(hex, mode, spec, opts) {
     const other = legalRatio(cta.L, cta.C, cta.H, onFillIsWhite ? 0 : 1);
     if (chosen < onFloor && other >= onFloor) onFillIsWhite = !onFillIsWhite;
   }
+  const keepsPole = stepKeepsPole(mode, onFillIsWhite, stateC.pressed, stateH, { ratioFloor: onFloor, enforceLc });
+  const hL = stateFillL(cta.L, mode, 1, keepsPole);
+  const pL = stateFillL(cta.L, mode, 2, keepsPole);
+  const ctaHover = emitRole(STAMP_FILL_HOVER, hL, stateC.hover(hL), stateH);
+  const ctaPressed = emitRole(STAMP_FILL_PRESSED, pL, stateC.pressed(pL), stateH);
+  if (cta.enforced) {
+    ctaHover.enforced = true;
+    ctaPressed.enforced = true;
+  }
+  if (cta.repelled) {
+    ctaHover.repelled = true;
+    ctaPressed.repelled = true;
+  }
   return { mode, seed, stops, roles: { cta, ctaHover, ctaPressed }, ons: { onFillIsWhite } };
 }
 
@@ -2706,18 +2706,18 @@ function generateNeutralScale(brandH, level = "default", contrastProfile) {
   if (popLift > 1e-6) {
     scale.ctaDark = makeStop(9, scale.dark[3].L + popLift, scale.dark[3].C, scale.dark[3].H);
   }
-  const nState = (stop, mode, rest, k) => {
-    const L = stateFillL(rest.L, mode, k);
-    return makeStop(stop, L, curve(L, mode), rest.H);
-  };
-  scale.ctaHover = nState(10, "light", scale.cta, 1);
-  scale.ctaPressed = nState(11, "light", scale.cta, 2);
-  scale.ctaHoverDark = nState(10, "dark", scale.ctaDark, 1);
-  scale.ctaPressedDark = nState(11, "dark", scale.ctaDark, 2);
   const onEnforce = contrastProfile !== "apca";
   const onFloor = 4.5;
   scale.onFillTextIsWhite = onTextIsWhite(apcaY(scale.cta.r, scale.cta.g, scale.cta.b), scale.cta.L, scale.cta.C, scale.cta.H, onEnforce, onFloor);
   scale.onFillTextIsWhiteDark = onTextIsWhite(apcaY(scale.ctaDark.r, scale.ctaDark.g, scale.ctaDark.b), scale.ctaDark.L, scale.ctaDark.C, scale.ctaDark.H, onEnforce, onFloor);
+  const nState = (stop, mode, rest, k, white) => {
+    const L = stateFillL(rest.L, mode, k, stepKeepsPole(mode, white, (l) => curve(l, mode), rest.H, { ratioFloor: onFloor }));
+    return makeStop(stop, L, curve(L, mode), rest.H);
+  };
+  scale.ctaHover = nState(10, "light", scale.cta, 1, scale.onFillTextIsWhite);
+  scale.ctaPressed = nState(11, "light", scale.cta, 2, scale.onFillTextIsWhite);
+  scale.ctaHoverDark = nState(10, "dark", scale.ctaDark, 1, scale.onFillTextIsWhiteDark);
+  scale.ctaPressedDark = nState(11, "dark", scale.ctaDark, 2, scale.onFillTextIsWhiteDark);
   return scale;
 }
 function generateSubtleSecondary(hex, opts) {
@@ -2730,10 +2730,6 @@ function generateSubtleSecondary(hex, opts) {
   });
   const asCta = (stop, src) => makeStop(stop, src.L, src.C, src.H);
   const mk = (stop, L, mode) => makeStop(stop, L, curve(L, mode), scale.brandH);
-  const st = (stop, mode, rest, k) => {
-    const L = stateFillL(rest.L, mode, k);
-    return makeStop(stop, L, curve(L, mode), rest.H);
-  };
   if (opts?.ctaL) {
     scale.cta = mk(9, opts.ctaL.light, "light");
     scale.ctaDark = mk(9, opts.ctaL.dark, "dark");
@@ -2741,14 +2737,18 @@ function generateSubtleSecondary(hex, opts) {
     scale.cta = asCta(9, scale.light[3]);
     scale.ctaDark = asCta(9, scale.dark[3]);
   }
-  scale.ctaHover = st(10, "light", scale.cta, 1);
-  scale.ctaPressed = st(11, "light", scale.cta, 2);
-  scale.ctaHoverDark = st(10, "dark", scale.ctaDark, 1);
-  scale.ctaPressedDark = st(11, "dark", scale.ctaDark, 2);
   const onEnforce = opts?.contrastProfile !== "apca";
   const onFloor = 4.5;
   scale.onFillTextIsWhite = onTextIsWhite(apcaY(scale.cta.r, scale.cta.g, scale.cta.b), scale.cta.L, scale.cta.C, scale.cta.H, onEnforce, onFloor);
   scale.onFillTextIsWhiteDark = onTextIsWhite(apcaY(scale.ctaDark.r, scale.ctaDark.g, scale.ctaDark.b), scale.ctaDark.L, scale.ctaDark.C, scale.ctaDark.H, onEnforce, onFloor);
+  const st = (stop, mode, rest, k, white) => {
+    const L = stateFillL(rest.L, mode, k, stepKeepsPole(mode, white, (l) => curve(l, mode), rest.H, { ratioFloor: onFloor }));
+    return makeStop(stop, L, curve(L, mode), rest.H);
+  };
+  scale.ctaHover = st(10, "light", scale.cta, 1, scale.onFillTextIsWhite);
+  scale.ctaPressed = st(11, "light", scale.cta, 2, scale.onFillTextIsWhite);
+  scale.ctaHoverDark = st(10, "dark", scale.ctaDark, 1, scale.onFillTextIsWhiteDark);
+  scale.ctaPressedDark = st(11, "dark", scale.ctaDark, 2, scale.onFillTextIsWhiteDark);
   return scale;
 }
 
@@ -3324,11 +3324,12 @@ function escapeCtaFamily(nScale, mode, contrastProfile) {
   if (!strongText) throw new Error("escapeCtaFamily: the neutral scale has no ink-11 stop");
   const mk = (stop, L) => makeStop(stop, L, strongText.C, strongText.H);
   const cta = mk(9, strongText.L);
-  const ctaHover = mk(10, stateFillL(strongText.L, mode, 1));
-  const ctaPressed = mk(11, stateFillL(strongText.L, mode, 2));
   const onEnforce = contrastProfile !== "apca";
   const onFloor = contrastProfile === "apca" ? void 0 : 4.5;
   const onFillIsWhite = onTextIsWhite(apcaY(cta.r, cta.g, cta.b), cta.L, cta.C, cta.H, onEnforce, onFloor);
+  const keepsPole = stepKeepsPole(mode, onFillIsWhite, () => strongText.C, strongText.H, { ratioFloor: onFloor });
+  const ctaHover = mk(10, stateFillL(strongText.L, mode, 1, keepsPole));
+  const ctaPressed = mk(11, stateFillL(strongText.L, mode, 2, keepsPole));
   return { cta, ctaHover, ctaPressed, onFillIsWhite };
 }
 var SECONDARY_DISTINCT_DELTA_E = 0.12;

package/dist-lib/index.mjs

@@ -21,13 +21,13 @@ function stateStepL(restL, _mode, k) {
 }
 var OVERRIDE_LIGHT_BELOW = ARCHETYPES.find((a) => a.name === "rich").min;
 var OVERRIDE_DARK_ABOVE = ARCHETYPES.find((a) => a.name === "light").min;
-function stateFillL(restL, mode, k) {
+function stateFillL(restL, mode, k, keepsPole) {
   const natural = mode === "dark" ? 1 : -1;
   const overridden = mode === "light" ? restL < OVERRIDE_LIGHT_BELOW : restL > OVERRIDE_DARK_ABOVE;
   const preferred = overridden ? -natural : natural;
   const fits = (d) => {
     const p = restL + d * stateStepL(restL, mode, 2);
-    return p >= STATE_L_MIN && p <= STATE_L_MAX;
+    return p >= STATE_L_MIN && p <= STATE_L_MAX && (keepsPole?.(p) ?? true);
   };
   const dir = fits(preferred) ? preferred : fits(-preferred) ? -preferred : preferred;
   const L = restL + dir * stateStepL(restL, mode, k);
@@ -2131,6 +2131,20 @@ function ctaDarkDualGateL(base, darkH, onFillTextIsWhite, enforce, coLc, capLoL,
   const lLc = findLForBlackTextLc(startL, C2, darkH, coLc + APCA_SOLVE_MARGIN_LC, capHiL);
   return Math.max(l45, Math.min(lLc, capHiL));
 }
+function stepKeepsPole(mode, white, chromaAt, H2, law) {
+  if (mode === "light") return void 0;
+  if (law.enforceLc !== void 0) {
+    const bar = law.enforceLc;
+    const lcAt = white ? whiteTextLcAt : blackTextLcAt;
+    return (L) => lcAt(L, chromaAt(L), H2) >= bar;
+  }
+  if (law.ratioFloor === void 0) return void 0;
+  const floor = law.ratioFloor, poleY = white ? 1 : 0;
+  return (L) => {
+    const C2 = clampChromaToGamut(L, chromaAt(L), H2);
+    return Math.min(legalRatio(L, C2, H2, poleY), contrastRatio(shippedY(L, C2, H2), poleY)) >= floor;
+  };
+}
 function onFillIsWhiteDarkAt(L, C2, H2, enforce, ratioFloor) {
   return onTextIsWhite(apcaYAt(L, C2, H2), L, C2, H2, enforce, ratioFloor);
 }
@@ -2413,7 +2427,8 @@ function resolveRamp(hex, mode, spec, opts) {
   const enforceLc = spec.ons.onFill.enforceLc;
   const coLc = ctx.opts?.apcaClearance && enforceLc === void 0 ? ctx.opts.apcaClearanceLc ?? spec.ons.onFill.coEnforceLc : void 0;
   const onFloor = enforceLc !== void 0 ? void 0 : spec.ons.onFill.ratioFloor;
-  let cta, ctaHover, ctaPressed, onFillIsWhite;
+  let cta, onFillIsWhite;
+  let stateC, stateH;
   if (mode === "light") {
     onFillIsWhite = onFillIsWhiteLight(ctx, enforceLc !== void 0 ? false : onFillEnforce);
     let light9L = enforceLc !== void 0 ? ctaLightLApca(ctx, onFillIsWhite, onFillEnforce, enforceLc) : ctaLightL(ctx, onFillIsWhite, onFillEnforce);
@@ -2445,21 +2460,14 @@ function resolveRamp(hex, mode, spec, opts) {
       }
     }
     cta = emitRole(STAMP_FILL, light9L, ctaCFor(light9L) * ctaCMul, ctaH);
-    const hCFor = (L) => ctx.cAt("light", L, (hoverReq?.chromaMult ?? 1) * ctx.brandC) * ctaCMul;
-    const pCFor = (L) => ctx.cAt("light", L, (pressedReq?.chromaMult ?? 1) * ctx.brandC) * ctaCMul;
-    const hL = stateFillL(light9L, "light", 1);
-    const pL = stateFillL(light9L, "light", 2);
-    ctaHover = emitRole(STAMP_FILL_HOVER, hL, hCFor(hL), ctaH);
-    ctaPressed = emitRole(STAMP_FILL_PRESSED, pL, pCFor(pL), ctaH);
-    if (light9L !== ctx.scaleL) {
-      cta.enforced = true;
-      ctaHover.enforced = true;
-      ctaPressed.enforced = true;
-    }
+    stateC = {
+      hover: (L) => ctx.cAt("light", L, (hoverReq?.chromaMult ?? 1) * ctx.brandC) * ctaCMul,
+      pressed: (L) => ctx.cAt("light", L, (pressedReq?.chromaMult ?? 1) * ctx.brandC) * ctaCMul
+    };
+    stateH = ctaH;
+    if (light9L !== ctx.scaleL) cta.enforced = true;
     if (repelled) {
       cta.repelled = true;
-      ctaHover.repelled = true;
-      ctaPressed.repelled = true;
       onFillIsWhite = onFillIsWhiteDarkAt(
         cta.L,
         cta.C,
@@ -2472,50 +2480,29 @@ function resolveRamp(hex, mode, spec, opts) {
     const d = dctx;
     const cta9L = ctx.opts?.darkCtaFlatApp !== void 0 ? flatDarkCtaL(d, (L) => ctx.cAt("dark", L, d.darkC9), ctx.darkCtaH, ctx.opts.darkCtaFlatApp) : d.dark9L;
     const dCFor = (L) => ctx.cAt("dark", L, d.darkC9);
-    const dTrio = (baseL) => [stateFillL(baseL, "dark", 1), stateFillL(baseL, "dark", 2)];
+    stateC = { hover: dCFor, pressed: dCFor };
+    stateH = ctx.darkCtaH;
     cta = emitRole(STAMP_FILL, cta9L, dCFor(cta9L), ctx.darkCtaH);
-    {
-      const [hL, pL] = dTrio(cta9L);
-      ctaHover = emitRole(STAMP_FILL_HOVER, hL, dCFor(hL), ctx.darkCtaH);
-      ctaPressed = emitRole(STAMP_FILL_PRESSED, pL, dCFor(pL), ctx.darkCtaH);
-    }
     onFillIsWhite = onFillIsWhiteDarkAt(cta.L, cta.C, cta.H, enforceLc !== void 0 ? false : onFillEnforce);
     const enforcedL = enforceLc !== void 0 ? ctaDarkEnforcedLApca(ctx, cta, onFillIsWhite, onFillEnforce, enforceLc) : ctaDarkEnforcedL(ctx, cta, onFillIsWhite, onFillEnforce);
     if (enforcedL !== null) {
       cta = emitRole(STAMP_FILL, enforcedL, dCFor(enforcedL), ctx.darkCtaH);
-      const [hL, pL] = dTrio(enforcedL);
-      ctaHover = emitRole(STAMP_FILL_HOVER, hL, dCFor(hL), ctx.darkCtaH);
-      ctaPressed = emitRole(STAMP_FILL_PRESSED, pL, dCFor(pL), ctx.darkCtaH);
       cta.enforced = true;
-      ctaHover.enforced = true;
-      ctaPressed.enforced = true;
     }
     if (coLc !== void 0) {
       const [capLoL, capHiL] = CTA_CLEARANCE_CAPS;
       const clearedL = ctaDarkDualGateL(cta, ctx.darkCtaH, onFillIsWhite, onFillEnforce, coLc + APCA_ENFORCE_MARGIN_LC, capLoL, capHiL);
       if (Math.abs(clearedL - cta.L) > 1e-9) {
         cta = emitRole(STAMP_FILL, clearedL, dCFor(clearedL), ctx.darkCtaH);
-        const [hL, pL] = dTrio(clearedL);
-        ctaHover = emitRole(STAMP_FILL_HOVER, hL, dCFor(hL), ctx.darkCtaH);
-        ctaPressed = emitRole(STAMP_FILL_PRESSED, pL, dCFor(pL), ctx.darkCtaH);
         cta.enforced = true;
-        ctaHover.enforced = true;
-        ctaPressed.enforced = true;
       }
     }
     if (ctx.opts?.ctaSolve) {
       const exitL = solveDarkCtaExit(cta, dCFor, ctx.darkCtaH, ctx.opts.ctaSolve.redDark, enforceLc, coLc);
       if (exitL !== null) {
         cta = emitRole(STAMP_FILL, exitL, dCFor(exitL), ctx.darkCtaH);
-        const [hL, pL] = dTrio(exitL);
-        ctaHover = emitRole(STAMP_FILL_HOVER, hL, dCFor(hL), ctx.darkCtaH);
-        ctaPressed = emitRole(STAMP_FILL_PRESSED, pL, dCFor(pL), ctx.darkCtaH);
         cta.enforced = true;
-        ctaHover.enforced = true;
-        ctaPressed.enforced = true;
         cta.repelled = true;
-        ctaHover.repelled = true;
-        ctaPressed.repelled = true;
         onFillIsWhite = onFillIsWhiteDarkAt(
           cta.L,
           cta.C,
@@ -2531,6 +2518,19 @@ function resolveRamp(hex, mode, spec, opts) {
     const other = legalRatio(cta.L, cta.C, cta.H, onFillIsWhite ? 0 : 1);
     if (chosen < onFloor && other >= onFloor) onFillIsWhite = !onFillIsWhite;
   }
+  const keepsPole = stepKeepsPole(mode, onFillIsWhite, stateC.pressed, stateH, { ratioFloor: onFloor, enforceLc });
+  const hL = stateFillL(cta.L, mode, 1, keepsPole);
+  const pL = stateFillL(cta.L, mode, 2, keepsPole);
+  const ctaHover = emitRole(STAMP_FILL_HOVER, hL, stateC.hover(hL), stateH);
+  const ctaPressed = emitRole(STAMP_FILL_PRESSED, pL, stateC.pressed(pL), stateH);
+  if (cta.enforced) {
+    ctaHover.enforced = true;
+    ctaPressed.enforced = true;
+  }
+  if (cta.repelled) {
+    ctaHover.repelled = true;
+    ctaPressed.repelled = true;
+  }
   return { mode, seed, stops, roles: { cta, ctaHover, ctaPressed }, ons: { onFillIsWhite } };
 }
 
@@ -2613,18 +2613,18 @@ function generateNeutralScale(brandH, level = "default", contrastProfile) {
   if (popLift > 1e-6) {
     scale.ctaDark = makeStop(9, scale.dark[3].L + popLift, scale.dark[3].C, scale.dark[3].H);
   }
-  const nState = (stop, mode, rest, k) => {
-    const L = stateFillL(rest.L, mode, k);
-    return makeStop(stop, L, curve(L, mode), rest.H);
-  };
-  scale.ctaHover = nState(10, "light", scale.cta, 1);
-  scale.ctaPressed = nState(11, "light", scale.cta, 2);
-  scale.ctaHoverDark = nState(10, "dark", scale.ctaDark, 1);
-  scale.ctaPressedDark = nState(11, "dark", scale.ctaDark, 2);
   const onEnforce = contrastProfile !== "apca";
   const onFloor = 4.5;
   scale.onFillTextIsWhite = onTextIsWhite(apcaY(scale.cta.r, scale.cta.g, scale.cta.b), scale.cta.L, scale.cta.C, scale.cta.H, onEnforce, onFloor);
   scale.onFillTextIsWhiteDark = onTextIsWhite(apcaY(scale.ctaDark.r, scale.ctaDark.g, scale.ctaDark.b), scale.ctaDark.L, scale.ctaDark.C, scale.ctaDark.H, onEnforce, onFloor);
+  const nState = (stop, mode, rest, k, white) => {
+    const L = stateFillL(rest.L, mode, k, stepKeepsPole(mode, white, (l) => curve(l, mode), rest.H, { ratioFloor: onFloor }));
+    return makeStop(stop, L, curve(L, mode), rest.H);
+  };
+  scale.ctaHover = nState(10, "light", scale.cta, 1, scale.onFillTextIsWhite);
+  scale.ctaPressed = nState(11, "light", scale.cta, 2, scale.onFillTextIsWhite);
+  scale.ctaHoverDark = nState(10, "dark", scale.ctaDark, 1, scale.onFillTextIsWhiteDark);
+  scale.ctaPressedDark = nState(11, "dark", scale.ctaDark, 2, scale.onFillTextIsWhiteDark);
   return scale;
 }
 function generateSubtleSecondary(hex, opts) {
@@ -2637,10 +2637,6 @@ function generateSubtleSecondary(hex, opts) {
   });
   const asCta = (stop, src) => makeStop(stop, src.L, src.C, src.H);
   const mk = (stop, L, mode) => makeStop(stop, L, curve(L, mode), scale.brandH);
-  const st = (stop, mode, rest, k) => {
-    const L = stateFillL(rest.L, mode, k);
-    return makeStop(stop, L, curve(L, mode), rest.H);
-  };
   if (opts?.ctaL) {
     scale.cta = mk(9, opts.ctaL.light, "light");
     scale.ctaDark = mk(9, opts.ctaL.dark, "dark");
@@ -2648,14 +2644,18 @@ function generateSubtleSecondary(hex, opts) {
     scale.cta = asCta(9, scale.light[3]);
     scale.ctaDark = asCta(9, scale.dark[3]);
   }
-  scale.ctaHover = st(10, "light", scale.cta, 1);
-  scale.ctaPressed = st(11, "light", scale.cta, 2);
-  scale.ctaHoverDark = st(10, "dark", scale.ctaDark, 1);
-  scale.ctaPressedDark = st(11, "dark", scale.ctaDark, 2);
   const onEnforce = opts?.contrastProfile !== "apca";
   const onFloor = 4.5;
   scale.onFillTextIsWhite = onTextIsWhite(apcaY(scale.cta.r, scale.cta.g, scale.cta.b), scale.cta.L, scale.cta.C, scale.cta.H, onEnforce, onFloor);
   scale.onFillTextIsWhiteDark = onTextIsWhite(apcaY(scale.ctaDark.r, scale.ctaDark.g, scale.ctaDark.b), scale.ctaDark.L, scale.ctaDark.C, scale.ctaDark.H, onEnforce, onFloor);
+  const st = (stop, mode, rest, k, white) => {
+    const L = stateFillL(rest.L, mode, k, stepKeepsPole(mode, white, (l) => curve(l, mode), rest.H, { ratioFloor: onFloor }));
+    return makeStop(stop, L, curve(L, mode), rest.H);
+  };
+  scale.ctaHover = st(10, "light", scale.cta, 1, scale.onFillTextIsWhite);
+  scale.ctaPressed = st(11, "light", scale.cta, 2, scale.onFillTextIsWhite);
+  scale.ctaHoverDark = st(10, "dark", scale.ctaDark, 1, scale.onFillTextIsWhiteDark);
+  scale.ctaPressedDark = st(11, "dark", scale.ctaDark, 2, scale.onFillTextIsWhiteDark);
   return scale;
 }
 
@@ -3231,11 +3231,12 @@ function escapeCtaFamily(nScale, mode, contrastProfile) {
   if (!strongText) throw new Error("escapeCtaFamily: the neutral scale has no ink-11 stop");
   const mk = (stop, L) => makeStop(stop, L, strongText.C, strongText.H);
   const cta = mk(9, strongText.L);
-  const ctaHover = mk(10, stateFillL(strongText.L, mode, 1));
-  const ctaPressed = mk(11, stateFillL(strongText.L, mode, 2));
   const onEnforce = contrastProfile !== "apca";
   const onFloor = contrastProfile === "apca" ? void 0 : 4.5;
   const onFillIsWhite = onTextIsWhite(apcaY(cta.r, cta.g, cta.b), cta.L, cta.C, cta.H, onEnforce, onFloor);
+  const keepsPole = stepKeepsPole(mode, onFillIsWhite, () => strongText.C, strongText.H, { ratioFloor: onFloor });
+  const ctaHover = mk(10, stateFillL(strongText.L, mode, 1, keepsPole));
+  const ctaPressed = mk(11, stateFillL(strongText.L, mode, 2, keepsPole));
   return { cta, ctaHover, ctaPressed, onFillIsWhite };
 }
 var SECONDARY_DISTINCT_DELTA_E = 0.12;

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

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

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

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

package/package.json

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