@wordpress/theme 0.1.0

package/src/color-ramps/lib/ramp-configs.ts

@@ -0,0 +1,309 @@
+/**
+ * Internal dependencies
+ */
+import type { RampStepConfig, RampConfig, RampDirection } from './types';
+import type { TaperChromaOptions } from './taper-chroma';
+
+const lightnessConstraintForegroundHighContrast = (
+	direction: RampDirection
+) =>
+	direction === 'lighter'
+		? 0.9551 // lightness of #f0f0f0 (ie $gray-100)
+		: 0.235; // lightness of #1e1e1e (ie $gray-900)
+const lightnessConstraintForegroundMediumContrast = (
+	direction: RampDirection
+) =>
+	direction === 'lighter'
+		? 0.77 // lightness of #b4b4b4
+		: 0.56; // lightness of #747474
+const lightnessConstraintBgFill = ( direction: RampDirection ) =>
+	direction === 'lighter'
+		? 0.67 // lightness of #969696 (7:1 vs black)
+		: 0.45; // lightness of #555555 (7:1 vs white)
+
+const BG_SURFACE_TAPER_CHROMA: TaperChromaOptions = {
+	alpha: 0.7,
+};
+const FG_TAPER_CHROMA: TaperChromaOptions = {
+	alpha: 0.6,
+	kLight: 0.2,
+	kDark: 0.2,
+};
+const STROKE_TAPER_CHROMA: TaperChromaOptions = {
+	alpha: 0.6,
+	radiusDark: 0.01,
+	radiusLight: 0.01,
+	kLight: 0.8,
+	kDark: 0.8,
+};
+const ACCENT_SURFACE_TAPER_CHROMA: TaperChromaOptions = {
+	alpha: 0.75,
+	radiusDark: 0.01,
+	radiusLight: 0.01,
+};
+
+const fgSurface4Config: RampStepConfig = {
+	contrast: {
+		reference: 'surface3',
+		followDirection: 'main',
+		target: 7,
+		preferLighter: true,
+	},
+	lightness: lightnessConstraintForegroundHighContrast,
+	taperChromaOptions: FG_TAPER_CHROMA,
+};
+
+export const BG_RAMP_CONFIG: RampConfig = {
+	// Surface
+	surface1: {
+		contrast: {
+			reference: 'surface2',
+			followDirection: 'opposite',
+			target: 1.02,
+			ignoreWhenAdjustingSeed: true,
+		},
+		taperChromaOptions: BG_SURFACE_TAPER_CHROMA,
+	},
+	surface2: {
+		contrast: {
+			reference: 'seed',
+			followDirection: 'main',
+			target: 1,
+		},
+	},
+	surface3: {
+		contrast: {
+			reference: 'surface2',
+			followDirection: 'main',
+			target: 1.02,
+		},
+		taperChromaOptions: BG_SURFACE_TAPER_CHROMA,
+	},
+	surface4: {
+		contrast: {
+			reference: 'surface2',
+			followDirection: 'main',
+			target: 1.08,
+		},
+		taperChromaOptions: BG_SURFACE_TAPER_CHROMA,
+	},
+	surface5: {
+		contrast: {
+			reference: 'surface2',
+			followDirection: 'main',
+			target: 1.2,
+		},
+		taperChromaOptions: BG_SURFACE_TAPER_CHROMA,
+	},
+	surface6: {
+		contrast: {
+			reference: 'surface2',
+			followDirection: 'main',
+			target: 1.4,
+		},
+		taperChromaOptions: BG_SURFACE_TAPER_CHROMA,
+	},
+	// Bg fill
+	bgFill1: {
+		contrast: {
+			reference: 'surface2',
+			followDirection: 'main',
+			target: 4,
+		},
+		lightness: lightnessConstraintBgFill,
+	},
+	bgFill2: {
+		contrast: {
+			reference: 'bgFill1',
+			followDirection: 'main',
+			target: 1.2,
+		},
+	},
+	bgFillInverted1: {
+		contrast: {
+			reference: 'bgFillInverted2',
+			followDirection: 'opposite',
+			target: 1.2,
+		},
+	},
+	bgFillInverted2: fgSurface4Config,
+	bgFillDark: {
+		contrast: {
+			reference: 'surface3',
+			followDirection: 'darker', // This is what causes the token to be always dark
+			target: 7,
+			ignoreWhenAdjustingSeed: true,
+		},
+		lightness: lightnessConstraintForegroundHighContrast,
+		taperChromaOptions: FG_TAPER_CHROMA,
+	},
+	// Stroke
+	stroke1: {
+		contrast: {
+			reference: 'stroke3',
+			followDirection: 'opposite',
+			target: 2.2,
+		},
+		taperChromaOptions: STROKE_TAPER_CHROMA,
+	},
+	stroke2: {
+		contrast: {
+			reference: 'stroke3',
+			followDirection: 'opposite',
+			target: 1.5,
+		},
+		taperChromaOptions: STROKE_TAPER_CHROMA,
+	},
+	stroke3: {
+		contrast: {
+			reference: 'surface3',
+			followDirection: 'main',
+			target: 3,
+		},
+		taperChromaOptions: STROKE_TAPER_CHROMA,
+	},
+	stroke4: {
+		contrast: {
+			reference: 'stroke3',
+			followDirection: 'main',
+			target: 1.5,
+		},
+		taperChromaOptions: STROKE_TAPER_CHROMA,
+	},
+	// fgSurface
+	fgSurface1: {
+		contrast: {
+			reference: 'surface3',
+			followDirection: 'main',
+			target: 2,
+			preferLighter: true,
+		},
+		taperChromaOptions: FG_TAPER_CHROMA,
+	},
+	fgSurface2: {
+		contrast: {
+			reference: 'surface3',
+			followDirection: 'main',
+			target: 3,
+			preferLighter: true,
+		},
+		taperChromaOptions: FG_TAPER_CHROMA,
+	},
+	fgSurface3: {
+		contrast: {
+			reference: 'surface3',
+			followDirection: 'main',
+			target: 4.5,
+			preferLighter: true,
+		},
+		lightness: lightnessConstraintForegroundMediumContrast,
+		taperChromaOptions: FG_TAPER_CHROMA,
+	},
+	fgSurface4: fgSurface4Config,
+	// fgFill
+	fgFill: {
+		contrast: {
+			reference: 'bgFill1',
+			followDirection: 'best',
+			target: 4.5,
+			preferLighter: true,
+		},
+		lightness: lightnessConstraintForegroundHighContrast,
+		taperChromaOptions: FG_TAPER_CHROMA,
+	},
+	fgFillInverted: {
+		contrast: {
+			reference: 'bgFillInverted1',
+			followDirection: 'best',
+			target: 4.5,
+			preferLighter: true,
+		},
+		lightness: lightnessConstraintForegroundHighContrast,
+		taperChromaOptions: FG_TAPER_CHROMA,
+	},
+	fgFillDark: {
+		contrast: {
+			reference: 'bgFillDark',
+			followDirection: 'best',
+			target: 4.5,
+			preferLighter: true,
+		},
+		lightness: lightnessConstraintForegroundHighContrast,
+		taperChromaOptions: FG_TAPER_CHROMA,
+	},
+};
+
+// BG_RAMP: seed => surface2 => {bgFill, surface3 => all other tokens}
+// ACCENT_RAMP: seed => bgFill1 => surface2 => surface3 => all other tokens
+export const ACCENT_RAMP_CONFIG: RampConfig = {
+	...BG_RAMP_CONFIG,
+	surface1: {
+		...BG_RAMP_CONFIG.surface1,
+		taperChromaOptions: ACCENT_SURFACE_TAPER_CHROMA,
+	},
+	surface2: {
+		contrast: {
+			reference: 'bgFill1',
+			followDirection: 'opposite',
+			target: BG_RAMP_CONFIG.bgFill1.contrast.target,
+			ignoreWhenAdjustingSeed: true,
+		},
+		taperChromaOptions: ACCENT_SURFACE_TAPER_CHROMA,
+	},
+	surface3: {
+		...BG_RAMP_CONFIG.surface3,
+		taperChromaOptions: ACCENT_SURFACE_TAPER_CHROMA,
+	},
+	surface4: {
+		...BG_RAMP_CONFIG.surface4,
+		taperChromaOptions: ACCENT_SURFACE_TAPER_CHROMA,
+	},
+	surface5: {
+		...BG_RAMP_CONFIG.surface5,
+		taperChromaOptions: ACCENT_SURFACE_TAPER_CHROMA,
+	},
+	surface6: {
+		...BG_RAMP_CONFIG.surface6,
+		taperChromaOptions: ACCENT_SURFACE_TAPER_CHROMA,
+	},
+	bgFill1: {
+		contrast: {
+			reference: 'seed',
+			followDirection: 'main',
+			target: 1,
+		},
+	},
+	stroke1: {
+		...BG_RAMP_CONFIG.stroke1,
+	},
+	stroke2: {
+		...BG_RAMP_CONFIG.stroke2,
+	},
+	stroke3: {
+		...BG_RAMP_CONFIG.stroke3,
+		sameAsIfPossible: 'fgSurface3',
+		taperChromaOptions: undefined,
+	},
+	stroke4: {
+		...BG_RAMP_CONFIG.stroke4,
+		taperChromaOptions: undefined,
+	},
+	// fgSurface: do not de-saturate
+	fgSurface1: {
+		...BG_RAMP_CONFIG.fgSurface1,
+		taperChromaOptions: undefined,
+	},
+	fgSurface2: {
+		...BG_RAMP_CONFIG.fgSurface2,
+		taperChromaOptions: undefined,
+	},
+	fgSurface3: {
+		...BG_RAMP_CONFIG.fgSurface3,
+		taperChromaOptions: undefined,
+		sameAsIfPossible: 'bgFill1',
+	},
+	fgSurface4: {
+		...BG_RAMP_CONFIG.fgSurface4,
+		taperChromaOptions: undefined,
+	},
+};

package/src/color-ramps/lib/taper-chroma.ts

@@ -0,0 +1,226 @@
+// npm i colorjs.io
+/**
+ * External dependencies
+ */
+import Color from 'colorjs.io';
+
+export interface TaperChromaOptions {
+	gamut?: 'p3' | 'srgb'; // target gamut (default "p3")
+	alpha?: number; // base fraction of Cmax at target (default 0.62)
+	carry?: number; // seed vividness carry exponent β in [0..1] (default 0.5)
+	cUpperBound?: number; // hard search cap for C (default 0.45)
+	// Continuous taper around the seed (desaturate both sides slightly)
+	radiusLight?: number; // distance in L where kLight is reached (default 0.20)
+	radiusDark?: number; // distance in L where kDark is reached (default 0.20)
+	kLight?: number; // floor multiplier near lighter side (default 0.85)
+	kDark?: number; // floor multiplier near darker side (default 0.85)
+	// Achromatic handling
+	hueFallback?: number; // degrees: if seed is achromatic and you still want color
+	achromaEpsilon?: number; // ≤ this chroma → treat as achromatic (default 0.005)
+}
+
+/**
+ * Given the seed and the target lightness, tapers the chroma smoothly.
+ * - C_intended = Cmax(Lt,H0) * alpha * (seedRelative^carry)
+ * - Continuous taper vs |Lt - Ls| to softly reduce chroma for neighbors
+ * - Downward-only clamp on C (preserve L & H)
+ * @param seed
+ * @param lTarget
+ * @param options
+ */
+export function taperChroma(
+	seed: Color, // already OKLCH
+	lTarget: number, // [0..1]
+	options: TaperChromaOptions = {}
+): { l: number; c: number } {
+	const gamut = options.gamut ?? 'p3';
+	const alpha = options.alpha ?? 0.65; // 0.7-0.8 works well for accent surface
+	const carry = options.carry ?? 0.5;
+	const cUpperBound = options.cUpperBound ?? 0.45;
+	const radiusLight = options.radiusLight ?? 0.2;
+	const radiusDark = options.radiusDark ?? 0.2;
+	const kLight = options.kLight ?? 0.85;
+	const kDark = options.kDark ?? 0.85;
+	const achromaEpsilon = options.achromaEpsilon ?? 0.005;
+
+	const cSeed = Math.max( 0, seed.oklch.c );
+	let hSeed = Number( seed.oklch.h );
+
+	const chromaIsTiny = cSeed < achromaEpsilon;
+	const hueIsInvalid = ! Number.isFinite( hSeed );
+
+	if ( chromaIsTiny || hueIsInvalid ) {
+		if ( typeof options.hueFallback === 'number' ) {
+			hSeed = normalizeHue( options.hueFallback );
+		} else {
+			// Respect achromatic intent: grayscale at target L
+			return new Color( 'oklch', [ clamp01( lTarget ), 0, 0 ] );
+		}
+	}
+
+	// Capacity at seed and target
+	const lSeed = clamp01( seed.oklch.l );
+	const cmaxSeed = getCachedMaxChromaAtLH( lSeed, hSeed, gamut, cUpperBound );
+	const cmaxTarget = getCachedMaxChromaAtLH(
+		clamp01( lTarget ),
+		hSeed,
+		gamut,
+		cUpperBound
+	);
+
+	// Seed vividness ratio (hue-fair normalization)
+	let seedRelative = 0;
+	const denom = cmaxSeed > 0 ? cmaxSeed : 1e-6;
+	seedRelative = clamp01( cSeed / denom );
+
+	// Intended chroma from local capacity, tempered by seed vividness
+	const cIntendedBase = alpha * cmaxTarget;
+	const cWithCarry =
+		cIntendedBase * Math.pow( seedRelative, clamp01( carry ) );
+
+	// Gentle, symmetric desaturation vs distance in L
+	const t = continuousTaper( lSeed, lTarget, {
+		radiusLight,
+		radiusDark,
+		kLight,
+		kDark,
+	} );
+	let cPlanned = cWithCarry * t;
+
+	// Downward-only clamp (preserve L & H)
+	const lOut = clamp01( lTarget );
+	const candidate = new Color( 'oklch', [ lOut, cPlanned, hSeed ] );
+	if ( ! candidate.inGamut( gamut ) ) {
+		const cap = Math.min( cPlanned, cUpperBound );
+		cPlanned = getCachedMaxChromaAtLH( lOut, hSeed, gamut, cap );
+	}
+
+	cPlanned = Math.min( cPlanned, cSeed );
+
+	return { l: lOut, c: cPlanned };
+}
+
+/* ---------------- helpers & caches ---------------- */
+
+function clamp01( x: number ): number {
+	if ( x < 0 ) {
+		return 0;
+	}
+	if ( x > 1 ) {
+		return 1;
+	}
+	return x;
+}
+function normalizeHue( h: number ): number {
+	let hue = h % 360;
+	if ( hue < 0 ) {
+		hue += 360;
+	}
+	return hue;
+}
+function raisedCosine( u: number ): number {
+	const x = clamp01( u );
+	return 0.5 - 0.5 * Math.cos( Math.PI * x );
+}
+
+/**
+ * smooth, distance-from-seed chroma taper (raised-cosine per side)
+ * @param seedL
+ * @param targetL
+ * @param opts
+ * @param opts.radiusLight
+ * @param opts.radiusDark
+ * @param opts.kLight
+ * @param opts.kDark
+ */
+function continuousTaper(
+	seedL: number,
+	targetL: number,
+	opts: {
+		radiusLight: number;
+		radiusDark: number;
+		kLight: number;
+		kDark: number;
+	}
+): number {
+	const d = targetL - seedL;
+	if ( d >= 0 ) {
+		const u = opts.radiusLight > 0 ? Math.abs( d ) / opts.radiusLight : 1;
+		const w = raisedCosine( u > 1 ? 1 : u );
+		return 1 - ( 1 - opts.kLight ) * w;
+	}
+	const u = opts.radiusDark > 0 ? Math.abs( d ) / opts.radiusDark : 1;
+	const w = raisedCosine( u > 1 ? 1 : u );
+	return 1 - ( 1 - opts.kDark ) * w;
+}
+
+/* ---- chroma-capacity queries with small caches ---- */
+
+const maxChromaCache = new Map< string, number >();
+
+function keyMax(
+	l: number,
+	h: number,
+	gamut: 'p3' | 'srgb',
+	cap: number
+): string {
+	// Quantize to keep cache compact
+	const lq = quantize( l, 1e-3 );
+	const hq = quantize( normalizeHue( h ), 1e-1 );
+	const cq = quantize( cap, 1e-3 );
+	return `${ gamut }|L:${ lq }|H:${ hq }|cap:${ cq }`;
+}
+function quantize( x: number, step: number ): number {
+	const k = Math.round( x / step );
+	return k * step;
+}
+
+function getCachedMaxChromaAtLH(
+	l: number,
+	h: number,
+	gamut: 'p3' | 'srgb',
+	cap: number
+): number {
+	const key = keyMax( l, h, gamut, cap );
+	const hit = maxChromaCache.get( key );
+	if ( typeof hit === 'number' ) {
+		return hit;
+	}
+
+	const computed = maxInGamutChromaAtLH( l, h, gamut, cap );
+	maxChromaCache.set( key, computed );
+	return computed;
+}
+
+/**
+ * Binary-search the max in-gamut chroma at fixed (L,H) in the target gamut
+ * @param l
+ * @param h
+ * @param gamut
+ * @param cap
+ */
+function maxInGamutChromaAtLH(
+	l: number,
+	h: number,
+	gamut: 'p3' | 'srgb',
+	cap: number
+): number {
+	let lo = 0;
+	let hi = cap;
+	let ok = 0;
+
+	const lFixed = clamp01( l );
+	const hFixed = normalizeHue( h );
+
+	for ( let i = 0; i < 18; i++ ) {
+		const mid = ( lo + hi ) / 2;
+		const probe = new Color( 'oklch', [ lFixed, mid, hFixed ] );
+		if ( probe.inGamut( gamut ) ) {
+			ok = mid;
+			lo = mid;
+		} else {
+			hi = mid;
+		}
+	}
+	return ok;
+}

package/src/color-ramps/lib/types.ts

@@ -0,0 +1,90 @@
+/**
+ * Internal dependencies
+ */
+import type { TaperChromaOptions } from './taper-chroma';
+
+export type Ramp = {
+	// Backgrounds for surfaces (nuanced, slight variations compared to bg)
+	surface1: string;
+	surface2: string;
+	surface3: string;
+	surface4: string;
+	surface5: string;
+	surface6: string;
+	// Strokes
+	stroke1: string;
+	stroke2: string;
+	stroke3: string;
+	stroke4: string;
+	// Stronger backgrounds for primary UI elements
+	bgFill1: string;
+	bgFill2: string;
+	bgFillInverted1: string;
+	bgFillInverted2: string;
+	bgFillDark: string;
+	// Foreground (text, icon) colors
+	fgSurface1: string;
+	fgSurface2: string;
+	fgSurface3: string;
+	fgSurface4: string;
+	// Foreground (text, icon) colors on top of bgFill
+	fgFill: string;
+	fgFillInverted: string;
+	fgFillDark: string;
+};
+
+export type RampDirection = 'lighter' | 'darker';
+export type FollowDirection = 'main' | 'opposite' | 'best' | RampDirection;
+export type ContrastRequirement = {
+	/** The reference color against which to calculate the contrast */
+	reference: keyof Ramp | 'seed';
+	/**
+	 * Which direction should the algorithm search a matching color in:
+	 * - main: follow the same direction as the ramp's main direction
+	 * - opposite: follow the opposite direction of the ramp
+	 * - best: pick the direction that has the most contrast headroom
+	 * - hardcoded ramp direction (useful for generating colors that always
+	 *   light/dark regardless of the ramp direction)
+	 */
+	followDirection: FollowDirection;
+	/**
+	 *  Prefer "lighter" direction when searching for a contrasting color.
+	 * Especially useful for foreground color to counter the poor results that the
+	 * WCAG algo gives when contrasting white text over mid-lightness backgrounds.
+	 */
+	preferLighter?: boolean;
+	/**
+	 * The contrast target to meet.
+	 */
+	target: number;
+	/**
+	 * When true, the algorithm won't count a failure in meeting the contrast
+	 * target as a reason to recalculate the ramp.
+	 */
+	ignoreWhenAdjustingSeed?: boolean;
+};
+
+export type RampStepConfig = {
+	contrast: ContrastRequirement;
+	lightness?: ( direction: RampDirection ) => number;
+	taperChromaOptions?: TaperChromaOptions;
+	/**
+	 * If specified, try to reuse the color from this step if it meets
+	 * the contrast requirements. This reduces the number of unique colors
+	 * in the ramp and improves consistency.
+	 */
+	sameAsIfPossible?: keyof Ramp;
+};
+
+export type RampConfig = Record< keyof Ramp, RampStepConfig >;
+
+export type RampResult = {
+	ramp: Record<
+		keyof Ramp,
+		{
+			color: string;
+			warning: boolean;
+		}
+	>;
+	direction: RampDirection;
+};