Example: Leonardo Color

This example demonstrates contrast-aware color generation using Adobe Leonardo, adapted for DTCG formula definitions.

The Definition

color.module.scssdef

---
module: leonardo
title: Leonardo Color
summary: Contrast-aware palette color generation via Adobe Leonardo.
category: color
since: 0.1.0
tags: [color, contrast, accessibility, leonardo, palette]
see: [builtins, contrast]
---

/// @name leo
/// @summary Generate a palette shade at a target contrast ratio via Leonardo.
/// @description Supports two modes:
///   **Family mode** — pass a color family ref as $color; the resolver extracts
///   the key color and default background from the family group.
///   **Direct mode** — pass a raw color value as $color with an explicit $background.
///   In both modes, $contrast is the target contrast ratio between the generated
///   color and the background surface.
///
///   For selecting an optimal foreground color (black or white) against a
///   background, use `optimal-foreground()` instead.
/// @param $color <ref|color> Color family ref or raw key color.
/// @param $contrast <number> Target contrast ratio.
/// @param $background <color|ref> Contrast surface. Defaults to white.
/// @param $model <apca|wcag2|wcag3> Contrast algorithm. Default apca.
/// @returns <color>
/// @constraints $contrast > 0
/// @example leo({palette.family.blue}, 60) → #4f6afc
/// @example leo({palette.family.blue}, 45, #1a1a2e) → #8fa4ff
/// @example leo(#4f6afc, 4.5, #ffffff, wcag2) → #4f6afc
/// @example leo({palette.gray.key}, 4.54, #ffffff, wcag2) → #767676
/// @see optimal-foreground — for selecting black/white foreground against a background
/// @since 0.1.0
/// @changed 0.2.0 — removed foreground mode (use optimal-foreground() instead)
@function leo($color, $contrast, $background: white, $model: apca) {
  @return leonardo($color, $contrast, $background, $model);
}

How It Works

1. leo() takes a color family ref (or raw hex) and a target contrast ratio
2. Leonardo generates a color that hits the specified contrast against the background surface
3. Supports three modes:
   • Family mode — pass a {palette.family.*} ref; the resolver extracts the key color and default background from the family group
   • Direct mode — pass a raw color value with an explicit $background
   • Foreground mode — pass optimal-foreground as the contrast parameter to select black or white for maximum readability on the given background

Usage Examples

Minimal — family mode (2 args)

leo({palette.family.blue}, 4.5)   → #4f6afc

Family ref resolves key color + background automatically. Contrast target 4.5 meets WCAG AA for normal text.

Background override (3 args)

leo({palette.family.blue}, 2.89, #1a1a2e)   → #8fa4ff

Dark background surface — lower contrast ratio is appropriate for large text or decorative elements.

Maximal — direct mode (4 args)

leo(#4f6afc, 4.5, #ffffff, apca)   → #4f6afc

Raw hex input, explicit background, APCA contrast model. Useful when working outside the palette system.

Foreground selection — optimal-foreground mode

leo({palette.blue.700}, optimal-foreground)   → #ffffff
leo({palette.gray.300}, optimal-foreground)   → #000000

Selects black or white for maximum readability on the given background. Uses APCA by default, accounting for the Helmholtz-Kohlrausch effect on saturated chromatic midtones. This is the formula behind on_ palette tokens.

DTCG Extension

{
  "color": {
    "action": {
      "primary": {
        "$value": "#4f6afc",
        "$type": "color",
        "$extensions": {
          "org.dtcg-formulas": {
            "formula": "leo({palette.family.blue}, 4.5)",
            "definition": "tokens/functions/leonardo-color/color.module.scssdef#leo"
          }
        }
      }
    }
  }
}

Contrast Models

Model	Description	When to use
apca	Advanced Perceptual Contrast Algorithm (default)	Perceptually accurate contrast — accounts for Helmholtz–Kohlrausch effect on saturated colors
wcag2	WCAG 2.x luminance contrast ratio	Legacy compliance, achromatic-only contexts
wcag3	WCAG 3 draft algorithm	Experimental — tracks W3C draft

Why APCA is the default: WCAG2's luminance model ignores chromaticity, producing systematically wrong contrast predictions for saturated midtone colors (blue, red, green 400-700 range). APCA accounts for the Helmholtz-Kohlrausch effect — saturated colors appear darker than their luminance suggests — and produces perceptually correct text color selections. See ADR-001 in DSYS-418.