color-map 2.1.0 → 2.3.0

package/src/scale/brand.ts

@@ -0,0 +1,50 @@
+import type { GamutId } from '../color/gamut.js'
+import { toGamut } 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'
+
+/** Options for `scaleFromBrand`. */
+export interface BrandScaleOptions {
+	/** `light` runs from a near-white step 1 to dark text; `dark` the other way. Default `light`. */
+	mode?: 'light' | 'dark'
+	/** The page background, whose lightness step 1 takes. Default near-white, or near-black in `dark`. */
+	background?: Color | string
+	/** The gamut steps other than 9 must fit. Default `srgb`. */
+	gamut?: GamutId
+}
+
+// Radix-like lightness shapes, steps 1 to 9, as fractions of the way from
+// step 1 to step 9; chroma of steps 1 to 8 as multiples of the brand's.
+const LIGHT_PROGRESS = [0, 0.0376, 0.1, 0.1796, 0.2606, 0.3466, 0.4656, 0.6312, 1]
+const CHROMA = [0.04, 0.08, 0.2, 0.32, 0.43, 0.52, 0.6, 0.75]
+
+/**
+ * A 12-step UI scale from one brand color, after Radix's palette generator:
+ * the brand color is step 9 exactly (returned as given, never remapped), steps
+ * 1 to 8 run from the background to it, step 10 is its hover state, and steps
+ * 11 and 12 are low- and high-contrast text. Hue is the brand's throughout.
+ * Radix's generator also borrows the shape of the nearest of its hand-tuned
+ * scales; this one uses a single fixed shape instead.
+ */
+export function scaleFromBrand(brand: Color | string, options: BrandScaleOptions = {}): Color[] {
+	const { mode = 'light', gamut = 'srgb' } = options
+	const dark = checkMode(mode) === 'dark'
+	const exact = toColor(brand)
+	const [l9, c9, h9] = componentsIn(exact, 'oklch') as [number, number, number | null]
+	const hue = h9 ?? 0
+	const bg = options.background
+	const l1 = bg ? (componentsIn(toColor(bg), 'oklch')[0] as number) : dark ? 0.18 : 0.992
+	const step = (l: number, c: number): Color => toGamut({ colorSpace: 'oklch', components: [l, c, hue] }, { gamut })
+
+	const out: Color[] = []
+	for (let i = 0; i < 8; i++) out.push(step(l1 + (l9 - l1) * (LIGHT_PROGRESS[i] as number), c9 * (CHROMA[i] as number)))
+	out.push(exact)
+	const hover = 0.03 / (l9 + 0.1)
+	out.push(step(dark ? l9 + hover : l9 - hover, c9 * 0.93))
+	const c8 = c9 * (CHROMA[7] as number)
+	out.push(step(dark ? 0.78 : 0.5, Math.min(c9 * 0.9, Math.max(c8, c9))))
+	out.push(step(dark ? 0.93 : 0.3, Math.min(c9 * 0.35, Math.max(c8, c9))))
+	return out
+}

package/src/scale/contrast-scale.ts

@@ -0,0 +1,48 @@
+import { type ContrastOption, findContrast } from '../color/contrast.js'
+import { toColor } from '../color/parse.js'
+import { componentsIn } from '../color/spaces.js'
+import type { Color } from '../color/types.js'
+
+/** Options for `createContrastScale`. */
+export interface ContrastScaleOptions {
+	/** The color the scale is built around: its hue and chroma carry to every step. */
+	seed: Color | string
+	/** What every step is measured against. */
+	background: Color | string
+	/** Target contrast per step, in order, or a record of named targets (`{ text: 7, border: 3 }`). */
+	targets: number[] | Record<string, number>
+	/** Default `wcag2`. */
+	contrast?: ContrastOption
+	/** Which way to look first from the background. Default: darker on a light background, lighter on a dark one. */
+	direction?: 'lighter' | 'darker'
+}
+
+/** One step of a contrast scale: the target it was given and the color and contrast it got. */
+export interface ContrastStep {
+	/** The key in a record of targets; otherwise the step's index as a string. */
+	name: string
+	target: number
+	color: Color
+	/** The contrast the color achieves, measured on the color itself. */
+	contrast: number
+	/** False when no lightness reaches `target`; `color` is then the best one found. */
+	met: boolean
+}
+
+/**
+ * A Leonardo-style scale: each step is the color nearest the background's
+ * lightness, at the seed's hue and chroma, that reaches its target contrast.
+ * Contrast is the same across hues, which a fixed-lightness scale cannot give.
+ */
+export function createContrastScale(options: ContrastScaleOptions): ContrastStep[] {
+	const { seed, background, targets, contrast, direction } = options
+	const [, chroma, hue] = componentsIn(toColor(seed), 'oklch') as [number, number, number | null]
+	const entries: [string, number][] = Array.isArray(targets)
+		? targets.map((t, i) => [String(i), t])
+		: Object.entries(targets)
+	return entries.map(([name, target]) => ({
+		name,
+		target,
+		...findContrast(background, target, { hue: hue ?? 0, chroma, contrast, direction })
+	}))
+}

package/src/scale/gradient.ts

@@ -0,0 +1,91 @@
+import { type MixOptions, mix } from '../color/mix.js'
+import { toColor } from '../color/parse.js'
+import type { Color } from '../color/types.js'
+
+/** A color at a position on the gradient line. */
+export interface GradientStop {
+	/** A CSS color string or a color object. Its alpha is the stop's alpha. */
+	color: Color | string
+	/**
+	 * Where the stop sits, with 0 the start and 1 the end; it may fall outside
+	 * 0 to 1. Leave it out to spread the stop evenly between its neighbors, as
+	 * CSS gradients do.
+	 */
+	at?: number
+}
+
+/** `in` and `hue` work as they do in `mix()`. The default space is `oklab`. */
+export type GradientOptions = MixOptions
+
+/**
+ * Places each stop the way CSS gradients do (CSS Images 3 section 3.5.3): a
+ * first stop without a position goes at 0 and a last one at 1, a position
+ * before an earlier stop's moves up to it, and a run of stops without a
+ * position spreads evenly between the stops around it.
+ */
+function positions(stops: readonly GradientStop[]): number[] {
+	const n = stops.length
+	const at: (number | undefined)[] = stops.map((s, i) => {
+		if (s.at !== undefined && !Number.isFinite(s.at)) throw new Error(`stop ${i} has a position of ${s.at}`)
+		return s.at
+	})
+	if (at[0] === undefined) at[0] = 0
+	if (at[n - 1] === undefined) at[n - 1] = 1
+	let max = Number.NEGATIVE_INFINITY
+	for (let i = 0; i < n; i++) {
+		const p = at[i]
+		if (p !== undefined) at[i] = max = Math.max(max, p)
+	}
+	for (let i = 1; i < n; i++) {
+		if (at[i] !== undefined) continue
+		let j = i
+		while (at[j] === undefined) j++
+		const from = at[i - 1] as number
+		const step = ((at[j] as number) - from) / (j - i + 1)
+		for (let k = i; k < j; k++) at[k] = from + step * (k - i + 1)
+	}
+	return at as number[]
+}
+
+/**
+ * Builds `count` colors, evenly spaced from 0 to 1 along a gradient through
+ * `stops`, the way a CSS gradient blends them: each pair of neighboring stops
+ * is mixed with `mix()`, so `in` and `hue` work as they do there. A stop is
+ * `{ color, at? }`, or a bare color when it needs no position. Before the
+ * first stop and after the last, the color holds; where two stops share a
+ * position, the color changes there and the sample at that position takes the
+ * later stop. Colors come back in the `in` space, default `oklab`.
+ *
+ * Alpha comes from each stop's color, 1 when the color has none, so
+ * `rgb(0 0 255 / 0.2)` is a stop at alpha 0.2. Alpha is interpolated linearly
+ * between stops, and the other components are premultiplied by it, so a
+ * transparent stop does not pull its neighbor's color toward its own. A color
+ * whose alpha is 1 has no `alpha` key; a `none` alpha takes the neighboring
+ * stop's.
+ *
+ * ```ts
+ * createGradient([{ color: 'blue', at: 0 }, { color: 'lime', at: 0.6 }, { color: 'yellow', at: 1 }], 72)
+ * createGradient(['blue', 'lime'], 5, { in: 'oklch' })
+ * ```
+ */
+export function createGradient(
+	stops: readonly (GradientStop | Color | string)[],
+	count: number,
+	options: GradientOptions = {}
+): Color[] {
+	if (stops.length < 2) throw new Error(`a gradient needs at least 2 stops, got ${stops.length}`)
+	if (!Number.isInteger(count) || count < 2) throw new Error(`count must be an integer of at least 2, got ${count}`)
+	const list = stops.map((s): GradientStop => (typeof s === 'string' || 'colorSpace' in s ? { color: s } : s))
+	const colors = list.map((s) => toColor(s.color))
+	const at = positions(list)
+	const last = list.length - 2
+	return Array.from({ length: count }, (_, i) => {
+		const t = i / (count - 1)
+		let s = 0
+		while (s < last && (at[s + 1] as number) <= t) s++
+		const from = at[s] as number
+		const width = (at[s + 1] as number) - from
+		const local = width > 0 ? Math.min(1, Math.max(0, (t - from) / width)) : t < from ? 0 : 1
+		return mix(colors[s] as Color, colors[s + 1] as Color, local, options)
+	})
+}

package/src/scale/index.ts

@@ -0,0 +1,5 @@
+export { type BrandScaleOptions, scaleFromBrand } from './brand.js'
+export { type ContrastScaleOptions, type ContrastStep, createContrastScale } from './contrast-scale.js'
+export { createGradient, type GradientOptions, type GradientStop } from './gradient.js'
+export { createScale, type ScaleOptions, type ScalePreset } from './scale.js'
+export { lstar, MATERIAL_TONES, type TonalPaletteOptions, tonalPalette, toneColor } from './tone.js'

package/src/scale/scale.ts

@@ -0,0 +1,127 @@
+import type { GamutId } from '../color/gamut.js'
+import { toGamut } from '../color/gamut.js'
+import { toColor } from '../color/parse.js'
+import { componentsIn } from '../color/spaces.js'
+import type { Color } from '../color/types.js'
+import { unknownName } from '../color/unknown-name.js'
+import { MATERIAL_TONES, toneColor } from './tone.js'
+
+/** The built-in step curves. */
+export type ScalePreset = 'tailwind-11' | 'radix-12' | 'tone-13' | 'even'
+
+/** A step curve. `chroma` and `hueShift` are relative to the step at `anchor`, which takes the seed's own. */
+interface Curve {
+	/** OKLCH lightness 0 to 1, or CIE L* tones 0 to 100 when `tone` is set. */
+	lightness: number[]
+	chroma: number[]
+	hueShift: number[]
+	anchor: number
+	tone?: boolean
+}
+
+// Tailwind v4 blue, 50 to 950. The preset is this one hand-tuned scale, so a
+// seed of blue-500 gives Tailwind's blue back, and other hues get its shape.
+// biome-ignore lint/suspicious/noApproximativeNumericConstant: 0.707 is Tailwind blue-400's lightness, not 1/sqrt(2)
+const TW_L = [0.97, 0.932, 0.882, 0.809, 0.707, 0.623, 0.546, 0.488, 0.424, 0.379, 0.282]
+const TW_C = [0.014, 0.032, 0.059, 0.105, 0.165, 0.214, 0.245, 0.243, 0.199, 0.146, 0.091]
+const TW_H = [254.604, 255.585, 254.128, 251.813, 254.624, 259.815, 262.881, 264.376, 265.638, 265.522, 267.935]
+
+// Radix-like light scale: step 9 is the pure solid, 11 and 12 are text.
+const RADIX_L = [0.992, 0.978, 0.953, 0.925, 0.894, 0.857, 0.81, 0.745, 0.62, 0.585, 0.52, 0.32]
+const RADIX_C = [0.04, 0.08, 0.2, 0.32, 0.43, 0.52, 0.6, 0.75, 1, 0.95, 0.9, 0.35]
+
+function even(n: number): Curve {
+	const t = (i: number) => i / (n - 1)
+	const bell = (i: number) => Math.sin(Math.PI * (0.05 + 0.9 * t(i)))
+	const anchor = Math.round((n - 1) / 2)
+	return {
+		lightness: Array.from({ length: n }, (_, i) => 0.97 - 0.72 * t(i)),
+		chroma: Array.from({ length: n }, (_, i) => bell(i) / bell(anchor)),
+		hueShift: Array.from({ length: n }, () => 0),
+		anchor
+	}
+}
+
+const PRESETS: Record<string, Curve> = {
+	__proto__: null as never,
+	'tailwind-11': {
+		lightness: TW_L,
+		chroma: TW_C.map((c) => c / TW_C[5]),
+		hueShift: TW_H.map((h) => h - TW_H[5]),
+		anchor: 5
+	},
+	'radix-12': {
+		lightness: RADIX_L,
+		chroma: RADIX_C,
+		hueShift: RADIX_L.map(() => 0),
+		anchor: 8
+	},
+	'tone-13': {
+		lightness: [...MATERIAL_TONES].reverse(),
+		chroma: MATERIAL_TONES.map(() => 1),
+		hueShift: MATERIAL_TONES.map(() => 0),
+		anchor: 6,
+		tone: true
+	}
+}
+
+/** Options for `createScale`. Only `seed` is required. */
+export interface ScaleOptions {
+	/** The color the scale is built around. Its hue and chroma set the anchor step. */
+	seed: Color | string
+	/**
+	 * A preset, or a number of steps for an even scale. Default `tailwind-11`.
+	 * `tone-13` steps are CIE L* tones, so any two steps whose tones differ by
+	 * 40 reach contrast 3 and by 50 about 4.5.
+	 */
+	steps?: ScalePreset | number
+	/** Overrides the curve's lightness, one per step: OKLCH L 0 to 1 (L* tones 0 to 100 for `tone-13`). */
+	lightness?: number[]
+	/** Overrides chroma, as a multiplier of the seed's chroma, one per step. */
+	chroma?: number[]
+	/** Overrides hue drift, as degrees added to the seed's hue, one per step; a number is applied to every step. */
+	hueShift?: number[] | number
+	/** The gamut every step must fit. Default `srgb`. */
+	gamut?: GamutId
+}
+
+function curveOf(steps: ScalePreset | number): Curve {
+	if (typeof steps === 'number') {
+		if (!Number.isInteger(steps) || steps < 2) throw new Error(`steps must be an integer of at least 2, got ${steps}`)
+		return even(steps)
+	}
+	if (steps === 'even') return even(11)
+	const curve = PRESETS[steps]
+	if (!curve) throw unknownName('scale preset', steps, [...Object.keys(PRESETS), 'even'])
+	return curve
+}
+
+/**
+ * Builds a scale from light to dark around `seed`: one color per step, in
+ * OKLCH, mapped into `gamut`. The preset gives each step's lightness, chroma
+ * (relative to the seed's) and hue drift; pass `lightness`, `chroma` or
+ * `hueShift` to replace any of them.
+ */
+export function createScale(options: ScaleOptions): Color[] {
+	const { seed, steps = 'tailwind-11', gamut = 'srgb' } = options
+	const curve = curveOf(steps)
+	const n = curve.lightness.length
+	const pick = <T>(name: string, over: T[] | undefined, base: T[]): T[] => {
+		if (over === undefined) return base
+		if (over.length !== n) throw new Error(`${name} needs ${n} values, got ${over.length}`)
+		return over
+	}
+	const lightness = pick('lightness', options.lightness, curve.lightness)
+	const chroma = pick('chroma', options.chroma, curve.chroma)
+	const drift =
+		typeof options.hueShift === 'number' ? curve.lightness.map(() => options.hueShift as number) : options.hueShift
+	const hueShift = pick('hueShift', drift, curve.hueShift)
+
+	const [, seedC, seedH] = componentsIn(toColor(seed), 'oklch') as [number, number, number | null]
+	const hue = seedH ?? 0
+	return lightness.map((l, i) => {
+		const c = seedC * (chroma[i] as number)
+		const h = hue + (hueShift[i] as number)
+		return curve.tone ? toneColor(l, c, h, gamut) : toGamut({ colorSpace: 'oklch', components: [l, c, h] }, { gamut })
+	})
+}

package/src/scale/tone.ts

@@ -0,0 +1,69 @@
+import { type GamutId, inGamut } from '../color/gamut.js'
+import { componentsIn } from '../color/spaces.js'
+import type { Color } from '../color/types.js'
+
+/** CIE L* (0 to 100) of a color: its relative luminance on the CIELAB lightness curve. */
+export function lstar(color: Color): number {
+	const y = Math.max(0, componentsIn(color, 'xyz-d65')[1] as number)
+	return y > 216 / 24389 ? 116 * Math.cbrt(y) - 16 : (24389 / 27) * y
+}
+
+/** Material's tones: 0 is black, 100 is white. */
+export const MATERIAL_TONES: readonly number[] = [0, 10, 20, 30, 40, 50, 60, 70, 80, 90, 95, 99, 100]
+
+/** Options for `tonalPalette`. */
+export interface TonalPaletteOptions {
+	/** The gamut the colors must fit. Default `srgb`. */
+	gamut?: GamutId
+}
+
+/**
+ * The color at CIE L* `tone` with the given OKLCH hue and chroma, mapped into
+ * the gamut. OKLCH lightness is searched until the *mapped* color lands on
+ * `tone`, so chroma tapers where the gamut narrows and the tone stays true.
+ */
+export function toneColor(tone: number, chroma: number, hue: number, gamut: GamutId = 'srgb'): Color {
+	if (tone <= 0) return { colorSpace: 'oklch', components: [0, 0, hue] }
+	if (tone >= 100) return { colorSpace: 'oklch', components: [1, 0, hue] }
+	// The hue is fixed, so its cosine and sine are taken once: OKLCH converts by
+	// way of OKLab with exactly these products, so the results are the same.
+	const r = (hue * Math.PI) / 180
+	const cos = Math.cos(r)
+	const sin = Math.sin(r)
+	const lab = (l: number, c: number): Color => ({ colorSpace: 'oklab', components: [l, c * cos, c * sin] })
+	// The most chroma, up to `chroma`, that fits at this lightness; no clipping, so L* is monotone in L.
+	const chromaAt = (l: number): number => {
+		if (inGamut(lab(l, chroma), gamut)) return chroma
+		let [lo, hi] = [0, chroma]
+		for (let i = 0; i < 24; i++) {
+			const mid = (lo + hi) / 2
+			if (inGamut(lab(l, mid), gamut)) lo = mid
+			else hi = mid
+		}
+		return lo
+	}
+	let lo = 0
+	let hi = 1
+	for (let i = 0; i < 40; i++) {
+		const mid = (lo + hi) / 2
+		if (lstar(lab(mid, chromaAt(mid))) < tone) lo = mid
+		else hi = mid
+	}
+	const l = (lo + hi) / 2
+	return { colorSpace: 'oklch', components: [l, chromaAt(l), hue] }
+}
+
+/**
+ * A tonal palette, as in Material: one OKLCH hue and chroma held across L*
+ * tones. Two colors whose tones differ by 40 or more reach WCAG 2 contrast 3,
+ * and by 50 or more about 4.5 (4.48 at the worst pair, 100 against 50), so a
+ * pair can be picked by tone alone. Default tones are Material's 13.
+ */
+export function tonalPalette(
+	hue: number,
+	chroma: number,
+	tones: readonly number[] = MATERIAL_TONES,
+	options: TonalPaletteOptions = {}
+): Color[] {
+	return tones.map((t) => toneColor(t, chroma, hue, options.gamut))
+}

package/src/tokens/css.ts

@@ -0,0 +1,32 @@
+import { type ToCssOptions, toCss } from '../color/serialize.js'
+import { convert } from '../color/spaces.js'
+import type { ColorSpaceId } from '../color/types.js'
+import { cssNames, flatten, type TokenTree } from './tokens.js'
+
+/** Options for `toCssVariables`. It also takes the options of `toCss`. */
+export interface CssVariablesOptions extends ToCssOptions {
+	/** The first part of every name. Default `color`, so `primary.500` becomes `--color-primary-500`. */
+	prefix?: string
+	/** The rule's selector. Default `:root`. */
+	selector?: string
+	/** Convert every color to this space first. Default: print each in its own space. */
+	space?: ColorSpaceId
+}
+
+/** Prints one `--name: value;` line per color. */
+export function declarations(tree: TokenTree, options: CssVariablesOptions & { prefix: string }): string[] {
+	const { prefix, space, ...css } = options
+	return [...cssNames(flatten(tree), prefix)].map(
+		([name, color]) => `${name}: ${toCss(space ? convert(color, space) : color, css)};`
+	)
+}
+
+/**
+ * Exports colors as CSS custom properties in one rule:
+ * `:root {\n\t--color-primary-500: oklch(0.62 0.19 260);\n}`.
+ */
+export function toCssVariables(tree: TokenTree, options: CssVariablesOptions = {}): string {
+	const { selector = ':root', prefix = 'color', ...rest } = options
+	const lines = declarations(tree, { ...rest, prefix })
+	return `${selector} {\n${lines.map((l) => `\t${l}\n`).join('')}}\n`
+}

package/src/tokens/dtcg.ts

@@ -0,0 +1,62 @@
+import { toGamut } from '../color/gamut.js'
+import { toHex } from '../color/serialize.js'
+import { convert } from '../color/spaces.js'
+import type { Color, ColorSpaceId, Component } from '../color/types.js'
+import { flatten, type TokenTree } from './tokens.js'
+
+/** Options for `toDtcg` and `toDtcgValue`. */
+export interface DtcgOptions {
+	/** Add the `hex` fallback (an sRGB `#rrggbb`, gamut-mapped when the color is outside sRGB). Default `true`. */
+	hex?: boolean
+}
+
+/** A color value as DTCG 2025.10 defines it. */
+export interface DtcgColorValue {
+	colorSpace: Exclude<ColorSpaceId, 'display-p3-linear'>
+	components: (number | 'none')[]
+	alpha?: number | 'none'
+	hex?: string
+}
+
+/** A DTCG color token: a `$type` of `color` and its {@link DtcgColorValue}. */
+export interface DtcgToken {
+	$type: 'color'
+	$value: DtcgColorValue
+}
+
+/** A DTCG group: named tokens and nested groups, as `toDtcg` returns for a token tree. */
+export interface DtcgGroup {
+	[name: string]: DtcgToken | DtcgGroup
+}
+
+const none = (c: Component): number | 'none' => (c === null ? 'none' : c)
+
+/** One color as a DTCG color value. `display-p3-linear` is not a DTCG space, so it becomes `display-p3`. */
+export function toDtcgValue(color: Color, options: DtcgOptions = {}): DtcgColorValue {
+	const c = color.colorSpace === 'display-p3-linear' ? convert(color, 'display-p3') : color
+	const value: DtcgColorValue = {
+		colorSpace: c.colorSpace as DtcgColorValue['colorSpace'],
+		components: c.components.map(none)
+	}
+	if (c.alpha !== undefined && c.alpha !== 1) value.alpha = none(c.alpha)
+	if (options.hex !== false) value.hex = toHex(toGamut({ ...c, alpha: 1 }, { gamut: 'srgb' }))
+	return value
+}
+
+/**
+ * Exports colors as a DTCG 2025.10 token file: nested groups whose leaves are
+ * `{ "$type": "color", "$value": { colorSpace, components, alpha?, hex? } }`.
+ * `none` components print as `"none"`, as the format asks. The result is plain
+ * JSON, so `JSON.stringify` writes the file.
+ */
+export function toDtcg(tree: TokenTree, options: DtcgOptions = {}): DtcgGroup {
+	// Groups have no prototype, so a token named `__proto__` or `constructor` is an ordinary key.
+	const root: DtcgGroup = Object.create(null)
+	for (const { path, color } of flatten(tree)) {
+		if (!path.length) throw new TypeError('A DTCG file needs a name for each token: pass an object, not a single color')
+		let group = root
+		for (const name of path.slice(0, -1)) group = (group[name] ??= Object.create(null)) as DtcgGroup
+		group[path[path.length - 1] as string] = { $type: 'color', $value: toDtcgValue(color, options) }
+	}
+	return root
+}

package/src/tokens/index.ts

@@ -0,0 +1,11 @@
+export { type CssVariablesOptions, toCssVariables } from './css.js'
+export {
+	type DtcgColorValue,
+	type DtcgGroup,
+	type DtcgOptions,
+	type DtcgToken,
+	toDtcg,
+	toDtcgValue
+} from './dtcg.js'
+export { type TailwindThemeOptions, toTailwindTheme } from './tailwind.js'
+export type { TokenTree } from './tokens.js'

package/src/tokens/tailwind.ts

@@ -0,0 +1,24 @@
+import type { ColorSpaceId } from '../color/types.js'
+import { type CssVariablesOptions, declarations } from './css.js'
+import type { TokenTree } from './tokens.js'
+
+/** Options for `toTailwindTheme`. It also takes the options of `toCss`. */
+export interface TailwindThemeOptions extends Omit<CssVariablesOptions, 'selector' | 'prefix'> {
+	/** The theme variable namespace. Default `color`, which makes `bg-primary-500` and `text-primary-500` work. */
+	namespace?: string
+	/** Write `@theme inline`, so utilities hold the value instead of a `var()` reference. */
+	inline?: boolean
+	/** Default `oklch`, the space Tailwind v4's own palette uses. */
+	space?: ColorSpaceId
+}
+
+/**
+ * Exports colors as a Tailwind v4 `@theme` block. Paste it into the CSS file
+ * that has `@import "tailwindcss"`. An array of 11 colors gets the keys
+ * 50 to 950, so a `tailwind-11` scale reads like Tailwind's own.
+ */
+export function toTailwindTheme(tree: TokenTree, options: TailwindThemeOptions = {}): string {
+	const { namespace = 'color', inline = false, space = 'oklch', ...rest } = options
+	const lines = declarations(tree, { ...rest, space, prefix: namespace })
+	return `@theme${inline ? ' inline' : ''} {\n${lines.map((l) => `\t${l}\n`).join('')}}\n`
+}

package/src/tokens/tokens.ts

@@ -0,0 +1,82 @@
+import { parse } from '../color/parse.js'
+import type { Color } from '../color/types.js'
+import type { SemanticPalette } from '../palette/semantic.js'
+
+/**
+ * What the exporters accept: a color, a CSS color string, an array of them (a
+ * scale), or an object of any of these nested to any depth. A `SemanticPalette`
+ * works as is: its `scales` and its role pairs export, its `meta` and ratios do not.
+ */
+export type TokenTree = SemanticPalette | Color | string | readonly TokenTree[] | { readonly [name: string]: TokenTree }
+
+/** A color and the path of names that leads to it. */
+export interface Token {
+	path: string[]
+	color: Color
+}
+
+const TAILWIND_STEPS = [50, 100, 200, 300, 400, 500, 600, 700, 800, 900, 950]
+
+const isColor = (v: unknown): v is Color =>
+	typeof v === 'object' &&
+	v !== null &&
+	typeof (v as Color).colorSpace === 'string' &&
+	Array.isArray((v as Color).components)
+
+// A semantic palette carries numbers (`ratio`, `target`, `meta`) that are not colors.
+function dropMeasures(tree: Record<string, unknown>): Record<string, unknown> {
+	const { meta: _meta, scales, roles, ...rest } = tree
+	const pairs = Object.fromEntries(
+		Object.entries(roles as Record<string, { bg: Color; fg: Color }>).map(([name, p]) => [name, { bg: p.bg, fg: p.fg }])
+	)
+	return { ...rest, ...(scales as object), roles: pairs }
+}
+
+const isSemantic = (v: object): boolean => 'roles' in v && 'scales' in v && 'meta' in v
+
+/**
+ * Walks a token tree into a flat list. An array gets the Tailwind keys
+ * (50 to 950) when it has 11 colors and 1-based numbers otherwise; pass an
+ * object to choose the keys. A value that is not a color, a string, an array
+ * or an object throws with its path.
+ */
+export function flatten(tree: TokenTree): Token[] {
+	const out: Token[] = []
+	const walk = (node: unknown, path: string[]): void => {
+		if (typeof node === 'string') return void out.push({ path, color: parse(node) })
+		if (isColor(node)) return void out.push({ path, color: node })
+		if (Array.isArray(node)) {
+			node.forEach((v, i) => {
+				walk(v, [...path, String(node.length === TAILWIND_STEPS.length ? TAILWIND_STEPS[i] : i + 1)])
+			})
+			return
+		}
+		if (typeof node === 'object' && node !== null) {
+			const obj = isSemantic(node) ? dropMeasures(node as Record<string, unknown>) : (node as Record<string, unknown>)
+			for (const [k, v] of Object.entries(obj)) walk(v, [...path, k])
+			return
+		}
+		throw new TypeError(`${path.join('.') || '(root)'} is not a color, a string, an array or an object`)
+	}
+	walk(tree, [])
+	return out
+}
+
+/** `primaryContainer` and `Primary Container` both become `primary-container`. */
+export const kebab = (name: string): string =>
+	name
+		.replace(/([a-z0-9])([A-Z])/g, '$1-$2')
+		.replace(/[^a-zA-Z0-9]+/g, '-')
+		.replace(/^-+|-+$/g, '')
+		.toLowerCase()
+
+/** Names tokens for CSS: kebab-case segments joined by `-` after `prefix`. Two tokens with one name throw. */
+export function cssNames(tokens: Token[], prefix: string): Map<string, Color> {
+	const out = new Map<string, Color>()
+	for (const { path, color } of tokens) {
+		const name = `--${[prefix, ...path].map(kebab).filter(Boolean).join('-')}`
+		if (out.has(name)) throw new Error(`${name} is produced by more than one token`)
+		out.set(name, color)
+	}
+	return out
+}

package/cjs/createColors.d.ts

@@ -1,2 +0,0 @@
-import type { RGB, RGBA, Alpha } from './interfaces.js';
-export declare function createColors(from: RGB | RGBA, to: RGB | RGBA, shades: number, alpha?: Alpha): RGBA[];

package/cjs/createColors.js

@@ -1,40 +0,0 @@
-"use strict";
-var __spreadArray = (this && this.__spreadArray) || function (to, from, pack) {
-    if (pack || arguments.length === 2) for (var i = 0, l = from.length, ar; i < l; i++) {
-        if (ar || !(i in from)) {
-            if (!ar) ar = Array.prototype.slice.call(from, 0, i);
-            ar[i] = from[i];
-        }
-    }
-    return to.concat(ar || Array.prototype.slice.call(from));
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.createColors = createColors;
-function createColors(from, to, shades, alpha) {
-    if (alpha === void 0) { alpha = [
-        from.length === 4 ? from[3] : to.length === 4 ? to[3] : 1,
-        to.length === 4 ? to[3] : from.length === 4 ? from[3] : 1
-    ]; }
-    var start = __spreadArray([], from, true);
-    var 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]);
-    var inc = 1 / Math.max(shades - 1, 1);
-    var rgba = [];
-    for (var i = 0; i < shades; i++) {
-        var 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;
-}
-//# sourceMappingURL=createColors.js.map

package/cjs/createColors.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"createColors.js","sourceRoot":"","sources":["../ts/createColors.ts"],"names":[],"mappings":";;;;;;;;;;;AAEA,oCAgCC;AAhCD,SAAgB,YAAY,CAC1B,IAAgB,EAChB,EAAc,EACd,MAAc,EACd,KAGC;IAHD,sBAAA,EAAA;QACE,IAAI,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QACzD,EAAE,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;KAC1D;IACD,IAAM,KAAK,qBAAO,IAAI,OAAC,CAAA;IACvB,IAAM,IAAI,GAAG;QACX,EAAE,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC;QACf,EAAE,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC;QACf,EAAE,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC;QACf,KAAK,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC;KACpB,CAAA;IAED,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;QACpB,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAA;IAEtB,IAAM,GAAG,GAAG,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC,CAAC,CAAA;IAEvC,IAAM,IAAI,GAAU,EAAE,CAAA;IACtB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QAChC,IAAM,KAAK,GAAG;YACZ,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC;YACxC,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC;YACxC,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC;YACxC,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC,GAAG,GAAG;SAC7B,CAAA;QACD,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;IAClB,CAAC;IACD,OAAO,IAAI,CAAA;AACb,CAAC"}

package/cjs/createColors.spec.d.ts

@@ -1 +0,0 @@
-export {};