颜色与对比度：相对亮度不是通道平均值

三种记法各有用途

hex 是交付格式，rgb 适合通道运算，hsl 是调色时唯一符合直觉的。互转本身不难，容易出错的是往返精度：hsl 的色相是浮点，取整后再转回来颜色就变了。所以中间表示保留浮点，只在最终输出时格式化。

相对亮度不是通道平均

WCAG 对比度的第一步是把 sRGB 通道还原成线性值，用的是 gamma 近似：

c = channel / 255
linear = c <= 0.03928 ? c / 12.92 : ((c + 0.055) / 1.055) ^ 2.4
L = 0.2126 * R + 0.7152 * G + 0.0722 * B

然后对比度是 (L1 + 0.05) / (L2 + 0.05)，亮的那一支在上。

跳过 gamma 直接对 RGB 求平均，是这类工具最常见的错误：算出来的数字看起来合理，但在中间调会明显偏离规范，AA/AAA 的判定也就不可信了。

阈值

正文文本要 4.5:1（AA）或 7:1（AAA），大号文本放宽到 3:1 与 4.5:1。工具把等级直接标出来，而不是只给数字——数字需要对照规范才知道够不够。

色阶不是混白混黑

50 到 900 的色阶如果简单地朝白色与黑色线性插值，中间几档会糊成一片，失去分离度。可行的做法是固定色相与饱和度，按感知亮度均匀取样，让相邻档之间的视觉差距尽量一致。

黑字还是白字

常见写法是判断亮度是否大于 128。这个规则在黄绿区间会给出错误答案——那些颜色的亮度中等偏高，但和白字的对比度仍然不够。可靠做法是把两种前景都算一遍，取对比度更大的那个，然后如实报告数值。

自检

这类计算适合用已知值兜底：纯黑对纯白的对比度必须是 21，同一颜色对自身必须是 1，三种记法往返转换必须回到原值。把这三条写进自检，重构时就不必重新推导公式。