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]
---

/// @name leo
/// @summary Generate a color at a target contrast using Leonardo.
/// @description Supports two modes. In family mode, pass a color family ref
///   as $color — the resolver extracts the key color and default background
///   from the family group. In 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.
///   Family mode: leo({palette.family.blue}, 4.5) → family color at 4.5 contrast.
///   Direct mode: leo(#4f6afc, 4.5, #ffffff) → ad-hoc contrast color.
/// @param $color <ref|color> Color family ref or raw key color value.
/// @param $contrast <number> Target contrast ratio between generated color and background.
/// @param $background <color|ref> Contrast surface. Defaults to white when family background is unavailable.
/// @param $model <wcag2|apca|wcag3> Contrast algorithm. Default wcag2.
/// @returns <color>
/// @constraints $contrast > 0
/// @example leo({palette.family.blue}, 4.5) → #4f6afc
/// @example leo({palette.family.blue}, 2.89, #1a1a2e) → #8fa4ff
/// @example leo(#4f6afc, 4.5, #ffffff, apca) → #4f6afc
/// @since 0.1.0
@function leo($color, $contrast, $background: white, $model: wcag2) {
  @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 two 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

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.

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
wcag2	WCAG 2.x luminance contrast ratio (default)	General accessibility compliance
apca	Advanced Perceptual Contrast Algorithm	Modern perceptual accuracy, future WCAG 3
wcag3	WCAG 3 draft algorithm	Experimental — tracks W3C draft