leonardo-colors

Leonardo Contrast Colors — Agent 技能

帮助用户使用 @adobe/leonardo-contrast-colors 时，请按以下步骤操作。需要完整的 API 详情（参数、类型、setter）时，按需加载 references/api.md。

1. 安装

npm i @adobe/leonardo-contrast-colors

ESM（推荐）：

import { Theme, Color, BackgroundColor, contrast, convertColorValue, luminance, createScale } from '@adobe/leonardo-contrast-colors';

2. 创建 Color 和 BackgroundColor

BackgroundColor

每个主题创建一个。用于定义背景，以及目标对比度下的灰色（或其他中性色）色阶。

const gray = new BackgroundColor({
  name: 'gray',
  colorKeys: ['#cacaca'],   // one or more keys to interpolate
  ratios: [2, 3, 4.5, 8]   // target contrast ratios (positive = darker than background)
});

Color（前景色）

用于定义在特定对比度下的语义颜色（例如蓝色、红色）。

const blue = new Color({
  name: 'blue',
  colorKeys: ['#5CDBFF', '#0000FF'],  // interpolated in colorspace
  colorspace: 'LCH',                  // optional; default 'RGB'
  ratios: [3, 4.5]                    // e.g. large text (3:1), normal text (4.5:1)
});

参数：

• name — 用于为输出名称添加前缀（例如 blue100、blue200）。
• colorKeys — CSS 颜色字符串数组；色阶会在这些颜色之间插值。
• colorspace（或 colorSpace）— 插值空间：'LCH'、'LAB'、'RGB'、'HSL'、'HSV'、'HSLuv'、'CAM02'、'CAM02p'、'OKLAB'、'OKLCH'。默认值为 'RGB'。
• ratios — 数字数组（例如 [3, 4.5, 7]），或将自定义名称映射到对比度的对象（例如 { 'blue--largeText': 3, 'blue--normalText': 4.5 }）。
• smooth — 可选布尔值；控制插值时是否进行贝塞尔平滑处理（默认值为 false）。
• output — 可选的输出格式（默认值为 'HEX'）；通常会被 Theme 覆盖。

负对比度 — 对于比背景更亮的颜色（例如深色模式下的文本），请使用负值（例如 -1.5、-3）。负值的命名采用分数增量（例如 gray25、gray50）。

3. 创建 Theme

将一个 BackgroundColor 和一个或多个 Color 组合起来，并设置亮度以及可选的对比度/饱和度。

const theme = new Theme({
  colors: [gray, blue, red],   // gray is BackgroundColor; blue, red are Color
  backgroundColor: gray,       // required; must be the BackgroundColor instance
  lightness: 97,               // 0–100; background lightness (e.g. 97 = light, 8 = dark)
  contrast: 1,                 // optional; multiplier for all ratios (default 1)
  saturation: 100,            // optional; 0–100 (default 100)
  output: 'HEX',               // optional; default 'HEX'
  formula: 'wcag2'             // optional; 'wcag2' (default) or 'wcag3' (APCA)
});

注意： colors 应包含同一个 BackgroundColor，且将其作为第一个元素（或至少包含在列表中），以及所有前景 Color。Theme 要求将 backgroundColor 设置为该 BackgroundColor 实例。

4. 读取主题输出

三个 getter：

• theme.contrastColors — 数组：第一个元素为 { background: '#...' }，之后每种颜色对应一个对象，包含 name 和 values: [{ name, contrast, value }]。可用于生成设计令牌或 CSS 变量。
• theme.contrastColorPairs — 扁平对象：{ gray100: '#e0e0e0', blue100: '#b18cff', ... }。可用于快速查找。
• theme.contrastColorValues — 仅包含颜色字符串的扁平数组。

CSS 变量的迭代示例：

for (const item of theme.contrastColors) {
  if (item.background) {
    document.documentElement.style.setProperty('--background', item.background);
  } else {
    for (const v of item.values) {
      document.documentElement.style.setProperty(`--${v.name}`, v.value);
    }
  }
}

5. 在运行时修改主题

创建后，你可以修改：

• theme.lightness = 8 — 例如切换为深色背景。
• theme.contrast = 1.2 — 全局提高对比度。
• theme.saturation = 80 — 降低饱和度。
• theme.output = 'RGB' — 更改输出格式。
• theme.backgroundColor = otherBackgroundColor — 更换背景（传入 BackgroundColor 实例）。
• theme.colors = [gray, blue, red, green] — 替换颜色列表。

添加/移除/更新颜色：

• theme.addColor = newColor — 添加一个 Color 实例。
• theme.removeColor = { name: 'red' } 或 theme.removeColor = redColorInstance — 按名称或实例移除。
• theme.updateColor = { name: 'red', ratios: [3, 4.5, 7] } — 按名称更新颜色的对比度（或 colorKeys、name 等）。

设置任何属性后，请重新读取 theme.contrastColors（或 pairs/values）；这些值会在访问时计算。

6. 实用函数

• contrast(foregroundRgbArray, backgroundRgbArray, baseV?, method?) — 返回对比度。method：'wcag2'（默认）或 'wcag3'。RGB 数组格式为 [r, g, b]（0–255）。可用于检查两种颜色，无需构建完整主题。
• convertColorValue(colorString, format, object?) — 将任意受支持的颜色字符串转换为 format（例如 'HEX'、'RGB'、'LCH'）。如果 object === true，则返回通道对象而不是字符串。
• luminance(r, g, b) — sRGB 的相对亮度（0–1）。
• createScale({ swatches, colorKeys, colorSpace?, shift?, fullScale?, smooth?, distributeLightness?, sortColor?, asFun? }) — 构建插值色阶（不进行对比度目标处理）。除非设置 asFun: true（返回色阶函数），否则返回颜色字符串数组。适用于不要求无障碍的调色板，或在颜色键之间取色。

7. 常见的无障碍配色方案

• WCAG 2 AA（普通文本） — 最低 4.5:1。使用 ratios: [4.5]，或在 ratios 中包含 4.5。
• WCAG 2 AAA（普通文本） — 最低 7:1。使用 ratios: [7]，或包含 7。
• WCAG 2 大号文本 — 最低 3:1。对大号文本标记使用 ratios: [3]，或包含 3。
• WCAG 2 AA + 大号文本 — 使用 ratios: [3, 4.5]，并可通过对象命名：{ 'brand--large': 3, 'brand--normal': 4.5 }。
• WCAG 3 / APCA — 在 Theme 上设置 formula: 'wcag3'。按照 WCAG 3 指南解读 APCA Lc 值；当 method 为 'wcag3' 时，该库会返回对比度的 Lc 值。

建议：优先使用 LCH 或 LAB 进行插值（colorspace: 'LCH'），以获得感知上更均匀的色阶。

8. 支持的色彩空间和输出格式

插值色彩空间（Color/BackgroundColor colorSpace、createScale）：
LCH、LAB、RGB、HSL、HSV、HSLuv、CAM02、CAM02p、OKLAB、OKLCH。

输出格式（Theme 输出、Color 输出、convertColorValue）：
HEX、RGB、HSL、HSV、HSLuv、LAB、LCH、CAM02、CAM02p、OKLAB、OKLCH。

值遵循 W3C CSS Color Module Level 4 规范（例如 lch(100% 0 360deg)、rgb(255 255 255)）。

---

完整的参数表、setter 列表和类型详情，请参阅 references/api.md。