leonardo-colors

Leonardo Contrast Colors — エージェントスキル

@adobe/leonardo-contrast-colors を使ってユーザーをサポートする場合は、次の手順に従ってください。API の詳細（パラメーター、型、セッター）については、必要に応じて 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

テーマごとに 1 つ使用します。背景と、指定した比率におけるグレー（またはその他のニュートラルカラー）のスケールを定義します。

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 の作成

1 つの BackgroundColor と 1 つ以上の 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. Theme の出力を取得する

ゲッターは 3 つあります。

• theme.contrastColors — 配列です。最初の要素は { background: '#...' } で、その後に各 Color のオブジェクトが続きます。各オブジェクトには 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 の変更

作成後、次の値を変更できます。

• 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）です。完全なテーマを作成せずに、2 色をチェックする場合に使用します。
• 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' を設定します。APCA の Lc 値は WCAG 3 のガイダンスに従って解釈してください。ライブラリは 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)）。

---

パラメーターの全一覧、セッターの一覧、型の詳細については、references/api.md を参照してください。