pantoken / plugins/pantoken/colors/src / onColor

函数: onColor()

onColor(surface, threshold?): string

Beta

可读的前景色——黑或白——用于放置在 on surface 上的内容。这是 InstUI 常见的 *-on-color 变体的纯 CSS 形式（品牌按钮的焦点环、主-反色按钮的文字、彩色表面上的图标）：它不是使用固定的反色 token，而是从表面本身选择对比度，因此当表面变化时仍能保持正确。

它通过相对颜色语法读取表面的 OKLCH 明度，并在 threshold 处使用 calc(… * infinity) clamp 技巧将其钳制到 0（黑）或 1（白）——无需 JS，也无需固定的十六进制颜色。

参数

surface

string

背景颜色内容所位于的对象（字面值、var(--token)，或嵌套的 helper）。

threshold?

number = 0.62

将表面视为“浅色”的 OKLCH 明度阈值（0–1）（默认 0.62）。

返回值

string

一个解析为黑色或白色的 oklch(from …) 表达式。

示例

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)"