@rokkit/core 1.1.16 → 1.1.18

package/dist/color-space.d.ts

@@ -1,3 +1,14 @@
+/**
+ * Relative luminance (Y, 0–1) of a palette value in the given color space.
+ * Accepts hex (`#rrggbb`), bare RGB (`"r,g,b"` / `"r g b"`), and bare OKLCH
+ * (`"L C H"`). Returns null when the value can't be parsed — callers should
+ * treat null as "unknown" and fall back to a safe default.
+ *
+ * @param {string} value
+ * @param {string} [space] — 'rgb' | 'oklch' | 'hsl'; disambiguates bare channels
+ * @returns {number | null}
+ */
+export function relativeLuminance(value: string, space?: string): number | null;
 /**
  * Abstract base class for color space adapters.
  */

package/dist/named-tokens.d.ts

@@ -9,8 +9,8 @@ export type ZSlot = 'z0' | 'z1' | 'z2' | 'z3' | 'z4' | 'z5' | 'z6' | 'z7' | 'z8'
 export declare const Z_SLOTS: ZSlot[];
 /**
  * Maps each named token to the palette shade index that backs it.
- * 'derived' indicates the token is computed from another palette (e.g., on-primary
- * picks the paper shade of the surface palette by default for white-on-primary).
+ * 'derived' indicates the token is computed (e.g., on-primary is the auto
+ * on-color — near-black or near-white — picked by the primary fill's luminance).
  *
  *   paper:        50  (lightest surface tone, canvas)
  *   paper-soft:   100 (card background)
@@ -21,7 +21,7 @@ export declare const Z_SLOTS: ZSlot[];
  *   ink-soft:     500 (placeholder)
  *   ink-faint:    300 (disabled)
  *   primary:      500 (CTA fill)
- *   on-primary:   derived — surface.50 default (white-on-primary)
+ *   on-primary:   derived — auto on-color (near-black/white) for primary fill
  *   accent / status: 500 (solid)
  *   *-soft:       100 (tinted-bg companion)
  *   focus-ring:   500 of accent

package/dist/theme.d.ts

@@ -38,13 +38,20 @@ export declare function semanticShortcuts(name: any): (string[] | (RegExp | (([,
 /**
  * Generates "on-color" text shortcuts for readable text on colored backgrounds.
  *
- * - `text-on-{name}` → high contrast text for use on z5+ backgrounds (always light text)
- * - `text-on-{name}-muted` → slightly muted but still readable on z5+ backgrounds
+ * The on-color is whichever of near-black / near-white best contrasts with the
+ * role's z5 fill (the principle: a 500-shade fill takes black OR white text —
+ * never a mid tint, which fails AA on bright fills like vermillion). The caller
+ * passes the resolved on-color hex (see `Theme.#onColorHex`); we emit it as an
+ * arbitrary-value utility so it stays a single CSS color, opacity-composable.
  *
- * @param {string} name - Color name (e.g., 'primary', 'surface')
+ * - `text-on-{name}` → readable text on a z5+ fill
+ * - `text-on-{name}-muted` → same on-color (kept for back-compat callers)
+ *
+ * @param {string} name - Color name (e.g., 'primary', 'accent', 'danger')
+ * @param {string} [onColor='#fafafa'] - resolved on-color hex for this role
  * @returns {Array} Array of shortcut definitions
  */
-export declare function contrastShortcuts(name: any): (RegExp | (([, end]: [any, any]) => string))[][];
+export declare function contrastShortcuts(name: any, onColor?: string): (RegExp | (([, end]: [any, any]) => string))[][];
 /**
  * Theme class for managing color palettes, mappings, and semantic shortcuts.
  */
@@ -120,8 +127,8 @@ export declare class Theme {
      * Used in extended mode where the preset emits the full --color-{role}-{shade}
      * palette; named tokens become thin syntactic aliases over the palette.
      *
-     * `on-primary` aliases to `var(--color-surface-50)` (derived: paper of surface,
-     * matching the core-mode resolution).
+     * `on-primary` resolves to the auto on-color for the primary fill (near-black
+     * or near-white), matching the core-mode derivation.
      */
     getZAliasesForExtended(): Record<string, string>;
     /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rokkit/core",
-  "version": "1.1.16",
+  "version": "1.1.18",
   "description": "Contains core utility functions and classes that can be used in various components.",
   "repository": {
     "type": "git",
@@ -46,6 +46,6 @@
     "ramda": "^0.32.0"
   },
   "devDependencies": {
-    "@rokkit/icons": "1.1.16"
+    "@rokkit/icons": "1.1.18"
   }
 }

package/src/color-space.js

@@ -42,6 +42,73 @@ function matMul(m, v) {
 	return m.map((row) => row[0] * v[0] + row[1] * v[1] + row[2] * v[2])
 }
 
+// Inverse OKLab matrices (for OKLCH → XYZ, to recover relative luminance Y).
+const OKLAB_TO_LMS3 = [
+	[1, 0.3963377774, 0.2158037573],
+	[1, -0.1055613458, -0.0638541728],
+	[1, -0.0894841775, -1.291485548]
+]
+const LMS_TO_XYZ = [
+	[1.2270138511, -0.5577999807, 0.281256149],
+	[-0.0405801784, 1.1122568696, -0.0716766787],
+	[-0.0763812845, -0.4214819784, 1.5861632204]
+]
+
+/**
+ * Relative luminance (Y, 0–1 per WCAG) of an sRGB triplet.
+ * @param {number} r @param {number} g @param {number} b — 0–255
+ * @returns {number}
+ */
+function rgbLuminance(r, g, b) {
+	const lin = [srgbToLinear(r), srgbToLinear(g), srgbToLinear(b)]
+	return 0.2126 * lin[0] + 0.7152 * lin[1] + 0.0722 * lin[2]
+}
+
+/**
+ * Relative luminance (Y) of an OKLCH color. Y is the XYZ Y component, so we
+ * only need OKLab → LMS → XYZ — no full sRGB round-trip.
+ * @param {number} L @param {number} C @param {number} H — H in degrees
+ * @returns {number}
+ */
+function oklchLuminance(L, C, H) {
+	const hr = (H * Math.PI) / 180
+	const lab = [L, C * Math.cos(hr), C * Math.sin(hr)]
+	const lms = matMul(OKLAB_TO_LMS3, lab).map((v) => v ** 3)
+	return matMul(LMS_TO_XYZ, lms)[1]
+}
+
+/**
+ * Relative luminance (Y, 0–1) of a palette value in the given color space.
+ * Accepts hex (`#rrggbb`), bare RGB (`"r,g,b"` / `"r g b"`), and bare OKLCH
+ * (`"L C H"`). Returns null when the value can't be parsed — callers should
+ * treat null as "unknown" and fall back to a safe default.
+ *
+ * @param {string} value
+ * @param {string} [space] — 'rgb' | 'oklch' | 'hsl'; disambiguates bare channels
+ * @returns {number | null}
+ */
+export function relativeLuminance(value, space = 'rgb') {
+	if (typeof value !== 'string') return null
+	const v = value.trim()
+	if (HEX_RE.test(v)) {
+		const [r, g, b] = parseHex(v)
+		return rgbLuminance(r, g, b)
+	}
+	if (space === 'oklch' && /^[\d.]+\s+[\d.]+\s+[\d.]+$/.test(v)) {
+		const [L, C, H] = v.split(/\s+/).map(Number)
+		return oklchLuminance(L, C, H)
+	}
+	if (/^\d+\s*,\s*\d+\s*,\s*\d+$/.test(v)) {
+		const [r, g, b] = v.split(',').map((s) => Number(s.trim()))
+		return rgbLuminance(r, g, b)
+	}
+	if (/^\d+\s+\d+\s+\d+$/.test(v)) {
+		const [r, g, b] = v.trim().split(/\s+/).map(Number)
+		return rgbLuminance(r, g, b)
+	}
+	return null
+}
+
 // ── Hex parsing helper ──────────────────────────────────────────────────
 
 /**

package/src/named-tokens.ts

@@ -27,8 +27,8 @@ export const Z_SLOTS: ZSlot[] = ['z0', 'z1', 'z2', 'z3', 'z4', 'z5', 'z6', 'z7',
 
 /**
  * Maps each named token to the palette shade index that backs it.
- * 'derived' indicates the token is computed from another palette (e.g., on-primary
- * picks the paper shade of the surface palette by default for white-on-primary).
+ * 'derived' indicates the token is computed (e.g., on-primary is the auto
+ * on-color — near-black or near-white — picked by the primary fill's luminance).
  *
  *   paper:        50  (lightest surface tone, canvas)
  *   paper-soft:   100 (card background)
@@ -39,7 +39,7 @@ export const Z_SLOTS: ZSlot[] = ['z0', 'z1', 'z2', 'z3', 'z4', 'z5', 'z6', 'z7',
  *   ink-soft:     500 (placeholder)
  *   ink-faint:    300 (disabled)
  *   primary:      500 (CTA fill)
- *   on-primary:   derived — surface.50 default (white-on-primary)
+ *   on-primary:   derived — auto on-color (near-black/white) for primary fill
  *   accent / status: 500 (solid)
  *   *-soft:       100 (tinted-bg companion)
  *   focus-ring:   500 of accent

package/src/theme.ts

@@ -2,7 +2,7 @@
 // @ts-nocheck
 import { DEFAULT_THEME_MAPPING, defaultColors, TONE_MAP, INVERTED_ROLES } from './constants'
 import { shades } from './colors/index'
-import { ColorSpace } from './color-space'
+import { ColorSpace, relativeLuminance } from './color-space'
 import {
   NAMED_TOKENS,
   NAMED_TOKEN_SHADE_MAP,
@@ -133,25 +133,42 @@ export function semanticShortcuts(name) {
 /**
  * Generates "on-color" text shortcuts for readable text on colored backgrounds.
  *
- * - `text-on-{name}` → high contrast text for use on z5+ backgrounds (always light text)
- * - `text-on-{name}-muted` → slightly muted but still readable on z5+ backgrounds
+ * The on-color is whichever of near-black / near-white best contrasts with the
+ * role's z5 fill (the principle: a 500-shade fill takes black OR white text —
+ * never a mid tint, which fails AA on bright fills like vermillion). The caller
+ * passes the resolved on-color hex (see `Theme.#onColorHex`); we emit it as an
+ * arbitrary-value utility so it stays a single CSS color, opacity-composable.
  *
- * @param {string} name - Color name (e.g., 'primary', 'surface')
+ * - `text-on-{name}` → readable text on a z5+ fill
+ * - `text-on-{name}-muted` → same on-color (kept for back-compat callers)
+ *
+ * @param {string} name - Color name (e.g., 'primary', 'accent', 'danger')
+ * @param {string} [onColor='#fafafa'] - resolved on-color hex for this role
  * @returns {Array} Array of shortcut definitions
  */
-export function contrastShortcuts(name) {
+export function contrastShortcuts(name, onColor = '#fafafa') {
 	return [
-		[
-			new RegExp(`^text-on-${name}(\\/\\d+)?$`),
-			([, end]) => `text-${name}-50${end || ''} dark:text-${name}-50${end || ''}`
-		],
-		[
-			new RegExp(`^text-on-${name}-muted(\\/\\d+)?$`),
-			([, end]) => `text-${name}-100${end || ''} dark:text-${name}-200${end || ''}`
-		]
+		[new RegExp(`^text-on-${name}(\\/\\d+)?$`), ([, end]) => `text-[${onColor}]${end || ''}`],
+		[new RegExp(`^text-on-${name}-muted(\\/\\d+)?$`), ([, end]) => `text-[${onColor}]${end || ''}`]
 	]
 }
 
+/**
+ * Near-black / near-white on-color endpoints. Not pure #000/#fff — a hair of
+ * lift reads softer on a saturated fill while still clearing AA (near-black is
+ * dark enough that even a mid-bright vermillion 500 reaches ~5:1).
+ */
+const ON_COLOR_DARK = '#161616'
+const ON_COLOR_LIGHT = '#fafafa'
+/**
+ * Fill luminance where ON_COLOR_DARK and ON_COLOR_LIGHT give equal WCAG contrast:
+ * solve (Yf+0.05)² = (Y_dark+0.05)(Y_light+0.05) with Y_dark≈0.0074, Y_light≈0.956
+ * → Yf ≈ 0.190. Fills at/above this take dark text; below take light text. (Truly
+ * mid-luminance fills near this point clear neither pair at AA — that's the
+ * palette author's choice to make, per "pick a 500 where black or white works".)
+ */
+const ON_COLOR_Y_CROSSOVER = 0.19
+
 /**
  * Fallback chain for nullable color mappings.
  * If a semantic color is null, it inherits from another semantic color.
@@ -306,23 +323,32 @@ export class Theme {
 	}
 
 	/**
-	 * Resolves a 'derived' named token. Today only `on-primary` is derived — it picks
-	 * shade 50 from the surface palette for the default white-on-primary contrast pair.
+	 * Resolves a 'derived' named token. Today only `on-primary` is derived — it's
+	 * the auto on-color (near-black or near-white) for the primary fill, so the
+	 * default pair always clears AA whether primary-500 is bright (→ black) or
+	 * dark (→ white). Skins still override `on-primary` for a bespoke pair.
 	 */
-	#resolveDerivedToken(name: string, colors: Record<string, Record<string, string>>, perRoleModes?: Record<string, 'core' | 'extended'>): string | undefined {
+	#resolveDerivedToken(name: string, colors: Record<string, Record<string, string>>, _perRoleModes?: Record<string, 'core' | 'extended'>): string | undefined {
 		if (name === 'on-primary') {
-			const surfacePaletteName = this.#mapping['surface']
-			const surfacePalette = colors[surfacePaletteName]
-			if (!surfacePalette?.['50']) return undefined
-			const surfaceMode = perRoleModes?.['surface'] ?? 'core'
-			if (surfaceMode === 'extended') {
-				return `var(--color-surface-50)`
-			}
-			return this.#adapter.wrap(surfacePalette['50'])
+			return this.#adapter.wrap(this.#onColorHex('primary', colors))
 		}
 		return undefined
 	}
 
+	/**
+	 * Picks the readable on-color (near-black / near-white hex) for a role's z5
+	 * fill by its relative luminance. Bright fills (vermillion, teal, amber) take
+	 * dark text; dark fills (violet, indigo) take light text. Falls back to light
+	 * when the fill can't be measured (matches the historical default).
+	 */
+	#onColorHex(role: string, colors: Record<string, Record<string, string>>): string {
+		const palette = colors[this.#mapping[role]]
+		const fill = palette?.['500']
+		const y = fill !== undefined ? relativeLuminance(fill, this.#adapter.name) : null
+		if (y === null) return ON_COLOR_LIGHT
+		return y >= ON_COLOR_Y_CROSSOVER ? ON_COLOR_DARK : ON_COLOR_LIGHT
+	}
+
 	/**
 	 * Generate z-aliases for surface or ink role using the provided map.
 	 */
@@ -387,17 +413,18 @@ export class Theme {
 	 * Used in extended mode where the preset emits the full --color-{role}-{shade}
 	 * palette; named tokens become thin syntactic aliases over the palette.
 	 *
-	 * `on-primary` aliases to `var(--color-surface-50)` (derived: paper of surface,
-	 * matching the core-mode resolution).
+	 * `on-primary` resolves to the auto on-color for the primary fill (near-black
+	 * or near-white), matching the core-mode derivation.
 	 */
 	getZAliasesForExtended(): Record<string, string> {
+		const colors = { ...defaultColors, ...this.#colors }
 		const result: Record<string, string> = {}
 		for (const name of NAMED_TOKENS) {
 			const role = NAMED_TOKEN_ROLE_MAP[name]
 			const shadeOrDerived = NAMED_TOKEN_SHADE_MAP[name]
 			if (shadeOrDerived === 'derived') {
-				// on-primary → surface.50
-				result[`--${name}`] = `var(--color-surface-50)`
+				// on-primary → auto on-color (black/white) for the primary fill
+				result[`--${name}`] = this.#adapter.wrap(this.#onColorHex('primary', colors))
 				continue
 			}
 			result[`--${name}`] = `var(--color-${role}-${shadeOrDerived})`
@@ -438,7 +465,8 @@ export class Theme {
 	}
 
 	getShortcuts(name) {
-		return [...semanticShortcuts(name), ...contrastShortcuts(name)]
+		const colors = { ...defaultColors, ...this.#colors }
+		return [...semanticShortcuts(name), ...contrastShortcuts(name, this.#onColorHex(name, colors))]
 	}
 
 	/**