Leonardo Colors

Leonardo Contrast Colors — Agent Skill

When helping users with @adobe/leonardo-contrast-colors, follow these steps. For full API details (parameters, types, setters), load references/api.md on demand.

1. Installation

npm i @adobe/leonardo-contrast-colors

ESM (recommended):

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

2. Creating Color and BackgroundColor

BackgroundColor

One per theme. Defines the background and the scale of grays (or other neutrals) at target ratios.

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 (foreground)

Defines a semantic color (e.g. blue, red) at specific contrast ratios.

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)
});

Parameters:

• name — Used to prefix output names (e.g. blue100, blue200).
• colorKeys — Array of CSS color strings; the scale is interpolated between them.
• colorspace (or colorSpace) — Interpolation space: 'LCH', 'LAB', 'RGB', 'HSL', 'HSV', 'HSLuv', 'CAM02', 'CAM02p', 'OKLAB', 'OKLCH'. Default 'RGB'.
• ratios — Either an array of numbers (e.g. [3, 4.5, 7]) or an object mapping custom names to ratios (e.g. { 'blue--largeText': 3, 'blue--normalText': 4.5 }).
• smooth — Optional boolean; bezier smoothing for interpolation (default false).
• output — Optional output format (default 'HEX'); usually overridden by Theme.

Negative ratios — Use negative values (e.g. -1.5, -3) for colors lighter than the background (e.g. text on dark mode). Naming for negatives uses fractional increments (e.g. gray25, gray50).

3. Creating a Theme

Combine one BackgroundColor and one or more Colors with a lightness and optional contrast/saturation.

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)
});

Note: colors should include the same BackgroundColor as the first element (or at least include it in the list) plus all foreground Colors. The Theme requires backgroundColor to be set to that BackgroundColor instance.

4. Reading theme output

Three getters:

• theme.contrastColors — Array: first element { background: '#...' }, then one object per color with name and values: [{ name, contrast, value }]. Use for design tokens or CSS variable generation.
• theme.contrastColorPairs — Flat object: { gray100: '#e0e0e0', blue100: '#b18cff', ... }. Use for quick lookups.
• theme.contrastColorValues — Flat array of color strings only.

Example iteration for CSS variables:

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. Mutating a theme at runtime

After construction you can change:

• theme.lightness = 8 — e.g. switch to dark background.
• theme.contrast = 1.2 — increase contrast globally.
• theme.saturation = 80 — reduce saturation.
• theme.output = 'RGB' — change output format.
• theme.backgroundColor = otherBackgroundColor — swap background (pass BackgroundColor instance).
• theme.colors = [gray, blue, red, green] — replace color list.

Adding/removing/updating colors:

• theme.addColor = newColor — Add a Color instance.
• theme.removeColor = { name: 'red' } or theme.removeColor = redColorInstance — Remove by name or by instance.
• theme.updateColor = { name: 'red', ratios: [3, 4.5, 7] } — Update a color’s ratios (or colorKeys, name, etc.) by name.

After any setter, re-read theme.contrastColors (or pairs/values); they are computed on access.

6. Utility functions

• contrast(foregroundRgbArray, backgroundRgbArray, baseV?, method?) — Returns contrast ratio. method: 'wcag2' (default) or 'wcag3'. RGB arrays are [r, g, b] (0–255). Use to check two colors without building a full theme.
• convertColorValue(colorString, format, object?) — Convert any supported color string to format (e.g. 'HEX', 'RGB', 'LCH'). If object === true, returns channel object instead of string.
• luminance(r, g, b) — Relative luminance (0–1) for sRGB.
• createScale({ swatches, colorKeys, colorSpace?, shift?, fullScale?, smooth?, distributeLightness?, sortColor?, asFun? }) — Build an interpolated scale (no contrast targeting). Returns array of color strings unless asFun: true (returns scale function). Useful for non-accessible palettes or stepping between keys.

7. Common accessibility recipes

• WCAG 2 AA (normal text) — Minimum 4.5:1. Use ratios: [4.5] or include 4.5 in ratios.
• WCAG 2 AAA (normal text) — Minimum 7:1. Use ratios: [7] or include 7.
• WCAG 2 large text — Minimum 3:1. Use ratios: [3] or include 3 for large text tokens.
• WCAG 2 AA + large text — Use ratios: [3, 4.5] and name via object if desired: { 'brand--large': 3, 'brand--normal': 4.5 }.
• WCAG 3 / APCA — Set formula: 'wcag3' on Theme. Interpret APCA Lc values per WCAG 3 guidance; the library returns Lc for contrast when method is 'wcag3'.

Recommendation: Prefer LCH or LAB for interpolation (colorspace: 'LCH') for perceptually even scales.

8. Supported colorspaces and output formats

Interpolation colorspaces (Color/BackgroundColor colorSpace, createScale): LCH, LAB, RGB, HSL, HSV, HSLuv, CAM02, CAM02p, OKLAB, OKLCH.

Output formats (Theme output, Color output, convertColorValue): HEX, RGB, HSL, HSV, HSLuv, LAB, LCH, CAM02, CAM02p, OKLAB, OKLCH.

Values follow W3C CSS Color Module Level 4 (e.g. lch(100% 0 360deg), rgb(255 255 255)).

---

For full parameter tables, setter lists, and type details, see references/api.md.

@adobe/leonardo-contrast-colors — Full API Reference

This document is the detailed API reference for the Leonardo Contrast Colors library. Use it when you need parameter types, setters, or output shapes.

---

Theme

Class that generates adaptive contrast-based colors from a background and a list of colors with target ratios.

Constructor

new Theme({ colors, backgroundColor, lightness, contrast?, saturation?, output?, formula? })

Getters (read-only)

Setters

Theme.updateColor options

Pass an object with:

• name (or color) — Current name of the color to update.
• ratios — New ratios (array or object).
• colorKeys — New color key array.
• name (as target) — New name for the color (rename).

Multiple updates: pass an array of such objects to theme.updateColor.

---

Color

Class that defines a single color scale with target contrast ratios (foreground or background).

Constructor

new Color({ name, colorKeys, colorspace?, colorSpace?, ratios, smooth?, output?, saturation? })

Setters

Read-only

• color.colorScale — Internal chroma scale (advanced use).

---

BackgroundColor

Extends Color. Used as the theme background. Same constructor and options as Color. Has an additional read-only backgroundColorScale (internal). Use one BackgroundColor per Theme and pass it as theme.backgroundColor.

---

createScale(options)

Builds an interpolated color scale (no contrast targeting).

Options

Returns

• If asFun is false (default): array of CSS color strings.
• If asFun is true: chroma scale function.

---

contrast(foregroundRgbArray, baseRgbArray, baseV?, method?)

Computes contrast between two colors given as RGB arrays [r, g, b] (0–255).

Returns: number — Contrast ratio (WCAG 2) or APCA Lc value (WCAG 3).

---

convertColorValue(color, format, object?)

Converts a color from any supported input to a target format.

Returns: string or channel object when object === true.

---

luminance(r, g, b)

Relative luminance of sRGB channels (0–255 each).

Returns: number in 0–1.

---

minPositive(ratioArray, formula)

Returns the minimum positive value in a ratio array for the given formula.

• ratioArray: number[]
• formula: 'wcag2' \| 'wcag3'

Returns: number

---

ratioName(ratioArray, formula)

Maps ratio array to named values for the given formula.

• ratioArray: number[]
• formula: 'wcag2' \| 'wcag3'

Returns: number[]

---

Types

Colorspace

Output / format names: 'HEX' | 'RGB' | 'HSL' | 'HSV' | 'HSLuv' | 'LAB' | 'LCH' | 'OKLAB' | 'OKLCH' | 'CAM02' | 'CAM02p'

InterpolationColorspace

All except 'HEX': 'RGB' | 'HSL' | 'HSV' | 'HSLuv' | 'LAB' | 'LCH' | 'OKLAB' | 'OKLCH' | 'CAM02' | 'CAM02p'

ContrastFormula

'wcag2' | 'wcag3'

Output format examples (W3C CSS Color Level 4)

contrastColors shape

[
  { background: string },
  { name: string, values: Array<{ name: string, contrast: number, value: string }> },
  ...
]

contrastColorPairs shape

{ [tokenName: string]: string }

e.g. { "gray100": "#e0e0e0", "blue200": "#8d63ff" }.