pantoken / plugins/pantoken/colors/src / onColor

Function: onColor()

onColor(surface, threshold?): string

Beta

The readable foreground — black or white — for content placed on surface. This is the CSS-only form of InstUI's recurring *-on-color variants (a focus ring on a brand button, a primary-inverse button's text, an icon on a coloured surface): rather than a fixed inverse token, it picks the contrast from the surface itself, so it stays correct as the surface changes.

It reads the surface's OKLCH lightness through relative color syntax and snaps it to 0 (black) or 1 (white) at threshold using the calc(… * infinity) clamp trick — no JS, no fixed hex.

Parameters

surface

string

The background colour content sits on (literal, var(--token), or a nested helper).

threshold?

number = 0.62

OKLCH lightness (0–1) above which the surface counts as "light" (default 0.62).

Returns

string

An oklch(from …) expression resolving to black or white.

Example

onColor("var(--instui-color-background-brand)"); // white on a dark brand surface, black on a light one
// → "oklch(from var(--…-brand) clamp(0, (0.62 - l) * infinity, 1) 0 0)"