Example: Color Names

This example demonstrates human-readable color naming using the meodai/color-names dataset (30 000+ named colors), adapted for DTCG formula definitions.

The Definition

color-names.module.scssdef

---
module: color-names
title: Color Names
summary: Human-readable color naming via nearest-match lookup.
category: color
since: 0.2.0
tags: [color, naming, accessibility, semantics]
see: [builtins]
---

/// @name color-name
/// @summary Return the closest human-readable name for a color.
/// @description Uses the meodai/color-names dataset (30 000+ entries) to find the
///   perceptually nearest named color. Useful for generating accessible labels,
///   semantic aliases, or documentation from raw hex values.
/// @param $color <color|ref> A hex color value or token reference.
/// @returns <string>
/// @example color-name(#ff6347) → Tomato
/// @example color-name(#bada55) → BadAss
/// @example color-name({palette.brand.primary}) → Ultramarine
@function color-name($color) {
  @return color-name($color);
}

How It Works

1. color-name() takes a hex color value or a token reference that resolves to a color
2. The adapter performs a nearest-neighbor lookup against the color-names dataset
3. Returns the closest human-readable name as a plain string

This is useful for generating accessible labels, semantic token aliases, or documentation annotations from raw hex values.

Usage Examples

Direct hex

color-name(#ff6347)   // Tomato

Standard CSS named color — exact match in the dataset.

Novelty hex

color-name(#bada55)   // BadAss

The dataset includes community-submitted names for well-known hex values.

Token reference

color-name({palette.brand.primary})   // Ultramarine

Pass a token ref — the resolver dereferences it to a hex value before lookup.

DTCG Extension

{
  "color": {
    "brand": {
      "primary-name": {
        "$value": "Ultramarine",
        "$extensions": {
          "org.dtcg-formulas": {
            "formula": "color-name({palette.brand.primary})",
            "definition": "tokens/functions/color-names/color-names.module.scssdef#color-name"
          }
        }
      }
    }
  }
}

Note: no $type is needed here — $value is a plain string, not a DTCG typed value.

Dataset Reference

The meodai/color-names repository provides:

• 30 000+ crowd-sourced color names
• Multiple dataset variants (best-of, short names, full corpus)
• Nearest-color matching via perceptual distance (Delta E)
• Available as npm package (color-name-list) or raw JSON