color-map 2.1.0 → 2.3.0

package/src/color/srgb-linear.ts

@@ -0,0 +1,9 @@
+import { srgbToXyz, xyzToSrgb } from './matrices.js'
+import { rgbSpace } from './rgb.js'
+import { identity } from './transfer.js'
+
+/**
+ * The CSS `srgb-linear` space: sRGB primaries without a transfer curve. Components are red, green and blue in 0 to 1.
+ * Pass it to `createConverter` and to the narrow helpers such as `createMix` and `createToGamut`.
+ */
+export const srgbLinear = rgbSpace('srgb-linear', identity, identity, srgbToXyz, xyzToSrgb)

package/src/color/srgb.ts

@@ -0,0 +1,9 @@
+import { srgbToXyz, xyzToSrgb } from './matrices.js'
+import { rgbSpace } from './rgb.js'
+import { srgbToGamma, srgbToLinear } from './transfer.js'
+
+/**
+ * The CSS `srgb` space. Components are red, green and blue in 0 to 1, with the sRGB transfer curve.
+ * Pass it to `createConverter` and to the narrow helpers such as `createMix` and `createToGamut`.
+ */
+export const srgb = rgbSpace('srgb', srgbToLinear, srgbToGamma, srgbToXyz, xyzToSrgb)

package/src/color/test-utils.ts

@@ -0,0 +1,10 @@
+/** Packs 0 to 1 channels into a rounded `rrggbb` string, for comparing colors across libraries. */
+export function hexOf(rgb: number[]): string {
+	return rgb
+		.map((v) =>
+			Math.round(v * 255)
+				.toString(16)
+				.padStart(2, '0')
+		)
+		.join('')
+}

package/src/color/transfer.ts

@@ -0,0 +1,14 @@
+import { signed } from './math.js'
+
+export const identity = (n: number): number => n
+
+export const srgbToLinear = signed((a) => (a <= 0.04045 ? a / 12.92 : ((a + 0.055) / 1.055) ** 2.4))
+export const srgbToGamma = signed((a) => (a > 0.0031308 ? 1.055 * a ** (1 / 2.4) - 0.055 : 12.92 * a))
+
+export const power = (gamma: number): [(n: number) => number, (n: number) => number] => [
+	signed((a) => a ** gamma),
+	signed((a) => a ** (1 / gamma))
+]
+
+export const prophotoToLinear = signed((a) => (a <= 16 / 512 ? a / 16 : a ** 1.8))
+export const prophotoToGamma = signed((a) => (a >= 1 / 512 ? a ** (1 / 1.8) : 16 * a))

package/src/color/types.ts

@@ -0,0 +1,41 @@
+/** The spaces a {@link Color} can be in. Names are the CSS ones. */
+export type ColorSpaceId =
+	| 'srgb'
+	| 'srgb-linear'
+	| 'hsl'
+	| 'hwb'
+	| 'lab'
+	| 'lch'
+	| 'oklab'
+	| 'oklch'
+	| 'display-p3'
+	| 'display-p3-linear'
+	| 'a98-rgb'
+	| 'prophoto-rgb'
+	| 'rec2020'
+	| 'xyz-d50'
+	| 'xyz-d65'
+
+/** A component value. `null` stands for the CSS keyword `none`. */
+export type Component = number | null
+
+/**
+ * A color as plain JSON. Component ranges follow CSS: `srgb` is 0 to 1, `hsl`
+ * and `hwb` take hue in degrees and the rest in 0 to 100, `lab` and `lch` take
+ * L in 0 to 100, `oklab` and `oklch` take L in 0 to 1. A missing `alpha` is 1.
+ */
+export interface Color {
+	colorSpace: ColorSpaceId
+	components: Component[]
+	alpha?: Component
+}
+
+/** Three numbers: the components of a color without alpha, or a point in XYZ. */
+export type Vec3 = [number, number, number]
+
+/** A color space, defined by its conversion to and from the XYZ-D65 hub. */
+export interface Space {
+	id: ColorSpaceId
+	toXyz(c: Vec3): Vec3
+	fromXyz(xyz: Vec3): Vec3
+}

package/src/color/unknown-name.ts

@@ -0,0 +1,15 @@
+/**
+ * The error for a name a caller wrote that the library does not know: it names
+ * the value and lists the valid ones, in the style of `unknown color space`.
+ */
+export function unknownName(what: string, value: unknown, valid: readonly string[]): Error {
+	return new Error(
+		`color-map: unknown ${what} "${String(value)}"${valid.length ? `; use one of ${valid.join(', ')}` : ''}`
+	)
+}
+
+/** `mode` itself when it is `light` or `dark`; any other value is an unknown mode. */
+export function checkMode<T>(mode: T): T {
+	if (mode !== 'light' && mode !== 'dark') throw unknownName('mode', mode, ['light', 'dark'])
+	return mode
+}

package/src/color/xyz-d50.ts

@@ -0,0 +1,13 @@
+import { multiply } from './math.js'
+import { d50ToD65, d65ToD50 } from './matrices.js'
+import type { Space } from './types.js'
+
+/**
+ * The CSS `xyz-d50` space (CIE XYZ, D50 white). Components are X, Y and Z, where Y is 1 for white.
+ * Pass it to `createConverter` and to the narrow helpers such as `createMix` and `createToGamut`.
+ */
+export const xyzD50: Space = {
+	id: 'xyz-d50',
+	toXyz: (c) => multiply(d50ToD65, c[0], c[1], c[2]),
+	fromXyz: (xyz) => multiply(d65ToD50, xyz[0], xyz[1], xyz[2])
+}

package/src/color/xyz-d65.ts

@@ -0,0 +1,8 @@
+import type { Space } from './types.js'
+
+/** The hub every other space converts through. */
+export const xyzD65: Space = {
+	id: 'xyz-d65',
+	toXyz: (c) => c,
+	fromXyz: (xyz) => xyz
+}

package/src/index.ts

@@ -0,0 +1,37 @@
+// The root re-exports the four subpaths, which stay the stable contract. The
+// legacy names stay here through 2.x, deprecated in favor of `color-map/legacy`,
+// and leave the root in 3.0. They are aliases rather than `export *` so that the
+// deprecation shows only at the root and not in `color-map/legacy`.
+import {
+	type Alpha as LegacyAlpha,
+	type ColorMap as LegacyColorMap,
+	type RGB as LegacyRGB,
+	type RGBA as LegacyRGBA,
+	createColors as legacyCreateColors,
+	createColorsFromMap as legacyCreateColorsFromMap,
+	rgbaString as legacyRgbaString,
+	rgbHex as legacyRgbHex
+} from './legacy/index.js'
+
+export * from './color/index.js'
+export * from './palette/index.js'
+export * from './scale/index.js'
+export * from './tokens/index.js'
+
+/** @deprecated Import it from `color-map/legacy`. The root stops exporting it in 3.0. */
+export const createColors = legacyCreateColors
+/** @deprecated Use `createGradient` from `color-map`, or import it from `color-map/legacy`. The root stops exporting it in 3.0. */
+export const createColorsFromMap = legacyCreateColorsFromMap
+/** @deprecated Import it from `color-map/legacy`, or use `toHex` from `color-map`. The root stops exporting it in 3.0. */
+export const rgbHex = legacyRgbHex
+/** @deprecated Import it from `color-map/legacy`, or use `toCss` from `color-map`. The root stops exporting it in 3.0. */
+export const rgbaString = legacyRgbaString
+
+/** @deprecated Import it from `color-map/legacy`. The root stops exporting it in 3.0. */
+export type Alpha = LegacyAlpha
+/** @deprecated Import it from `color-map/legacy`. The root stops exporting it in 3.0. */
+export type ColorMap = LegacyColorMap
+/** @deprecated Import it from `color-map/legacy`. The root stops exporting it in 3.0. */
+export type RGB = LegacyRGB
+/** @deprecated Import it from `color-map/legacy`. The root stops exporting it in 3.0. */
+export type RGBA = LegacyRGBA

package/src/legacy/createColors.ts

@@ -0,0 +1,36 @@
+import type { Alpha, RGB, RGBA } from './interfaces.js'
+
+/**
+ * Creates `shades` colors that step evenly from `from` to `to`. Red, green and
+ * blue are rounded to whole numbers. Without `alpha`, the alpha of each end
+ * comes from its own fourth value, then from the other end, then is 1.
+ * Every result is an `RGBA`.
+ */
+export function createColors(
+	from: RGB | RGBA,
+	to: RGB | RGBA,
+	shades: number,
+	alpha: Alpha = [
+		from.length === 4 ? from[3] : to.length === 4 ? to[3] : 1,
+		to.length === 4 ? to[3] : from.length === 4 ? from[3] : 1
+	]
+): RGBA[] {
+	const start = [...from]
+	const diff = [to[0] - from[0], to[1] - from[1], to[2] - from[2], alpha[1] - alpha[0]]
+
+	if (start.length === 3) start.push(alpha[0])
+
+	const inc = 1 / Math.max(shades - 1, 1)
+
+	const rgba: any[] = []
+	for (let i = 0; i < shades; i++) {
+		const color = [
+			Math.round(start[0] + i * diff[0] * inc),
+			Math.round(start[1] + i * diff[1] * inc),
+			Math.round(start[2] + i * diff[2] * inc),
+			start[3] + i * diff[3] * inc
+		]
+		rgba.push(color)
+	}
+	return rgba
+}

package/src/legacy/createColorsFromMap.ts

@@ -0,0 +1,29 @@
+import { createColors } from './createColors.js'
+import type { Alpha, ColorMap, RGBA } from './interfaces.js'
+
+/**
+ * Create colors with specified color map.
+ *
+ * @deprecated Use `createGradient` from `color-map`. Each of its stops
+ * carries its own alpha, and `{ in: 'srgb' }` comes close to these results.
+ */
+export function createColorsFromMap(colormap: ColorMap, shades: number, alpha?: Alpha): RGBA[] {
+	if (shades < colormap.length) {
+		throw new Error(`Requires at least ${colormap.length} shades.`)
+	}
+
+	const result: RGBA[] = []
+	const steps: number[] = []
+	for (let i = 0; i < colormap.length; i++) {
+		steps.push(Math.round(colormap[i].index * shades))
+	}
+
+	for (let i = 0; i < colormap.length - 1; i++) {
+		const n = steps[i + 1] - steps[i]
+		const from = colormap[i].rgb
+		const to = colormap[i + 1].rgb
+		result.push(...createColors(from, to, n, alpha))
+	}
+
+	return result
+}

package/src/legacy/interfaces.ts

@@ -0,0 +1,19 @@
+/** Red, green and blue as whole numbers in 0 to 255. */
+export type RGB = [number, number, number]
+/** Red, green and blue as whole numbers in 0 to 255, then alpha in 0 to 1. */
+export type RGBA = [number, number, number, number]
+/** The alpha at the start and at the end of a run of colors, each in 0 to 1. */
+export type Alpha = [number, number]
+
+/** The segments of a gradient, in order, for `createColorsFromMap`. Each has an `index` and an `rgb`. */
+export type ColorMap = {
+	/**
+	 * Defines how fast or slow the `rgb` values will change from one segment to the next.
+	 * i.e. the steepness of the gradient between two segments.
+	 */
+	index: number
+	/**
+	 * RGB or RGBA. if RGBA, this alpha will be used instead of the alpha specified in the call.
+	 */
+	rgb: RGB | RGBA
+}[]

package/{ts → src/legacy}/rgbHex.ts

@@ -5,14 +5,14 @@ import type { RGB, RGBA } from './interfaces.js'
  * JavaScript note: no check for array length, use it properly.
  */
 export function rgbHex(rgb: RGB | RGBA) {
-  let hex = '#'
-  for (let i = 0; i < 3; i++) {
-    hex += d2h(rgb[i])
-  }
-  return hex
+	let hex = '#'
+	for (let i = 0; i < 3; i++) {
+		hex += d2h(rgb[i])
+	}
+	return hex
 }
 
 function d2h(d: number) {
-  const s = (+d).toString(16)
-  return s.length < 2 ? '0' + s : s
+	const s = (+d).toString(16)
+	return s.length < 2 ? '0' + s : s
 }

package/src/legacy/rgbaString.ts

@@ -0,0 +1,6 @@
+import type { RGBA } from './interfaces.js'
+
+/** Formats an `RGBA` as a CSS `rgba(r,g,b,a)` string, with no spaces. */
+export function rgbaString(rgba: RGBA) {
+	return 'rgba(' + rgba.join(',') + ')'
+}

package/src/palette/dark.ts

@@ -0,0 +1,55 @@
+import { type GamutId, toGamut } from '../color/gamut.js'
+import { componentsIn } from '../color/spaces.js'
+import type { Color } from '../color/types.js'
+import { unknownName } from '../color/unknown-name.js'
+import { lstar, toneColor } from '../scale/tone.js'
+
+/** How `darkVariant` builds a dark scale from a light one: `mirror`, `tone-swap` or `lightness-invert`. */
+export type DarkStrategy = 'mirror' | 'tone-swap' | 'lightness-invert'
+
+const STRATEGIES: readonly string[] = ['mirror', 'tone-swap', 'lightness-invert']
+
+/** Options for `darkVariant`. */
+export interface DarkVariantOptions {
+	/** The gamut every color must fit. Default `srgb`. */
+	gamut?: GamutId
+}
+
+/**
+ * A dark version of a light scale (ordered light to dark), with the same
+ * number of steps.
+ * - `mirror`: step n takes the color of step N+1-n, so the scale runs dark to
+ *   light and step 1 is the old last step. Colors are unchanged.
+ * - `tone-swap`: each color keeps its OKLCH hue and chroma and takes the CIE
+ *   L* tone 100 minus its own, as Material swaps tone 40 for 80. Contrast
+ *   between two steps is kept roughly the same.
+ * - `lightness-invert`: OKLCH lightness is reflected within the scale's own
+ *   range, keeping step order, with chroma eased by 10% to curb vibration on
+ *   dark backgrounds.
+ */
+export function darkVariant(
+	scale: readonly Color[],
+	strategy: DarkStrategy = 'tone-swap',
+	options: DarkVariantOptions = {}
+): Color[] {
+	const { gamut = 'srgb' } = options
+	if (!STRATEGIES.includes(strategy)) throw unknownName('dark variant strategy', strategy, STRATEGIES)
+	if (strategy === 'mirror') return [...scale].reverse()
+	if (strategy === 'tone-swap') {
+		return scale.map((c) => {
+			const [, chroma, hue] = componentsIn(c, 'oklch') as [number, number, number | null]
+			return withAlpha(toneColor(100 - lstar(c), chroma, hue ?? 0, gamut), c)
+		})
+	}
+	const oklch = scale.map((c) => componentsIn(c, 'oklch') as [number, number, number | null])
+	const ls = oklch.map((c) => c[0])
+	const sum = Math.min(...ls) + Math.max(...ls)
+	return scale.map((c, i) => {
+		const [l, chroma, hue] = oklch[i] as [number, number, number | null]
+		return withAlpha(toGamut({ colorSpace: 'oklch', components: [sum - l, chroma * 0.9, hue] }, { gamut }), c)
+	})
+}
+
+function withAlpha(color: Color, from: Color): Color {
+	return from.alpha === undefined ? color : { ...color, alpha: from.alpha }
+}

package/src/palette/harmony.ts

@@ -0,0 +1,107 @@
+import { type GamutId, toGamut } from '../color/gamut.js'
+import { normalizeHue } from '../color/math.js'
+import { toColor } from '../color/parse.js'
+import { convert } from '../color/spaces.js'
+import type { Color } from '../color/types.js'
+import { unknownName } from '../color/unknown-name.js'
+
+type ColorInput = Color | string
+
+/** The hue rotations, in degrees, that each scheme adds to the base color. */
+const SCHEMES = {
+	__proto__: null,
+	complementary: [0, 180],
+	split: [0, 150, 210],
+	analogous: [-30, 0, 30],
+	triadic: [0, 120, 240],
+	tetradic: [0, 90, 180, 270]
+} as const
+
+/** A harmony scheme `harmony` accepts: `complementary`, `split`, `analogous`, `triadic` or `tetradic`. */
+export type HarmonyScheme = keyof typeof SCHEMES
+
+/** Spaces with a hue channel that a scheme can rotate in. */
+export type HarmonySpace = 'oklch' | 'lch' | 'hsl' | 'hwb'
+
+/** Options for `harmony`. */
+export interface HarmonyOptions {
+	/** The space whose hue is rotated. Default `oklch`, which keeps perceived lightness steady. */
+	space?: HarmonySpace
+	/** The gamut every color must fit. Default `srgb`. */
+	gamut?: GamutId
+}
+
+const HUE_SPACES: readonly string[] = ['oklch', 'lch', 'hsl', 'hwb']
+
+const hueIndex = (space: HarmonySpace): number => (space === 'hsl' || space === 'hwb' ? 0 : 2)
+
+/**
+ * The colors of a harmony: `color` rotated around the hue wheel of `space`,
+ * with lightness and chroma held, in the order of the scheme's angles
+ * (`complementary` 0 and 180; `split` 0, 150, 210; `analogous` -30, 0, 30;
+ * `triadic` 0, 120, 240; `tetradic` 0, 90, 180, 270). The color itself is the
+ * entry at angle 0, returned as given. Rotated colors are mapped into `gamut`.
+ * The same angle looks different in `hsl` and `oklch`, so name the space.
+ */
+export function harmony(color: ColorInput, scheme: HarmonyScheme, options: HarmonyOptions = {}): Color[] {
+	const { space = 'oklch', gamut = 'srgb' } = options
+	const angles = SCHEMES[scheme]
+	if (!angles) throw unknownName('harmony scheme', scheme, Object.keys(SCHEMES))
+	if (!HUE_SPACES.includes(space)) throw unknownName('harmony space', space, HUE_SPACES)
+	const base = toColor(color)
+	const inSpace = convert(base, space)
+	const at = hueIndex(space)
+	const hue = (inSpace.components[at] as number | null) ?? 0
+	return angles.map((angle) => {
+		if (angle === 0) return base
+		const components = [...inSpace.components]
+		components[at] = normalizeHue(hue + angle)
+		return toGamut({ ...inSpace, components }, { gamut })
+	})
+}
+
+/** Options for `harmonize`. */
+export interface HarmonizeOptions {
+	/** The most the hue may move, in degrees. Default 15. */
+	max?: number
+	/** The share of the hue difference to move. Default 0.5. */
+	factor?: number
+	/** The gamut the result must fit. Default `srgb`. */
+	gamut?: GamutId
+}
+
+/**
+ * Nudges `color`'s hue toward `toward`, as Material's `Blend.harmonize` does:
+ * by half the hue difference, but at most 15 degrees, in OKLCH, keeping
+ * lightness and chroma. Use it to make a status color feel at home with a
+ * brand color without changing its meaning.
+ */
+export function harmonize(color: ColorInput, toward: ColorInput, options: HarmonizeOptions = {}): Color {
+	const { max = 15, factor = 0.5, gamut = 'srgb' } = options
+	const from = convert(toColor(color), 'oklch')
+	const to = convert(toColor(toward), 'oklch')
+	const h0 = (from.components[2] as number | null) ?? 0
+	const h1 = (to.components[2] as number | null) ?? h0
+	// Signed shortest way round, -180 to 180.
+	const diff = normalizeHue(h1 - h0 + 180) - 180
+	const rotation = Math.min(Math.abs(diff) * factor, max) * Math.sign(diff)
+	const components = [...from.components]
+	components[2] = normalizeHue(h0 + rotation)
+	return toGamut({ ...from, components }, { gamut })
+}
+
+/**
+ * The opposite of a color. `lightness` flips OKLCH lightness (L becomes 1 - L)
+ * and keeps hue and chroma, so light turns dark without changing its hue;
+ * `rgb` inverts each sRGB channel, which also turns the hue to its complement.
+ * Alpha is kept. The result is mapped into sRGB.
+ */
+export function inverse(color: ColorInput, mode: 'lightness' | 'rgb' = 'lightness'): Color {
+	const base = toColor(color)
+	if (mode === 'rgb') {
+		const c = convert(base, 'srgb')
+		return toGamut({ ...c, components: c.components.map((x) => 1 - (x as number)) })
+	}
+	const c = convert(base, 'oklch')
+	return toGamut({ ...c, components: [1 - (c.components[0] as number), c.components[1], c.components[2]] })
+}

package/src/palette/index.ts

@@ -0,0 +1,18 @@
+export { type DarkStrategy, type DarkVariantOptions, darkVariant } from './dark.js'
+export {
+	type HarmonizeOptions,
+	type HarmonyOptions,
+	type HarmonyScheme,
+	type HarmonySpace,
+	harmonize,
+	harmony,
+	inverse
+} from './harmony.js'
+export {
+	type RolePair,
+	type SemanticPalette,
+	type SemanticPaletteOptions,
+	type SemanticRole,
+	semanticPalette
+} from './semantic.js'
+export { type PaletteIssue, type PaletteLike, type ValidateOptions, type ValidateResult, validate } from './validate.js'

package/src/palette/semantic.ts

@@ -0,0 +1,120 @@
+import { type ContrastOption, findContrast, pick } from '../color/contrast.js'
+import type { GamutId } from '../color/gamut.js'
+import { toColor } from '../color/parse.js'
+import { componentsIn } from '../color/spaces.js'
+import type { Color } from '../color/types.js'
+import { checkMode } from '../color/unknown-name.js'
+import { tonalPalette, toneColor } from '../scale/tone.js'
+import { harmonize } from './harmony.js'
+
+/** A background, the foreground drawn on it, and the contrast they reach. */
+export interface RolePair {
+	bg: Color
+	fg: Color
+	/** The contrast of `fg` on `bg`, as the algorithm reports it (absolute value). */
+	ratio: number
+	/** The contrast the pair was built to reach. */
+	target: number
+}
+
+/** Options for `semanticPalette`. Only `brand` is required. */
+export interface SemanticPaletteOptions {
+	/** The brand color; it sets the hue of the primary, the neutrals and the harmonized status colors. */
+	brand: Color | string
+	/** Default `light`. */
+	mode?: 'light' | 'dark'
+	/** The contrast measure. Default `wcag2`. */
+	contrast?: ContrastOption
+	/** The contrast text pairs must reach. Default 4.5, which fits WCAG 2 (pass about 60 for APCA Lc). */
+	target?: number
+	/** The gamut every color must fit. Default `srgb`. */
+	gamut?: GamutId
+}
+
+/** A role in a {@link SemanticPalette}. Each role holds a {@link RolePair}. */
+export type SemanticRole =
+	| 'primary'
+	| 'primaryContainer'
+	| 'success'
+	| 'warning'
+	| 'danger'
+	| 'info'
+	| 'surface'
+	| 'surfaceVariant'
+	| 'outline'
+
+/** What `semanticPalette` returns: the settings it used, the tonal scales it built from, and a pair for each role. */
+export interface SemanticPalette {
+	meta: { mode: 'light' | 'dark'; contrast: string; target: number; gamut: GamutId }
+	/** Material's 13 tones, dark to light, in the brand's hue (`primary`) and a faint tint of it (`neutral`). */
+	scales: { primary: Color[]; neutral: Color[] }
+	roles: Record<SemanticRole, RolePair>
+}
+
+// Tones (light, dark) per role: Material's 2021 assignments (see the research notes, B-palettes).
+const BG_TONE = { primary: [40, 80], primaryContainer: [90, 30], surface: [98, 6], surfaceVariant: [90, 30] } as const
+const FG_TONE = { primary: [100, 20], primaryContainer: [10, 90], surface: [10, 90], surfaceVariant: [30, 80] } as const
+
+// OKLCH hues of the status colors, before they are harmonized toward the brand.
+const STATUS = { success: 145, warning: 85, danger: 25, info: 240 } as const
+
+/**
+ * A role-based palette from one brand color: primary and its container, four
+ * status colors (success, warning, danger, info) harmonized toward the brand's
+ * hue, a surface and a variant tinted by the brand hue, and an outline. Every
+ * pair is built from L* tones, so a 50-tone gap or more reaches about 4.5 on
+ * WCAG 2 (the worst pair, 100 on 50, gives 4.48). Each pair records the ratio
+ * it reached; a foreground that falls short of `target` is replaced by the
+ * closest one that meets it, and `validate` reports any that cannot.
+ */
+export function semanticPalette(options: SemanticPaletteOptions): SemanticPalette {
+	const { mode = 'light', contrast = 'wcag2', target = 4.5, gamut = 'srgb' } = options
+	const fn = pick(contrast)
+	const dark = checkMode(mode) === 'dark'
+	const i = dark ? 1 : 0
+	const brand = toColor(options.brand)
+	const [, c, h] = componentsIn(brand, 'oklch') as [number, number, number | null]
+	const hue = h ?? 0
+	const chroma = Math.max(c, 0.04)
+	const tint = 0.015
+
+	const pair = (bg: Color, fgTone: number, fgChroma: number, need = target): RolePair => {
+		let fg = toneColor(fgTone, fgChroma, hue, gamut)
+		let ratio = Math.abs(fn(fg, bg))
+		if (ratio < need) {
+			const found = findContrast(bg, need, { contrast: fn, chroma: fgChroma, hue })
+			fg = found.color
+			ratio = Math.abs(found.contrast)
+		}
+		return { bg, fg, ratio, target: need }
+	}
+	const status = (name: keyof typeof STATUS): RolePair => {
+		const base = toneColor(BG_TONE.primary[i], 0.14, STATUS[name], gamut)
+		return pair(harmonize(base, brand, { gamut }), FG_TONE.primary[i], 0.02)
+	}
+	const surface = toneColor(BG_TONE.surface[i], tint, hue, gamut)
+	const outline = pair(surface, dark ? 60 : 50, tint, 3)
+
+	return {
+		meta: { mode, contrast: fn.algorithm ?? 'custom', target, gamut },
+		scales: {
+			primary: tonalPalette(hue, chroma, undefined, { gamut }),
+			neutral: tonalPalette(hue, tint, undefined, { gamut })
+		},
+		roles: {
+			primary: pair(toneColor(BG_TONE.primary[i], chroma, hue, gamut), FG_TONE.primary[i], 0.02),
+			primaryContainer: pair(
+				toneColor(BG_TONE.primaryContainer[i], chroma, hue, gamut),
+				FG_TONE.primaryContainer[i],
+				0.02
+			),
+			success: status('success'),
+			warning: status('warning'),
+			danger: status('danger'),
+			info: status('info'),
+			surface: pair(surface, FG_TONE.surface[i], tint),
+			surfaceVariant: pair(toneColor(BG_TONE.surfaceVariant[i], tint, hue, gamut), FG_TONE.surfaceVariant[i], tint),
+			outline
+		}
+	}
+}

package/src/palette/validate.ts

@@ -0,0 +1,82 @@
+import { type ContrastOption, pick } from '../color/contrast.js'
+import { type GamutId, inGamut } from '../color/gamut.js'
+import { componentsIn } from '../color/spaces.js'
+import type { Color } from '../color/types.js'
+import type { RolePair } from './semantic.js'
+
+/** What `validate` accepts: a {@link SemanticPalette}, or any object with role pairs and/or scales. */
+export interface PaletteLike {
+	roles?: Record<string, RolePair>
+	scales?: Record<string, readonly Color[]>
+}
+
+/** Options for `validate`. */
+export interface ValidateOptions {
+	/** The measure used to re-check each pair. Default `wcag2`. */
+	contrast?: ContrastOption
+	/** The target for a pair that carries none. Default 4.5. */
+	target?: number
+	/** The gamut colors must fit; a color outside it was clipped or never mapped. Default `srgb`. */
+	gamut?: GamutId
+}
+
+/** One problem `validate` found in a palette. */
+export interface PaletteIssue {
+	kind: 'contrast' | 'lightness' | 'gamut'
+	/** Where: `roles.danger`, `scales.primary[3]`. */
+	path: string
+	message: string
+}
+
+/** What `validate` returns: `ok` is true when `issues` is empty. */
+export interface ValidateResult {
+	ok: boolean
+	issues: PaletteIssue[]
+}
+
+/**
+ * Checks a palette and lists what is wrong, so an agent can fix it:
+ * - `contrast`: a role pair whose measured contrast is under its target;
+ * - `lightness`: a scale whose OKLCH lightness does not change steadily in one
+ *   direction from one step to the next;
+ * - `gamut`: a color outside the gamut (it would be clipped on display).
+ */
+export function validate(palette: PaletteLike, options: ValidateOptions = {}): ValidateResult {
+	const { contrast = 'wcag2', target = 4.5, gamut = 'srgb' } = options
+	const fn = pick(contrast)
+	const issues: PaletteIssue[] = []
+	const outside = (path: string, color: Color) => {
+		if (!inGamut(color, gamut)) issues.push({ kind: 'gamut', path, message: `${path} is outside ${gamut}` })
+	}
+
+	for (const [name, p] of Object.entries(palette.roles ?? {})) {
+		const need = p.target ?? target
+		const ratio = Math.abs(fn(p.fg, p.bg))
+		if (ratio < need)
+			issues.push({
+				kind: 'contrast',
+				path: `roles.${name}`,
+				message: `roles.${name} reaches ${ratio.toFixed(2)}, needs ${need}`
+			})
+		outside(`roles.${name}.bg`, p.bg)
+		outside(`roles.${name}.fg`, p.fg)
+	}
+
+	for (const [name, scale] of Object.entries(palette.scales ?? {})) {
+		const ls = scale.map((c) => componentsIn(c, 'oklch')[0] as number)
+		const steps = ls.slice(1).map((l, k) => l - (ls[k] as number))
+		const direction = Math.sign(steps.find((d) => d !== 0) ?? 0)
+		steps.forEach((d, k) => {
+			if (Math.sign(d) !== direction || Math.abs(d) < 1e-9)
+				issues.push({
+					kind: 'lightness',
+					path: `scales.${name}[${k + 1}]`,
+					message: `scales.${name} lightness does not change steadily at step ${k + 1}`
+				})
+		})
+		scale.forEach((c, k) => {
+			outside(`scales.${name}[${k}]`, c)
+		})
+	}
+	return { ok: issues.length === 0, issues }
+}