Encode and decode W3C Design Tokens Community Group color tokens, per the October 2025 draft of the DTCG Color spec.

Design tokens are a portable JSON format for design-system values. A color token looks like this:

%{
  "$type" => "color",
  "$value" => %{
    "colorSpace" => "oklch",
    "components" => [0.63, 0.19, 259.5],
    "alpha" => 1.0,
    "hex" => "#3b82f6"
  }
}

This module converts between those maps and the library's Color.* structs, so palettes can round-trip through any tool that speaks the DTCG format (Style Dictionary, Figma, Penpot, and so on).

Encode

iex> {:ok, color} = Color.new("#3b82f6")
iex> token = Color.DesignTokens.encode(color)
iex> token["colorSpace"]
"srgb"

To emit in a different colour space, convert first:

iex> {:ok, oklch} = Color.convert("#3b82f6", Color.Oklch)
iex> Color.DesignTokens.encode(oklch) |> Map.get("colorSpace")
"oklch"

Or use encode/2 with the :space option — it runs the conversion for you:

iex> token = Color.DesignTokens.encode("#3b82f6", space: Color.Oklch)
iex> token["colorSpace"]
"oklch"

Decode

iex> value = %{"colorSpace" => "oklch", "components" => [0.63, 0.19, 259.5], "alpha" => 1}
iex> {:ok, oklch} = Color.DesignTokens.decode(value)
iex> match?(%Color.Oklch{}, oklch)
true

Decode also accepts full tokens (with $type / $value), and a hex-only fallback:

iex> {:ok, srgb} = Color.DesignTokens.decode(%{"hex" => "#3b82f6"})
iex> Color.to_hex(srgb)
"#3b82f6"

Unknown colour spaces or malformed input return {:error, %Color.DesignTokensDecodeError{}}.

Supported colour spaces

The DTCG spec and our mapping:

Alias tokens

DTCG supports alias tokens — "$value" => "{palette.blue.500}" — that reference another token. This module does not resolve aliases. Resolve them in the caller (where you have the full token tree) before passing values here. decode/1 returns a specific :alias_not_resolved error if it sees one, so you can handle them cleanly.