@rafters/color-utils 0.5.4 → 0.6.0

package/README.md

@@ -73,7 +73,7 @@ everywhere, `p3` needs a wide-gamut screen, `out` is displayable nowhere.
 
 - `getGamutTier(oklch)` — which tier a color falls in.
 - `isInSRGBGamut(oklch)` / `isInP3Gamut(oklch)` — the two boundary checks.
-- `toNearestGamut(oklch)` — snap an out-of-gamut color into sRGB. Returns
+- `toNearestGamut(oklch)` — snap an out-of-gamut color into sRGB, keeping lightness, hue and alpha; only chroma drops. Returns
   `{ color, tier }`: the snapped OKLCH and the tier it landed in.
 - `computeGamutBoundaries(hue, steps?)` — the boundary points a picker draws
   against.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rafters/color-utils",
-  "version": "0.5.4",
+  "version": "0.6.0",
   "description": "OKLCH color manipulation utilities for Rafters design system",
   "homepage": "https://rafters.studio",
   "license": "MIT",
@@ -22,15 +22,15 @@
     "access": "public"
   },
   "dependencies": {
+    "@rafters/shared": "0.6.0",
     "apca-w3": "^0.1.9",
     "colorjs.io": "^0.5.2",
-    "zod": "^4.1.12",
-    "@rafters/shared": "0.5.4"
+    "zod": "^4.6.5"
   },
   "devDependencies": {
-    "@types/node": "24.10.0",
+    "@types/node": "^24",
     "tsx": "^4.21.0",
-    "typescript": "5.9.3",
+    "typescript": "^7.0.2",
     "vitest": "^5.0.0",
     "zocker": "3.0.0"
   },

package/src/accessibility.ts

@@ -18,6 +18,7 @@ import { APCAcontrast, displayP3toY, sRGBtoY } from 'apca-w3';
 import Color from 'colorjs.io';
 import { z } from 'zod';
 import { getGamutTier, toGamutCeiling } from './gamut.js';
+import { POSITION_TO_INDEX } from './scale-positions.js';
 
 /** White reference color for contrast calculations. */
 export const CONTRAST_WHITE: OKLCH = { l: 1, c: 0, h: 0, alpha: 1 };
@@ -276,6 +277,8 @@ export function assembleWcagAccessibility(
 
 /**
  * Re-derive accessibility metadata for a ColorValue whose scale changed.
+ * On-white and on-black are measured on the recorded anchor step when the
+ * value has one (createNormalizedScale), else on the 600 step.
  * A family value supplied without its WCAG pair matrices would starve the
  * contrast/state/invert selection downstream -- this guard re-bakes them.
  * No-op for values without a scale. (Moved from the removed CLI set command;
@@ -283,7 +286,9 @@ export function assembleWcagAccessibility(
  */
 export function rebakeAccessibility(value: ColorValue): ColorValue {
   if (!('scale' in value) || !Array.isArray(value.scale)) return value;
-  const reference = value.scale[REFERENCE_STEP_INDEX] ?? value.scale[0];
+  const anchorIndex =
+    value.anchor === undefined ? REFERENCE_STEP_INDEX : POSITION_TO_INDEX[value.anchor];
+  const reference = value.scale[anchorIndex ?? REFERENCE_STEP_INDEX] ?? value.scale[0];
   if (!reference) return value;
   return { ...value, accessibility: assembleWcagAccessibility(value.scale, reference) };
 }

package/src/builder.ts

@@ -120,13 +120,42 @@ export function buildColorValue(oklch: OKLCH, options: BuildColorValueOptions =
         }
       : undefined;
 
+  return assembleColorValue(
+    oklch,
+    { scale, gamut, seedAdjusted, reference: landed ?? oklch },
+    options,
+  );
+}
+
+/** The scale half of a ColorValue, as a builder produced it. */
+export interface BuiltScale {
+  scale: OKLCH[];
+  gamut: NonNullable<ColorValue['gamut']>;
+  seedAdjusted: ColorValue['seedAdjusted'];
+  /** The step the on-white and on-black figures are measured on. */
+  reference: OKLCH;
+}
+
+/**
+ * Assemble a ColorValue around a built scale: harmonies, accessibility,
+ * analysis, weights, semantic suggestions and the name, all from the
+ * requested colour. Shared by buildColorValue and createNormalizedScale so
+ * both families carry the same intelligence.
+ */
+export function assembleColorValue(
+  oklch: OKLCH,
+  built: BuiltScale,
+  options: BuildColorValueOptions,
+): ColorValue {
+  const { scale, gamut, seedAdjusted, reference } = built;
+
   // Generate harmonies
   const harmony = generateHarmony(oklch);
 
   // WCAG accessibility (pair matrices + on-white/on-black) via the shared
   // assembler, measured on the step the seed landed on (the same step
   // rebakeAccessibility uses); APCA is layered on below, builder-only.
-  const wcagAccessibility = assembleWcagAccessibility(scale, landed ?? oklch);
+  const wcagAccessibility = assembleWcagAccessibility(scale, reference);
   const apcaOnWhite = calculateAPCAContrast(oklch, CONTRAST_WHITE);
   const apcaOnBlack = calculateAPCAContrast(oklch, CONTRAST_BLACK);
 

package/src/conversion.ts

@@ -90,3 +90,23 @@ export function roundOKLCH(oklch: OKLCH): OKLCH {
     alpha: oklch.alpha !== undefined ? Math.round(oklch.alpha * 100) / 100 : 1,
   };
 }
+
+/**
+ * Convert an in-gamut OKLCH colour to sRGB: gamma-encoded components in
+ * [0, 1] (clamped, so a colour on the sRGB boundary cannot round outside it)
+ * and a six-digit hex. Map an out-of-gamut colour first, with
+ * toGamutCeiling(oklch, 'srgb'); alpha is not part of the result.
+ */
+export function oklchToSRGB(oklch: OKLCH): { components: [number, number, number]; hex: string } {
+  const coords = new Color('oklch', [oklch.l, oklch.c, oklch.h]).to('srgb').coords;
+  const channel = (i: number): number => Math.min(1, Math.max(0, Number(coords[i] ?? 0) || 0));
+  const components: [number, number, number] = [channel(0), channel(1), channel(2)];
+  const hex = `#${components
+    .map((v) =>
+      Math.round(v * 255)
+        .toString(16)
+        .padStart(2, '0'),
+    )
+    .join('')}`;
+  return { components, hex };
+}

package/src/gamut.ts

@@ -45,33 +45,17 @@ export function getGamutTier(oklch: OKLCH): GamutTier {
 }
 
 /**
- * Snap an OKLCH color to the nearest in-gamut color.
- * Returns the snapped color and its tier.
+ * Snap an OKLCH color into sRGB, keeping lightness, hue and alpha: the
+ * largest chroma sRGB holds there, as toGamutCeiling(oklch, 'srgb').
  */
 export function toNearestGamut(oklch: OKLCH): { color: OKLCH; tier: GamutTier } {
-  const color = new Color('oklch', [oklch.l, oklch.c, oklch.h]);
-
-  if (color.inGamut('srgb')) {
-    return { color: { ...oklch }, tier: 'srgb' };
-  }
-
-  const srgbMapped = color.toGamut({ space: 'srgb' });
-  const mappedOklch = srgbMapped.to('oklch');
-  return {
-    color: {
-      l: mappedOklch.coords[0] ?? 0,
-      c: mappedOklch.coords[1] ?? 0,
-      h: mappedOklch.coords[2] ?? oklch.h,
-      alpha: oklch.alpha,
-    },
-    tier: 'srgb',
-  };
+  return { color: toGamutCeiling(oklch, 'srgb'), tier: 'srgb' };
 }
 
 /**
- * Whether Display P3 steps are allowed in a family. Current choice (Sean,
- * 2026-10-17; revisable): one constant, off by default, so every family is
- * built in sRGB until a setting exists to turn it on.
+ * Whether Display P3 steps are allowed in a family. One constant, off by
+ * default, so every family is built in sRGB until a setting exists to turn it
+ * on.
  */
 export const ALLOW_P3 = false;
 
@@ -84,18 +68,11 @@ function inCeiling(oklch: OKLCH, ceiling: GamutCeiling): boolean {
 
 /**
  * Map one colour into a gamut ceiling: unchanged when already inside, else
- * colorjs.io toGamut into that space.
+ * the same lightness and hue at the largest chroma the ceiling holds there.
  */
 export function toGamutCeiling(oklch: OKLCH, ceiling: GamutCeiling): OKLCH {
-  const color = new Color('oklch', [oklch.l, oklch.c, oklch.h]);
-  if (color.inGamut(ceiling)) return { ...oklch };
-  const [l, c, h] = color.toGamut({ space: ceiling }).to('oklch').coords;
-  return {
-    l: l ?? oklch.l,
-    c: c ?? 0,
-    h: h === undefined || Number.isNaN(h) ? oklch.h : h,
-    alpha: oklch.alpha,
-  };
+  if (inCeiling(oklch, ceiling)) return { ...oklch };
+  return { ...oklch, c: Math.min(oklch.c, findMaxChroma(oklch.l, oklch.h, ceiling)) };
 }
 
 /**
@@ -113,46 +90,17 @@ function roundInside(oklch: OKLCH, ceiling: GamutCeiling): OKLCH {
   return { ...rounded, c: Math.max(0, c) };
 }
 
-/** Keep the step's lightness and hue; reduce chroma only, to the ceiling's edge. */
-function reduceChromaOnly(oklch: OKLCH, ceiling: GamutCeiling): OKLCH {
-  const maxC = findMaxChroma(oklch.l, oklch.h, ceiling);
-  return roundInside({ ...oklch, c: Math.min(oklch.c, maxC) }, ceiling);
-}
-
 /**
- * Map every step of a scale into the ceiling, keeping lightness order.
+ * Map every step of a scale into the ceiling, keeping lightness and hue.
  *
- * A step already inside the ceiling is not moved. A step outside is mapped
- * with colorjs.io toGamut; where that mapping would break the scale's
- * strictly falling lightness, the step keeps its lightness and loses chroma
- * only. Steps already inside are never re-marked, so the loop ends: at worst
- * every outside step keeps its lightness, and the input order holds.
+ * A step already inside the ceiling is not moved. A step outside keeps its
+ * lightness and hue and loses chroma only, to the ceiling's edge, so the
+ * scale's lightness order is the input's.
  */
 export function mapScaleToGamut(scale: readonly OKLCH[], ceiling: GamutCeiling): OKLCH[] {
-  const chromaOnly = new Set<number>();
-  const mapStep = (step: OKLCH, i: number): OKLCH => {
-    if (inCeiling(step, ceiling)) return { ...step };
-    if (chromaOnly.has(i)) return reduceChromaOnly(step, ceiling);
-    return roundInside(toGamutCeiling(step, ceiling), ceiling);
-  };
-  let mapped = scale.map(mapStep);
-  for (;;) {
-    let marked = false;
-    for (let i = 1; i < mapped.length; i++) {
-      const prev = mapped[i - 1];
-      const cur = mapped[i];
-      if (prev === undefined || cur === undefined || cur.l < prev.l) continue;
-      for (const j of [i - 1, i]) {
-        const original = scale[j];
-        if (original && !chromaOnly.has(j) && !inCeiling(original, ceiling)) {
-          chromaOnly.add(j);
-          marked = true;
-        }
-      }
-    }
-    if (!marked) return mapped;
-    mapped = scale.map(mapStep);
-  }
+  return scale.map((step) =>
+    inCeiling(step, ceiling) ? { ...step } : roundInside(toGamutCeiling(step, ceiling), ceiling),
+  );
 }
 
 /**
@@ -172,12 +120,12 @@ export function storedTier(oklch: OKLCH): GamutCeiling {
 }
 
 /**
- * Snap an OKLCH into sRGB and round it -- the shape every generated color is
- * emitted in. Lives here because both halves are gamut/conversion concerns;
- * harmony.ts and semantic.ts are callers, not owners.
+ * Snap an OKLCH into sRGB and round it inside sRGB -- the shape every
+ * generated color is emitted in. Lives here because both halves are
+ * gamut/conversion concerns; harmony.ts and semantic.ts are callers, not owners.
  */
 export function clampColor(color: OKLCH): OKLCH {
-  return roundOKLCH(toNearestGamut(color).color);
+  return roundInside(toNearestGamut(color).color, 'srgb');
 }
 
 const DEFAULT_STEPS = 101;
@@ -196,7 +144,7 @@ const TOLERANCE = 0.001;
  * against 0.0227 at h=145, l=0.05. `inGamut` is the predicate this function
  * actually needs, and bisecting it is the only way to ask where it flips.
  */
-function findMaxChroma(l: number, h: number, gamutSpace: string): number {
+export function findMaxChroma(l: number, h: number, gamutSpace: string): number {
   let lo = 0;
   let hi = MAX_CHROMA;
   if (l <= 0 || l >= 1) return 0;

package/src/harmony.ts

@@ -2,10 +2,10 @@
  * Harmony generation for design systems using pure OKLCH hue rotation.
  *
  * Rule: harmonies are PURE HUE ROTATIONS. L and C are never mutated.
- * Only H changes. Every harmony output goes through toNearestGamut() then
- * roundOKLCH(). The scale is different: generateOKLCHScale returns unmapped
- * steps, and buildColorValue maps them into the family's ceiling with
- * mapScaleToGamut (gamut.ts).
+ * Only H changes. Every harmony output goes through clampColor(), which
+ * drops chroma into sRGB and rounds inside it. The scale is different:
+ * generateOKLCHScale returns unmapped steps, and buildColorValue maps them
+ * into the family's ceiling with mapScaleToGamut (gamut.ts).
  */
 
 import type { ColorHarmonies, OKLCH } from '@rafters/shared';

package/src/index.ts

@@ -37,6 +37,7 @@ export {
   hexToOKLCH,
   type OklchToCSSOptions,
   oklchToCSS,
+  oklchToSRGB,
   roundOKLCH,
   tryParseColor,
 } from './conversion.js';
@@ -59,6 +60,15 @@ export {
 // Harmony
 export { generateHarmony, generateOKLCHScale } from './harmony.js';
 
+// Normalized scale (#2872)
+export { createNormalizedScale } from './normalized-scale.js';
+export {
+  CHROMA_SHARE,
+  HUE_DRIFT_BANDS,
+  HUE_DRIFT_SAMPLES,
+  LIGHTNESS_LADDERS,
+} from './normalized-scale-constants.js';
+
 // Manipulation
 export { adjustHue } from './manipulation.js';
 // Naming

package/src/normalized-scale-constants.ts

@@ -0,0 +1,66 @@
+/**
+ * Measured constants for createNormalizedScale.
+ *
+ * Source: the hand-tuned palettes in platform's colour seed
+ * (apps/api/seed/colors.json) -- Tailwind, Material, Open Color, Ant and
+ * Chakra -- 66 chromatic palettes, each interpolated to 11 positions, median
+ * across palettes, measured 2026-10-26. Radix is excluded: its light and dark
+ * scales are mixed in the data. Every array runs lightest (50) to darkest (950).
+ */
+
+/**
+ * Step lightness, by ladder.
+ * deep: Tailwind, Ant and Chakra, 38 palettes (17, 12 and 9).
+ * compact: Material and Open Color, 28 palettes (16 and 12).
+ */
+export const LIGHTNESS_LADDERS = {
+  deep: [0.978, 0.942, 0.896, 0.827, 0.74, 0.67, 0.593, 0.52, 0.451, 0.392, 0.292],
+  compact: [0.964, 0.925, 0.874, 0.811, 0.762, 0.719, 0.677, 0.644, 0.6, 0.543, 0.49],
+} as const;
+
+/**
+ * Step chroma as a share of the sRGB chroma maximum at the step's lightness
+ * and hue.
+ * gamut: the maximum itself, by definition.
+ * measured: all five systems, 66 palettes.
+ */
+export const CHROMA_SHARE = {
+  gamut: [1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1],
+  measured: [0.97, 0.95, 0.92, 0.9, 0.94, 0.95, 0.97, 0.97, 0.97, 0.92, 0.94],
+} as const;
+
+/**
+ * Hue drift in degrees, relative to the palette's middle step (500), keyed by
+ * band centre hue (0 = red, 60 = amber, 90 = yellow, ... 330). All five
+ * systems, 66 palettes; the count per band is HUE_DRIFT_SAMPLES.
+ */
+export const HUE_DRIFT_BANDS = {
+  0: [-10.0, -9.1, -6.6, -4.6, -2.8, 0.0, -0.8, -2.2, -3.4, -4.6, -7.0],
+  30: [-7.0, -4.0, -5.4, -3.8, -2.4, 0.0, 0.0, -0.4, -1.3, -2.1, -2.5],
+  60: [25.5, 25.6, 22.4, 17.8, 10.2, 3.2, -2.4, -7.6, -11.1, -13.8, -16.0],
+  90: [11.0, 10.1, 10.0, 8.6, 6.0, 1.5, -3.6, -10.3, -17.6, -24.8, -32.0],
+  120: [-9.0, -7.2, -6.2, -4.0, -2.0, -0.5, 0.4, 1.0, 2.0, 2.0, 2.0],
+  150: [4.0, 1.6, 1.6, 1.2, 0.7, 0.0, 0.2, 0.6, 1.5, 2.5, 2.0],
+  180: [3.5, 2.6, 1.2, 1.2, 0.9, 0.5, 0.4, 1.0, 1.9, 1.5, 4.5],
+  210: [-10.0, -9.3, -8.4, -6.6, -3.4, -1.5, 0.4, 0.4, 1.2, 2.2, 4.0],
+  240: [-10.0, -8.1, -6.4, -7.0, -4.0, -1.0, 0.8, 2.6, 4.4, 6.1, 7.0],
+  270: [-4.0, -3.5, -2.2, -0.8, 0.5, 0.2, 0.2, 0.4, 0.0, 1.0, 2.0],
+  300: [7.0, 7.0, 6.2, 4.6, 2.6, 0.5, -1.2, -2.3, -2.5, -2.5, -2.5],
+  330: [-2.0, -0.4, 0.0, 0.7, 1.0, 0.5, 0.0, 0.0, 0.0, 0.0, 0.0],
+} as const;
+
+/** Palettes per hue band behind HUE_DRIFT_BANDS (66 in all); 330 (pink) rests on 3. */
+export const HUE_DRIFT_SAMPLES = {
+  0: 5,
+  30: 8,
+  60: 6,
+  90: 7,
+  120: 5,
+  150: 6,
+  180: 4,
+  210: 5,
+  240: 5,
+  270: 6,
+  300: 6,
+  330: 3,
+} as const;

package/src/normalized-scale.ts

@@ -0,0 +1,176 @@
+/**
+ * Normalized scale builder.
+ *
+ * A second way to build a colour family, beside buildColorValue: step
+ * lightness from a measured ladder bent through the source, step chroma at
+ * the source's own share of what sRGB holds, and step hue drifting toward
+ * both ends the way hand-tuned systems drift it. The constants are in normalized-scale-constants.ts.
+ */
+
+import type { ColorValue, OKLCH } from '@rafters/shared';
+import { assembleColorValue } from './builder.js';
+import { findMaxChroma, isInSRGBGamut, storedTier } from './gamut.js';
+import { normalizeHue } from './internal/math.js';
+import { CHROMA_SHARE, HUE_DRIFT_BANDS, LIGHTNESS_LADDERS } from './normalized-scale-constants.js';
+import { SCALE_POSITIONS } from './scale-positions.js';
+
+/** An option createNormalizedScale cannot build from. */
+export class NormalizedScaleError extends Error {
+  constructor(
+    public readonly option: 'lightness' | 'chroma' | 'hue',
+    message: string,
+  ) {
+    super(`createNormalizedScale: ${option} ${message}`);
+    this.name = 'NormalizedScaleError';
+  }
+}
+
+const STEP_COUNT = SCALE_POSITIONS.length;
+const BAND_WIDTH = 30;
+
+function checkLength(option: 'lightness' | 'chroma' | 'hue', values: readonly number[]): void {
+  if (values.length !== STEP_COUNT) {
+    throw new NormalizedScaleError(option, `must have ${STEP_COUNT} entries, got ${values.length}`);
+  }
+}
+
+function resolveLadder(lightness: number[] | 'deep' | 'compact'): readonly number[] {
+  if (typeof lightness === 'string') return LIGHTNESS_LADDERS[lightness];
+  checkLength('lightness', lightness);
+  for (let i = 1; i < lightness.length; i++) {
+    const prev = lightness[i - 1];
+    const cur = lightness[i];
+    if (prev === undefined || cur === undefined || cur >= prev) {
+      throw new NormalizedScaleError('lightness', 'must be strictly decreasing');
+    }
+  }
+  return lightness;
+}
+
+function resolveShare(chroma: number[] | 'gamut' | 'measured'): readonly number[] {
+  if (typeof chroma === 'string') return CHROMA_SHARE[chroma];
+  checkLength('chroma', chroma);
+  return chroma;
+}
+
+const DRIFT_BY_BAND: Readonly<Record<number, readonly number[]>> = HUE_DRIFT_BANDS;
+
+function bandDrift(band: number): readonly number[] {
+  return DRIFT_BY_BAND[normalizeHue(band)] ?? HUE_DRIFT_BANDS[0];
+}
+
+/** The measured drift for a hue, interpolated between the two nearest bands. */
+function measuredDrift(hue: number): number[] {
+  const h = normalizeHue(hue);
+  const lower = Math.floor(h / BAND_WIDTH) * BAND_WIDTH;
+  const t = (h - lower) / BAND_WIDTH;
+  const lo = bandDrift(lower);
+  const hi = bandDrift(lower + BAND_WIDTH);
+  return lo.map((d, i) => d * (1 - t) + (hi[i] ?? d) * t);
+}
+
+function resolveDrift(hue: number[] | 'measured' | 'none', sourceHue: number): readonly number[] {
+  if (hue === 'none') return Array.from({ length: STEP_COUNT }, () => 0);
+  if (hue === 'measured') return measuredDrift(sourceHue);
+  checkLength('hue', hue);
+  return hue;
+}
+
+/** The step whose ladder lightness is nearest the source's own. */
+function nearestStep(ladder: readonly number[], l: number): number {
+  let best = 0;
+  for (let i = 1; i < ladder.length; i++) {
+    const cur = ladder[i];
+    const bestL = ladder[best];
+    if (cur !== undefined && bestL !== undefined && Math.abs(cur - l) < Math.abs(bestL - l)) {
+      best = i;
+    }
+  }
+  return best;
+}
+
+/**
+ * Step lightness: the ladder bent toward the pin. Steps lighter than the
+ * anchor are re-spaced between the ladder's top and the pin, steps darker
+ * between the pin and the ladder's bottom, so the run has no gap.
+ */
+function bendLadder(ladder: readonly number[], anchor: number, pin: number): number[] {
+  const top = ladder[0] ?? pin;
+  const bottom = ladder[ladder.length - 1] ?? pin;
+  const at = ladder[anchor] ?? pin;
+  return ladder.map((lad, k) => {
+    if (k === anchor) return pin;
+    if (k < anchor) return top + ((pin - top) * (lad - top)) / (at - top);
+    return pin + ((bottom - pin) * (lad - at)) / (bottom - at);
+  });
+}
+
+/** Chroma floored to the stored precision, so a step at the sRGB edge stays inside. */
+function floorChroma(c: number): number {
+  return Math.floor(c * 1000) / 1000;
+}
+
+/**
+ * Chroma reduction into sRGB: a step outside keeps its lightness and hue
+ * exactly and takes the sRGB chroma maximum there.
+ */
+function reduceIntoSRGB(step: OKLCH): OKLCH {
+  if (isInSRGBGamut(step)) return step;
+  return { ...step, c: floorChroma(findMaxChroma(step.l, step.h, 'srgb')) };
+}
+
+/** Lightness at which every hue has room, for the source's chroma share. */
+const SHARE_REFERENCE_L = 0.6;
+
+/**
+ * Build a ColorValue on a normalized 11-step scale.
+ *
+ * The source is the pin, exactly as typed, at the step whose ladder lightness
+ * is nearest its own (the anchor). The other steps take the ladder bent
+ * toward the pin, the source's share of the sRGB chroma maximum (at L 0.6)
+ * times the chroma curve times the maximum at the step, and the source hue
+ * plus the drift relative to the anchor. A step outside sRGB, the anchor
+ * included, loses chroma only. Harmonies, accessibility, analysis and naming
+ * are buildColorValue's.
+ *
+ * @throws NormalizedScaleError when an array option does not have 11 entries,
+ *   or a lightness array is not strictly decreasing.
+ */
+export function createNormalizedScale(
+  source: OKLCH,
+  options: {
+    lightness?: number[] | 'deep' | 'compact';
+    chroma?: number[] | 'gamut' | 'measured';
+    hue?: number[] | 'measured' | 'none';
+  } = {},
+): ColorValue {
+  const lightness = options.lightness ?? 'deep';
+  const ladder = resolveLadder(lightness);
+  const curve = resolveShare(options.chroma ?? 'measured');
+  const drift = resolveDrift(options.hue ?? 'measured', source.h);
+
+  const anchor = nearestStep(ladder, source.l);
+  const anchorDrift = drift[anchor] ?? 0;
+  const stepL = bendLadder(ladder, anchor, source.l);
+  const referenceMax = findMaxChroma(SHARE_REFERENCE_L, source.h, 'srgb');
+  const seedShare = referenceMax > 0 ? Math.min(1, source.c / referenceMax) : 0;
+
+  const scale = stepL.map((rawL, i): OKLCH => {
+    if (i === anchor) return reduceIntoSRGB({ ...source });
+    const l = Math.round(rawL * 1000) / 1000;
+    const h = Math.round(normalizeHue(source.h + (drift[i] ?? 0) - anchorDrift));
+    const c = floorChroma(seedShare * (curve[i] ?? 0) * findMaxChroma(l, h, 'srgb'));
+    return reduceIntoSRGB({ l, c, h, alpha: source.alpha ?? 1 });
+  });
+  const gamut = scale.map(storedTier);
+
+  const landed = scale[anchor] ?? source;
+  const seedAdjusted: ColorValue['seedAdjusted'] =
+    landed.c !== source.c ? { from: { ...source }, to: { ...landed }, reason: 'gamut' } : undefined;
+
+  return {
+    ...assembleColorValue(source, { scale, gamut, seedAdjusted, reference: landed }, {}),
+    scaleStyle: typeof lightness === 'string' ? lightness : 'custom',
+    anchor: SCALE_POSITIONS[anchor],
+  };
+}