@getvitops/utils 0.9.0 → 2.0.0

package/CHANGELOG.md

@@ -1,5 +1,222 @@
 # @getvitops/utils
 
+## 2.0.0
+
+### Minor Changes
+
+- 04a51d8: Icons: one semantic vocabulary across icon sets, with the bundle derived from your source.
+
+  Name icons by meaning — `<Icon name="menu" />` resolves to `fa7-solid:bars`, `ph:list` or
+  `lucide:menu` depending on the set you configure, so swapping sets is a config edit rather than a
+  find-and-replace. A name containing `:` still passes through untouched, which is the escape hatch
+  for a set-specific glyph.
+
+  **New `icons` option on `getvitops()`.** Configures the sets once per site and, under
+  `output: 'server'`, derives astro-icon's `include` map by scanning your source — the list most
+  projects end up maintaining by hand. On a static build no `include` is passed at all, because
+  astro-icon is already zero-config there and a list could only drop a glyph the scan couldn't see.
+  Names you declare that don't resolve fail the build; names only the scan found just warn; names
+  computed at runtime are reported with file and line so you can declare them.
+
+  **New `<Icon />` component**, and a real fix with it: `Popover`, `Details` and `Drawer` imported
+  `astro-icon/components` at module scope, so the _optional_ peer was resolved whether or not an icon
+  ever rendered — hard-failing anyone who hadn't installed it. Engines now load dynamically. The
+  per-component `iconResolver` prop still works but is deprecated in favour of the integration option.
+
+  **New SVG sprite** (`icons.sprite: true` in your site config) for consumers that can't run an icon
+  integration — Bricks/WordPress, EmDash renderers, plain HTML. `<use href="…/icons.svg#ph--list">`,
+  no JavaScript and no icon-API request. Every semantic name also gets a set-independent `icon-<name>`
+  alias, so sprite markup survives an icon-set change. WordPress gets `vitops_icon()`, a
+  `[vitops_icon]` shortcode and a **Vitops → Icon** Bricks element.
+
+  **New `vitops icons`** command: reports which icons your source uses, which names couldn't be
+  resolved, and which are computed at runtime; `--sprite` builds the sprite, `--json` for CI.
+
+  **Renamed, and completed to all four directions.** Chevrons and arrows are the
+  one family whose _meaning is_ its direction, and that direction is physical, not
+  logical — a chevron in a details marker points down in every writing mode. So they
+  are named for where they point: `expand-more`/`expand-less` →
+  `chevron-down`/`chevron-up`, and `arrow-forward`/`arrow-back` →
+  `arrow-right`/`arrow-left`. `chevron-left`/`chevron-right` keep their names.
+  `arrow-up`/`arrow-down` are new, so both families now cover all four directions.
+  `lightning` is new.
+
+  If you passed any of the old names to `<Icon />`, `resolveIcon` or an `icons`
+  config, update them. They fail loudly rather than silently: an unresolvable
+  declared name throws, and `vitops icons` reports scanned ones.
+
+  **Fixed three Font Awesome mappings that named no real glyph** and so rendered an
+  empty box: `login`/`logout` were mapped to `login`/`logout` (Font Awesome calls
+  them `right-to-bracket`/`right-from-bracket`) and `backup` to `backup`
+  (`cloud-arrow-up`). Every value in all four UI sets is now checked against the
+  installed collection.
+
+  **Phosphor (`ph`) joins the semantic map**, with all 83 names verified against the real icon set.
+  Phosphor keeps every weight in one collection and varies the name (`list`, `list-bold`), unlike Font
+  Awesome's per-weight collections, so `resolveIcon` and `generateIconInclude` gained a `weight`
+  option for sets shaped that way.
+
+  Fixes: `site.icons` was a closed object, so any icon collection not in its hand-written key list was
+  silently dropped during validation — your config passed and the icons never bundled. It accepts any
+  collection name now.
+
+- bf453b0: Maskable favicons are now opaque, so they stop rendering as a logo in a black box.
+
+  `icon-mask.png` is declared `purpose: "maskable"` and `apple-touch-icon.png` is linked on every
+  page. Both sit a deliberately-inset logo on a larger canvas — that inset **is** the maskable safe
+  zone and was always correct — but the canvas was filled with `alpha: 0`. From any transparent
+  source that left 36% of `icon-mask.png` and 40% of `apple-touch-icon.png` transparent, on two files
+  whose entire contract is full bleed: the OS crops them to its own shape and composites the rest onto
+  whatever it likes, usually black. iOS discards alpha on the apple-touch-icon outright.
+
+  `backgroundColor` was already the obvious input for this and already plumbed — as far as the web
+  manifest, and no further. So the raster and the manifest disagreed about the very colour meant to
+  sit behind the icon.
+
+  Now:
+  - those two outputs are composited onto `backgroundColor`, defaulting to `#ffffff` — the same
+    default the manifest's `background_color` already used;
+  - `favicon.svg`, `icon-{16,32,192,512}.png` and `favicon.ico` keep the source's transparency, since
+    none of them is maskable;
+  - a transparent source with no `backgroundColor` set now warns, rather than silently inheriting
+    white — a dark logo would lose against it;
+  - `icon-192`/`icon-512` declare `purpose: "any"` explicitly. Omitting it was legal (unset means
+    "any"), but with a maskable present and nothing claiming "any", some launchers picked the maskable
+    — the one with the safe-zone inset — for slots that wanted a plain icon.
+
+  `vitops favicon` gained `--background <hex>`; it previously had no way to set this at all.
+  `getvitops({ favicon })` and the Vite plugin now forward the option they were already accepting.
+
+- bf453b0: A chroma-0 seed now produces an actual neutral instead of a pink one.
+
+  Beyond a ramp's outermost authored colour, chroma decays towards a small endpoint value (0.008
+  light / 0.015 dark) so the near-white and near-black ends keep a whisper of the hue. That was
+  written as a lerp _target_, and the interpolation factor reaches exactly 1 at steps 50 and 950 for
+  every anchor position — so the endpoints were those constants **unconditionally**. Seeds at chroma
+  0.001, 0.002, 0.05 and 0.2 all produced a byte-identical `#f5f9fe` at step 50.
+
+  There was therefore no seed that yielded a plain neutral, and chroma 0 was the worst case: a true
+  achromatic colour has no hue (colorjs returns NaN), which collapses to 0 — red — so asking for grey
+  gave you `#fdf6f8`, a pink. A brand wanting plain white with grey panels had to discover `anchors`
+  to get there.
+
+  The endpoint is now a **ceiling** rather than a target, so a seed below it keeps its own chroma:
+
+  | seed chroma | step 50 before | step 50 after |
+  | ----------- | -------------- | ------------- |
+  | 0           | `#fdf6f8` 🩷   | `#f8f8f8`     |
+  | 0.001       | `#f5f9fe`      | `#f8f8f9`     |
+  | 0.003       | `#f5f9fe`      | `#f7f8fa`     |
+  | 0.05        | `#f5f9fe`      | `#f5f9fe`     |
+
+  `seed: "#808080"` now gives a real grey ramp — `#f8f8f8` / `#eee` / `#808080` / `#2b2b2b` / `#181818`.
+
+  **No existing palette moves.** The ceiling only binds below itself, and every ordinary brand hue
+  sits above it; the repo's own `tokens.json` is byte-identical across this change.
+
+## 1.0.0
+
+### Major Changes
+
+- bb92a14: **The colour system is rebuilt on a target-prefixed grammar and a shared lightness ladder.**
+  This is a breaking change to every colour token and utility class.
+
+  ## Why
+
+  Two axes shared one class namespace — functional _planes_ (`--<role>-bg-muted`) and
+  appearance-relative _stops_ (`--color-<role>-muted`) — arbitrated by a "plane wins" rule. The
+  result was not a scale. On the shipped palette, light mode:
+
+  | class                              | resolved to  | step                                          |
+  | ---------------------------------- | ------------ | --------------------------------------------- |
+  | `bg-ui-accent-x-muted`             | stop         | 100                                           |
+  | `bg-ui-accent-muted`               | plane        | 100 — identical, so `x-muted` was a dead rung |
+  | `bg-ui-accent`                     | plane        | 50 — _lighter_ than both its "muted" rungs    |
+  | `border-ui-accent-muted` / `-bold` | stop / plane | 300 / 300 — identical                         |
+  | `text-ui-accent-bold`              | stop         | 700 — _lighter_ than `text-…-muted` (800)     |
+
+  Every family was non-monotonic, two had duplicate rungs, and `--color-<role>-muted` was
+  unreachable through any `bg-` class.
+
+  ## The new grammar
+
+  ```
+  --color-<target>-<role>[-<variant>]        target ∈ bg | text | icon | border
+  ```
+
+  The target is **inside** the name, so `bg-danger-muted` and `text-danger-muted` are different
+  tokens and there is nothing left to arbitrate. **The class name is the token name minus
+  `--color-`** — one vocabulary instead of two.
+
+  Variants are ordinal (`xx-muted` < `x-muted` < `muted` < bare < `bold` < `x-bold`) and the
+  tables are sparse: only cells that hold their contrast target exist.
+
+  ## Role kinds
+
+  `colors.roles` values may now be `{ hue, kind }` as well as a bare hue string:
+
+  ```jsonc
+  "roles": {
+    "danger":  "rust",                             // shorthand => chromatic
+    "surface": { "hue": "navy", "kind": "surface" }
+  }
+  ```
+
+  - **`surface`** — a page/panel colour: `bg-<role>` is the card, `bg-<role>-muted` the page
+    behind it, `bg-<role>-x-muted` a well, `bg-<role>-bold` the inverse surface. Full text scale.
+  - **`chromatic`** (default) — a signal colour: tints (`bg-<role>-x-muted`/`-muted`) and solids
+    (`bg-<role>-solid[-bold|-x-bold]`), with **no bare `bg-<role>`** — say how loud you mean.
+    `text-on-<role>` is the guaranteed foreground for the solid family.
+
+  ## Palette generation
+
+  Every ramp now sits on one **fixed lightness ladder** (50 → L 0.98 … 950 → L 0.21); only chroma
+  and hue vary. That is what makes a step mean the same lightness in every hue. Previously each
+  seed transposed the curve, so relative luminance at step 300 ranged from 0.253 to 0.384 across
+  the shipped palette — the same variant read differently depending on the role.
+
+  Authored colours are still reproduced **exactly**. A `seed`, an `anchors` entry or a `tones`
+  value is pinned verbatim at its nearest step; every other step takes the ladder. Snapping brand
+  colours to the ladder was measured and rejected: 11 of 18 real brand hexes moved beyond a
+  just-noticeable difference (worst ΔE-OK 0.050 — Facebook's `#1877F2` → `#0067e1`) and six left
+  sRGB gamut. Deviation is now bounded and local to pinned steps, and warns past ~0.03 L.
+
+  Two tones that claim the same step now **error** instead of one silently overwriting the other;
+  the record form (`tones: { "600": "…", "700": "…" }`) is how you resolve it.
+
+  ## New
+  - **`icon-<role>`** — a non-text tier, so a glyph may run more vivid than text. `icon` is now a
+    default utility family alongside `bg`/`text`/`border`.
+  - **`--color-border-focus`** — the focus-ring tone, taken from `ui-primary`'s solid.
+  - **Contrast is enforced at build time**, not only in tests: text ≥ APCA Lc 75 on its primary
+    background, ≥ 60 on secondary planes, icons and surface boundaries ≥ 45, both appearances.
+    A violation now fails `generate`. Chromatic text is checked against the _surface_ planes it
+    actually sits on, not only its own tints. `text-<role>-x-muted` (placeholder) and `-xx-muted`
+    (disabled) are explicitly exempt; nothing else is.
+
+  ## Migrating
+
+  Rename `--<role>-<suffix>` → `--color-<target>-<role>[-<variant>]`, and the same for classes:
+
+  | before                                  | after                                                            |
+  | --------------------------------------- | ---------------------------------------------------------------- |
+  | `--<role>-bg` / `bg-<role>` (chromatic) | `--color-bg-<role>-x-muted` / `bg-<role>-x-muted`                |
+  | `--<role>-bg-muted`                     | `--color-bg-<role>-muted`                                        |
+  | `--<role>-solid` / `-solid-bold`        | `--color-bg-<role>-solid` / `-solid-bold`                        |
+  | `--<role>-on-solid` / `text-on-<role>`  | `--color-text-on-<role>` (class unchanged)                       |
+  | `--<role>-text` / `-text-muted`         | `--color-text-<role>` / `-muted`                                 |
+  | `--<role>-border` / `-border-bold`      | `--color-border-<role>` / `-bold`                                |
+  | `--color-<role>-muted` (stop)           | judge by use: `--color-bg-<role>-muted` or `--color-text-<role>` |
+
+  **`surface` background names rotate**, value-preserving: what was `--surface-bg` (the page) is
+  now `--color-bg-surface-muted`; what was `--surface-bg-bold` (raised) is now
+  `--color-bg-surface`. Elevation is expressed by which token you reach for — page `bg-muted`,
+  card `bg` — rather than a raised/sunken pair, which is what lets a future surfaces axis flatten
+  it without touching markup.
+
+  `vitops lint` reports role classes that no longer resolve, and now derives its suggestions from
+  what the generator actually emits rather than a hand-maintained list.
+
 ## 0.9.0
 
 ## 0.8.0

package/dist/color/index.d.mts

@@ -68,6 +68,44 @@ interface HarmonyDefinition {
   primaryIndex: number;
 }
 declare const HARMONY_DEFINITIONS: Record<HarmonyType, HarmonyDefinition>;
+/**
+ * The shared lightness ladder every ramp is built on (lightest → darkest).
+ *
+ * Fixed, NOT seed-derived. Two hues at the same step have to read equally light,
+ * otherwise one contrast table cannot serve every hue and a `muted` variant means
+ * something different depending on which role you ask. Only chroma and hue vary
+ * between ramps.
+ *
+ * The previous engine transposed this curve onto each seed, which let relative
+ * luminance at step 300 range from 0.253 (rust) to 0.384 (amber) across the
+ * shipped palette — the drift this replaces.
+ *
+ * Anchored steps are the one deliberate exception: see `generateOklchPalette`.
+ */
+declare const LIGHTNESS_LADDER: Record<StepName, number>;
+/**
+ * Chroma a ramp decays *towards* beyond its outermost anchors, so the near-white
+ * and near-black ends keep a whisper of the hue instead of going flat grey. The
+ * dark end carries slightly more because chroma reads weaker against black.
+ *
+ * It is a CEILING, not a target — `Math.min(ENDPOINT_CHROMA.x, anchor.c)`. That
+ * distinction is the whole reason a neutral is authorable. The interpolation
+ * factor reaches exactly 1 at steps 50 and 950 for every anchor position, so as a
+ * target it made the endpoints these constants *unconditionally*: seeds at chroma
+ * 0.001, 0.002, 0.05 and 0.2 all produced a byte-identical step 50. A brand
+ * wanting plain white with grey panels had no seed that worked, and chroma 0 was
+ * worst of all — colorjs returns NaN hue for a true achromatic colour, which
+ * `hexToOklch` collapses to 0, so the "neutral" came out pink.
+ *
+ * As a ceiling, a low-chroma seed simply stays low and a chroma-0 seed stays 0 at
+ * every unanchored step, which makes the NaN-hue collapse invisible rather than
+ * something `hexToOklch` has to solve (its `|| 0` is load-bearing for
+ * `getColorName`).
+ */
+declare const ENDPOINT_CHROMA: {
+  readonly light: 0.008;
+  readonly dark: 0.015;
+};
 interface OklchColor {
   l: number;
   c: number;
@@ -80,8 +118,36 @@ interface OklchColor {
  */
 declare function parseOklch(oklchString: string): OklchColor;
 /**
- * Generates a complete 11-step OKLCH palette from one or more colors.
- * Automatically determines which step each color belongs to based on lightness.
+ * The ladder step whose lightness is closest to `lightness` — i.e. where a
+ * supplied colour naturally belongs.
+ */
+declare function assignStepByLightness(lightness: number): StepName;
+/**
+ * How far an anchored colour sits from its step's ladder lightness.
+ *
+ * The generator surfaces this as a warning: a large deviation is legal (the
+ * caller asked for that exact colour) but it means the hue will read heavier or
+ * lighter than its siblings at that step, which is worth knowing rather than
+ * discovering later.
+ */
+declare function ladderDeviation(step: StepName, lightness: number): number;
+/**
+ * Build a complete 11-step OKLCH ramp from one or more anchor colours.
+ *
+ * **Ladder-first with exact anchors.** Every anchor is reproduced *verbatim* at
+ * its step; every other step takes its lightness from `LIGHTNESS_LADDER`, with
+ * chroma and hue interpolated between the flanking anchors and decayed toward
+ * `ENDPOINT_CHROMA` beyond the outermost ones.
+ *
+ * The consequence is the point: a client's brand hex survives byte-for-byte,
+ * while the other ten steps stay directly comparable to every other hue. The
+ * deviation from the ladder is bounded and *local to anchored steps* — unlike
+ * the previous engine, which warped the whole ramp to fit its anchors so every
+ * step drifted.
+ *
+ * Chroma may come out beyond the sRGB gamut here; that is deliberate.
+ * `oklchStringToHex` gamut-maps with the CSS algorithm, which reduces chroma
+ * while holding lightness, so the ladder survives the conversion.
  */
 declare function generateOklchPalette(input: string | string[] | Record<string, string>): Record<StepName, string>;
 /** APCA lightness-contrast (Lc) magnitude between a foreground and background. */
@@ -95,6 +161,11 @@ declare function pickOn(bg: string, hue?: number): string;
  * The tinted off-white / off-black endpoints for a hue — white/black with a
  * whisper of the hue mixed in. These are the text/background tints every ramp
  * needs (and the one exception strict brand kits allow).
+ *
+ * Derived from `LIGHTNESS_LADDER` and `ENDPOINT_CHROMA` rather than its own
+ * literals, so a strict tone kit's endpoints land on the same ladder rungs a
+ * generated ramp would have used. This is the single definition — callers must
+ * not hand-write their own near-white/near-black.
  */
 declare function tintedEndpoints(hue: number, chroma?: number): {
   light: string;
@@ -140,5 +211,5 @@ declare const DEFAULT_FUNCTIONAL_HUES: {
  */
 declare function suggestFunctionalColorHue(type: keyof typeof DEFAULT_FUNCTIONAL_HUES, existingHues: number[]): number;
 //#endregion
-export { COLOR_GROUPS, ColorGroup, DEFAULT_FUNCTIONAL_HUES, HARMONY_DEFINITIONS, HARMONY_STRATEGIES, HARMONY_TYPES, HarmonyDefinition, HarmonyOption, HarmonyStrategy, HarmonyType, RgbResult, STEP_NAMES, StepName, applyHarmonyStrategy, contrastLc, formatColorName, gamutMapOklchToHex, generateOklchPalette, getColorName, getColorNameWithHue, getHarmonySuggestions, hexToOklch, oklchStringToHex, oklchToHex, oklchToP3, oklchToSrgb, parseOklch, pickOn, suggestFunctionalColorHue, tintedEndpoints };
+export { COLOR_GROUPS, ColorGroup, DEFAULT_FUNCTIONAL_HUES, ENDPOINT_CHROMA, HARMONY_DEFINITIONS, HARMONY_STRATEGIES, HARMONY_TYPES, HarmonyDefinition, HarmonyOption, HarmonyStrategy, HarmonyType, LIGHTNESS_LADDER, RgbResult, STEP_NAMES, StepName, applyHarmonyStrategy, assignStepByLightness, contrastLc, formatColorName, gamutMapOklchToHex, generateOklchPalette, getColorName, getColorNameWithHue, getHarmonySuggestions, hexToOklch, ladderDeviation, oklchStringToHex, oklchToHex, oklchToP3, oklchToSrgb, parseOklch, pickOn, suggestFunctionalColorHue, tintedEndpoints };
 //# sourceMappingURL=index.d.mts.map

package/dist/color/index.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.mts","names":[],"sources":["../../src/color/colors.ts","../../src/color/color-harmony.ts"],"mappings":";UAkBiB,SAAA;EACf,CAAA;EACA,CAAA;EACA,CAAA;EACA,OAAA;EAHA;EAKA,aAAA;AAAA;;;;AAAa;iBAOC,WAAA,CAAY,CAAA,UAAW,CAAA,UAAW,CAAA,WAAY,SAAS;;;;;iBAmBvD,SAAA,CAAU,CAAA,UAAW,CAAA,UAAW,CAAA,WAAY,SAAS;;;;AAnBE;iBAsCvD,kBAAA,CACd,CAAA,UACA,CAAA,UACA,CAAA,UACA,KAAA;AAAA,cAUW,UAAA;AAAA,KACD,QAAA,WAAmB,UAAU;AAAA,cAE5B,YAAA;AAAA,KAWD,UAAA,WAAqB,YAAY;;;;iBAK7B,UAAA,CAAW,GAAA;EAAgB,CAAA;EAAW,CAAA;EAAW,CAAA;AAAA;;;;iBAajD,UAAA,CAAW,KAAA;EAAS,CAAA;EAAW,CAAA;EAAW,CAAA;AAAA;;;;AAhC+B;iBA8CzE,gBAAA,CAAiB,WAAmB;;;;AA7CX;iBA8DzB,eAAA,CAAgB,IAAY;;;;iBA+G5B,YAAA,CAAa,GAAW;AAhKxC;;;AAAA,iBAsLgB,mBAAA,CAAoB,GAAW;AAAA,cAclC,aAAA;AAAA,KASD,WAAA,WAAsB,aAAa;AAAA,UAE9B,iBAAA;EACf,KAAA;EACA,OAAA;EACA,YAAA;AAAA;AAAA,cAGW,mBAAA,EAAqB,MAAA,CAAO,WAAA,EAAa,iBAAA;AAAA,UAqD5C,UAAA;EACR,CAAA;EACA,CAAA;EACA,CAAA;AAAA;;;;;;iBAQc,UAAA,CAAW,WAAA,WAAsB,UAAU;;AAnQU;AAcrE;;iBAkXgB,oBAAA,CACd,KAAA,sBAA2B,MAAA,mBAC1B,MAAA,CAAO,QAAA;;iBA+GM,UAAA,CAAW,EAAA,UAAY,EAAU;AAldjD;;;;AAAA,iBA0dgB,MAAA,CAAO,EAAA,UAAY,GAAY;AA3W/C;;;;AAAwC;AAAxC,iBAuXgB,eAAA,CAAgB,GAAA,UAAa,MAAA;EAAkB,KAAA;EAAe,IAAA;AAAA;;;;AAtmB9E;;KCdY,eAAA;AAAA,UAWK,aAAA;EACf,EAAA,EAAI,eAAe;EACnB,KAAA;EACA,WAAA;EACA,QAAA;AAAA;AAAA,cAGW,kBAAA,EAAoB,aAAa;ADE/B;AAOf;;AAPe,iBC0DC,oBAAA,CAAqB,OAAA,UAAiB,QAAA,EAAU,eAAe;;;;iBAgB/D,qBAAA,CACd,OAAA,WACC,KAAK;EAAG,QAAA,EAAU,eAAA;EAAiB,GAAA;EAAa,KAAA;EAAe,WAAA;AAAA;;;;cAYrD,uBAAA;EAAA;;;;;;;;iBAUG,yBAAA,CACd,IAAA,eAAmB,uBAAuB,EAC1C,YAAA"}
+{"version":3,"file":"index.d.mts","names":[],"sources":["../../src/color/colors.ts","../../src/color/color-harmony.ts"],"mappings":";UAkBiB,SAAA;EACf,CAAA;EACA,CAAA;EACA,CAAA;EACA,OAAA;EAHA;EAKA,aAAA;AAAA;;;;AAAa;iBAOC,WAAA,CAAY,CAAA,UAAW,CAAA,UAAW,CAAA,WAAY,SAAS;;;;;iBAmBvD,SAAA,CAAU,CAAA,UAAW,CAAA,UAAW,CAAA,WAAY,SAAS;;;;AAnBE;iBAsCvD,kBAAA,CACd,CAAA,UACA,CAAA,UACA,CAAA,UACA,KAAA;AAAA,cAUW,UAAA;AAAA,KACD,QAAA,WAAmB,UAAU;AAAA,cAE5B,YAAA;AAAA,KAWD,UAAA,WAAqB,YAAY;;;;iBAK7B,UAAA,CAAW,GAAA;EAAgB,CAAA;EAAW,CAAA;EAAW,CAAA;AAAA;;;;iBAajD,UAAA,CAAW,KAAA;EAAS,CAAA;EAAW,CAAA;EAAW,CAAA;AAAA;;;;AAhC+B;iBA8CzE,gBAAA,CAAiB,WAAmB;;;;AA7CX;iBA8DzB,eAAA,CAAgB,IAAY;;;;iBA+G5B,YAAA,CAAa,GAAW;AAhKxC;;;AAAA,iBAsLgB,mBAAA,CAAoB,GAAW;AAAA,cAclC,aAAA;AAAA,KASD,WAAA,WAAsB,aAAa;AAAA,UAE9B,iBAAA;EACf,KAAA;EACA,OAAA;EACA,YAAA;AAAA;AAAA,cAGW,mBAAA,EAAqB,MAAA,CAAO,WAAA,EAAa,iBAAA;;;AAhNY;AAalE;;;;;;;;;AAAqE;AAcrE;cAyOa,gBAAA,EAAkB,MAAM,CAAC,QAAA;;;AAzOc;AAiBpD;;;;AAA4C;AA+G5C;;;;AAAwC;AAsBxC;;;;AAA+C;AAc/C;cAsGa,eAAA;EAAA,SAAwD,KAAA;EAAA,SAAA,IAAA;AAAA;AAAA,UAE3D,UAAA;EACR,CAAA;EACA,CAAA;EACA,CAAA;AAAA;AAhGF;;;;;AAAA,iBAwGgB,UAAA,CAAW,WAAA,WAAsB,UAAU;;;AArG7C;AAGd;iBAkIgB,qBAAA,CAAsB,SAAA,WAAoB,QAAQ;;;;;;;;;iBAuBlD,eAAA,CAAgB,IAAA,EAAM,QAAQ,EAAE,SAAA;;AAzJuB;AAoDvE;;;;AAA8C;AAiC9C;;;;;AAAsE;;;;;;iBA6FtD,oBAAA,CACd,KAAA,sBAA2B,MAAA,mBAC1B,MAAA,CAAO,QAAA;;iBAsFM,UAAA,CAAW,EAAA,UAAY,EAAU;AAxKjD;;;;AAAA,iBAgLgB,MAAA,CAAO,EAAA,UAAY,GAAY;AAhJ/C;;;;AAAkE;AAuBlE;;;;;AAvBA,iBAiKgB,eAAA,CAAgB,GAAA,UAAa,MAAA;EAAoB,KAAA;EAAe,IAAA;AAAA;;;;AAvkBhF;;KCdY,eAAA;AAAA,UAWK,aAAA;EACf,EAAA,EAAI,eAAe;EACnB,KAAA;EACA,WAAA;EACA,QAAA;AAAA;AAAA,cAGW,kBAAA,EAAoB,aAAa;ADE/B;AAOf;;AAPe,iBC0DC,oBAAA,CAAqB,OAAA,UAAiB,QAAA,EAAU,eAAe;;;;iBAgB/D,qBAAA,CACd,OAAA,WACC,KAAK;EAAG,QAAA,EAAU,eAAA;EAAiB,GAAA;EAAa,KAAA;EAAe,WAAA;AAAA;;;;cAYrD,uBAAA;EAAA;;;;;;;;iBAUG,yBAAA,CACd,IAAA,eAAmB,uBAAuB,EAC1C,YAAA"}

package/dist/color/index.mjs

@@ -332,18 +332,55 @@ const HARMONY_DEFINITIONS = {
 		primaryIndex: 1
 	}
 };
-const DEFAULT_LIGHTNESS_SCALE = {
-	50: .95,
-	100: .9,
-	200: .8,
-	300: .7,
-	400: .6,
-	500: .5,
-	600: .4,
-	700: .3,
-	800: .2,
-	900: .1,
-	950: .05
+/**
+* The shared lightness ladder every ramp is built on (lightest → darkest).
+*
+* Fixed, NOT seed-derived. Two hues at the same step have to read equally light,
+* otherwise one contrast table cannot serve every hue and a `muted` variant means
+* something different depending on which role you ask. Only chroma and hue vary
+* between ramps.
+*
+* The previous engine transposed this curve onto each seed, which let relative
+* luminance at step 300 range from 0.253 (rust) to 0.384 (amber) across the
+* shipped palette — the drift this replaces.
+*
+* Anchored steps are the one deliberate exception: see `generateOklchPalette`.
+*/
+const LIGHTNESS_LADDER = {
+	50: .98,
+	100: .95,
+	200: .9,
+	300: .83,
+	400: .74,
+	500: .65,
+	600: .54,
+	700: .47,
+	800: .38,
+	900: .29,
+	950: .21
+};
+/**
+* Chroma a ramp decays *towards* beyond its outermost anchors, so the near-white
+* and near-black ends keep a whisper of the hue instead of going flat grey. The
+* dark end carries slightly more because chroma reads weaker against black.
+*
+* It is a CEILING, not a target — `Math.min(ENDPOINT_CHROMA.x, anchor.c)`. That
+* distinction is the whole reason a neutral is authorable. The interpolation
+* factor reaches exactly 1 at steps 50 and 950 for every anchor position, so as a
+* target it made the endpoints these constants *unconditionally*: seeds at chroma
+* 0.001, 0.002, 0.05 and 0.2 all produced a byte-identical step 50. A brand
+* wanting plain white with grey panels had no seed that worked, and chroma 0 was
+* worst of all — colorjs returns NaN hue for a true achromatic colour, which
+* `hexToOklch` collapses to 0, so the "neutral" came out pink.
+*
+* As a ceiling, a low-chroma seed simply stays low and a chroma-0 seed stays 0 at
+* every unanchored step, which makes the NaN-hue collapse invisible rather than
+* something `hexToOklch` has to solve (its `|| 0` is load-bearing for
+* `getColorName`).
+*/
+const ENDPOINT_CHROMA = {
+	light: .008,
+	dark: .015
 };
 /**
 * Parses an OKLCH CSS string into numerical components.
@@ -367,69 +404,21 @@ function lerp(start, end, factor) {
 	return start + factor * (end - start);
 }
 /**
-* Transpose the default lightness scale to match the provided anchors.
+* Interpolate hue the short way round the wheel. A ramp anchored at 350° and 10°
+* spans 20°, not 340° — the naive lerp sent it the long way through cyan.
 */
-function transposeLightnessScale(parsedAnchors, sortedAnchorSteps) {
-	const transposedScale = {};
-	if (sortedAnchorSteps.length === 1) {
-		const anchorStep = sortedAnchorSteps[0];
-		const anchorL = parsedAnchors[anchorStep].l;
-		const defaultAnchorL = DEFAULT_LIGHTNESS_SCALE[anchorStep];
-		for (const step of STEP_NAMES) {
-			if (step === anchorStep) {
-				transposedScale[step] = anchorL;
-				continue;
-			}
-			const defaultStepL = DEFAULT_LIGHTNESS_SCALE[step];
-			if (defaultStepL > defaultAnchorL) transposedScale[step] = lerp(anchorL, .97, (defaultStepL - defaultAnchorL) / (1 - defaultAnchorL));
-			else transposedScale[step] = lerp(.05, anchorL, defaultStepL / defaultAnchorL);
-		}
-		return transposedScale;
-	}
-	for (const step of STEP_NAMES) {
-		const anchored = parsedAnchors[step];
-		if (anchored) {
-			transposedScale[step] = anchored.l;
-			continue;
-		}
-		let lowerStep = null;
-		let upperStep = null;
-		for (let i = sortedAnchorSteps.length - 1; i >= 0; i--) {
-			const candidate = sortedAnchorSteps[i];
-			if (candidate < step) {
-				lowerStep = candidate;
-				break;
-			}
-		}
-		for (const anchorStep of sortedAnchorSteps) if (anchorStep > step) {
-			upperStep = anchorStep;
-			break;
-		}
-		if (lowerStep !== null && upperStep !== null) {
-			const lowerL = parsedAnchors[lowerStep].l;
-			const upperL = parsedAnchors[upperStep].l;
-			const span = upperStep - lowerStep;
-			transposedScale[step] = lerp(lowerL, upperL, (step - lowerStep) / span);
-		} else if (lowerStep !== null) {
-			const lowerL = parsedAnchors[lowerStep].l;
-			const defaultLowerL = DEFAULT_LIGHTNESS_SCALE[lowerStep];
-			transposedScale[step] = lerp(.05, lowerL, DEFAULT_LIGHTNESS_SCALE[step] / defaultLowerL);
-		} else if (upperStep !== null) {
-			const upperL = parsedAnchors[upperStep].l;
-			const defaultUpperL = DEFAULT_LIGHTNESS_SCALE[upperStep];
-			transposedScale[step] = lerp(upperL, .97, (DEFAULT_LIGHTNESS_SCALE[step] - defaultUpperL) / (1 - defaultUpperL));
-		}
-	}
-	return transposedScale;
+function lerpHue(start, end, factor) {
+	return (start + (((end - start) % 360 + 540) % 360 - 180) * factor + 360) % 360;
 }
 /**
-* Automatically assigns a color to the most appropriate step based on its lightness.
+* The ladder step whose lightness is closest to `lightness` — i.e. where a
+* supplied colour naturally belongs.
 */
 function assignStepByLightness(lightness) {
 	let closestStep = 500;
-	let minDiff = Math.abs(lightness - DEFAULT_LIGHTNESS_SCALE[500]);
+	let minDiff = Math.abs(lightness - LIGHTNESS_LADDER[500]);
 	for (const step of STEP_NAMES) {
-		const diff = Math.abs(lightness - DEFAULT_LIGHTNESS_SCALE[step]);
+		const diff = Math.abs(lightness - LIGHTNESS_LADDER[step]);
 		if (diff < minDiff) {
 			minDiff = diff;
 			closestStep = step;
@@ -438,68 +427,78 @@ function assignStepByLightness(lightness) {
 	return closestStep;
 }
 /**
-* Generates a complete 11-step OKLCH palette from one or more colors.
-* Automatically determines which step each color belongs to based on lightness.
+* How far an anchored colour sits from its step's ladder lightness.
+*
+* The generator surfaces this as a warning: a large deviation is legal (the
+* caller asked for that exact colour) but it means the hue will read heavier or
+* lighter than its siblings at that step, which is worth knowing rather than
+* discovering later.
+*/
+function ladderDeviation(step, lightness) {
+	return lightness - LIGHTNESS_LADDER[step];
+}
+/** Absolute chroma ceiling — beyond this nothing survives gamut mapping anyway. */
+const MAX_CHROMA = .37;
+/**
+* Build a complete 11-step OKLCH ramp from one or more anchor colours.
+*
+* **Ladder-first with exact anchors.** Every anchor is reproduced *verbatim* at
+* its step; every other step takes its lightness from `LIGHTNESS_LADDER`, with
+* chroma and hue interpolated between the flanking anchors and decayed toward
+* `ENDPOINT_CHROMA` beyond the outermost ones.
+*
+* The consequence is the point: a client's brand hex survives byte-for-byte,
+* while the other ten steps stay directly comparable to every other hue. The
+* deviation from the ladder is bounded and *local to anchored steps* — unlike
+* the previous engine, which warped the whole ramp to fit its anchors so every
+* step drifted.
+*
+* Chroma may come out beyond the sRGB gamut here; that is deliberate.
+* `oklchStringToHex` gamut-maps with the CSS algorithm, which reduces chroma
+* while holding lightness, so the ladder survives the conversion.
 */
 function generateOklchPalette(input) {
 	let anchors = {};
-	if (typeof input === "string") {
-		const step = assignStepByLightness(parseOklch(input).l);
-		anchors[step] = input;
-	} else if (Array.isArray(input)) for (const colorStr of input) {
-		const step = assignStepByLightness(parseOklch(colorStr).l);
-		anchors[step] = colorStr;
-	}
-	else if (typeof input === "object") anchors = input;
+	if (typeof input === "string") anchors[assignStepByLightness(parseOklch(input).l)] = input;
+	else if (Array.isArray(input)) for (const colorStr of input) anchors[assignStepByLightness(parseOklch(colorStr).l)] = colorStr;
+	else if (typeof input === "object" && input !== null) anchors = { ...input };
 	else throw new Error("Input must be a color string, array of colors, or object with step assignments");
 	const parsedAnchors = {};
-	for (const key in anchors) parsedAnchors[parseInt(key)] = parseOklch(anchors[key]);
-	const sortedAnchorSteps = Object.keys(parsedAnchors).map(Number).sort((a, b) => a - b);
-	const lightnessScale = transposeLightnessScale(parsedAnchors, sortedAnchorSteps);
+	for (const [key, value] of Object.entries(anchors)) parsedAnchors[Number(key)] = parseOklch(value);
+	const anchorSteps = Object.keys(parsedAnchors).map(Number).sort((a, b) => a - b);
+	const idx = (step) => STEP_NAMES.indexOf(step);
+	const lastIdx = STEP_NAMES.length - 1;
 	const palette = {};
 	for (const step of STEP_NAMES) {
 		if (parsedAnchors[step]) {
 			palette[step] = anchors[step];
 			continue;
 		}
-		let startStep = null;
-		let endStep = null;
-		for (let i = sortedAnchorSteps.length - 1; i >= 0; i--) {
-			const candidate = sortedAnchorSteps[i];
-			if (candidate < step) {
-				startStep = candidate;
-				break;
-			}
-		}
-		for (const anchorStep of sortedAnchorSteps) if (anchorStep > step) {
-			endStep = anchorStep;
-			break;
-		}
-		let c_int, h_int;
-		if (startStep !== null && endStep !== null) {
-			const startColor = parsedAnchors[startStep];
-			const endColor = parsedAnchors[endStep];
-			const span = endStep - startStep;
-			const factor = (step - startStep) / span;
-			c_int = lerp(startColor.c, endColor.c, factor);
-			h_int = lerp(startColor.h, endColor.h, factor);
-		} else if (startStep !== null) {
-			const a = parsedAnchors[startStep];
-			c_int = a.c;
-			h_int = a.h;
-		} else if (endStep !== null) {
-			const a = parsedAnchors[endStep];
-			c_int = a.c;
-			h_int = a.h;
+		const lighter = [...anchorSteps].reverse().find((s) => s < step);
+		const darker = anchorSteps.find((s) => s > step);
+		let chroma;
+		let hue;
+		if (lighter !== void 0 && darker !== void 0) {
+			const a = parsedAnchors[lighter];
+			const b = parsedAnchors[darker];
+			const factor = (idx(step) - idx(lighter)) / (idx(darker) - idx(lighter));
+			chroma = lerp(a.c, b.c, factor);
+			hue = lerpHue(a.h, b.h, factor);
+		} else if (lighter !== void 0) {
+			const a = parsedAnchors[lighter];
+			const factor = (idx(step) - idx(lighter)) / (lastIdx - idx(lighter));
+			chroma = lerp(a.c, Math.min(ENDPOINT_CHROMA.dark, a.c), factor);
+			hue = a.h;
+		} else if (darker !== void 0) {
+			const b = parsedAnchors[darker];
+			const factor = (idx(darker) - idx(step)) / idx(darker);
+			chroma = lerp(b.c, Math.min(ENDPOINT_CHROMA.light, b.c), factor);
+			hue = b.h;
 		} else {
-			c_int = .1;
-			h_int = 0;
+			chroma = .1;
+			hue = 0;
 		}
-		const l_int = lightnessScale[step];
-		const dampeningFactor = l_int < .25 ? .3 + l_int / .25 * .7 : l_int > .75 ? .3 + (1 - l_int) / .25 * .7 : 1;
-		c_int *= dampeningFactor;
-		c_int = Math.min(c_int, .37);
-		palette[step] = `oklch(${(l_int * 100).toFixed(2) + "%"} ${c_int.toFixed(4)} ${h_int.toFixed(2)})`;
+		palette[step] = `oklch(${(LIGHTNESS_LADDER[step] * 100).toFixed(2) + "%"} ${Math.min(chroma, MAX_CHROMA).toFixed(4)} ${hue.toFixed(2)})`;
 	}
 	return palette;
 }
@@ -529,17 +528,22 @@ function pickOn(bg, hue) {
 * The tinted off-white / off-black endpoints for a hue — white/black with a
 * whisper of the hue mixed in. These are the text/background tints every ramp
 * needs (and the one exception strict brand kits allow).
+*
+* Derived from `LIGHTNESS_LADDER` and `ENDPOINT_CHROMA` rather than its own
+* literals, so a strict tone kit's endpoints land on the same ladder rungs a
+* generated ramp would have used. This is the single definition — callers must
+* not hand-write their own near-white/near-black.
 */
-function tintedEndpoints(hue, chroma = .01) {
+function tintedEndpoints(hue, chroma) {
 	return {
 		light: oklchToHex({
-			l: .98,
-			c: Math.min(chroma, .02),
+			l: LIGHTNESS_LADDER[50],
+			c: Math.min(chroma ?? ENDPOINT_CHROMA.light, .02),
 			h: hue
 		}),
 		dark: oklchToHex({
-			l: .16,
-			c: Math.min(chroma * 1.5, .03),
+			l: LIGHTNESS_LADDER[950],
+			c: Math.min((chroma ?? ENDPOINT_CHROMA.dark) * 1.5, .03),
 			h: hue
 		})
 	};
@@ -647,5 +651,5 @@ function suggestFunctionalColorHue(type, existingHues) {
 }
 
 //#endregion
-export { COLOR_GROUPS, DEFAULT_FUNCTIONAL_HUES, HARMONY_DEFINITIONS, HARMONY_STRATEGIES, HARMONY_TYPES, STEP_NAMES, applyHarmonyStrategy, contrastLc, formatColorName, gamutMapOklchToHex, generateOklchPalette, getColorName, getColorNameWithHue, getHarmonySuggestions, hexToOklch, oklchStringToHex, oklchToHex, oklchToP3, oklchToSrgb, parseOklch, pickOn, suggestFunctionalColorHue, tintedEndpoints };
+export { COLOR_GROUPS, DEFAULT_FUNCTIONAL_HUES, ENDPOINT_CHROMA, HARMONY_DEFINITIONS, HARMONY_STRATEGIES, HARMONY_TYPES, LIGHTNESS_LADDER, STEP_NAMES, applyHarmonyStrategy, assignStepByLightness, contrastLc, formatColorName, gamutMapOklchToHex, generateOklchPalette, getColorName, getColorNameWithHue, getHarmonySuggestions, hexToOklch, ladderDeviation, oklchStringToHex, oklchToHex, oklchToP3, oklchToSrgb, parseOklch, pickOn, suggestFunctionalColorHue, tintedEndpoints };
 //# sourceMappingURL=index.mjs.map