Malachi.UI.TokenGen.Source (malachi v0.22.7)

View Source

Reads docs/design/design-tokens.json and enforces every rule about its shape.

This module is the only definition of what a valid token file is: there is no separate JSON Schema, because most of the rules are about meaning (a reference resolves to a token of the right type, a terminal token has a hand declared sixteen color entry, a contrast pair names two colors) and a schema cannot express them. Every rule that fails is reported, each message starting with the path of the token or section it concerns, so one run lists everything that needs fixing.

Nothing here computes a color. Malachi.UI.TokenGen.Model does that from the t/0 this returns, and Malachi.UI.TokenGen.Gates judges the result.

The file

  • Every top level key that does not start with $ is a token group. Groups nest; a group that holds tokens declares $prefix, and a token's name is that prefix followed by its key unless the token declares $name. $type is inherited down the tree.
  • A token is an object with $value, or, for a color only, light and dark. A $value may be a reference, {path.to.token}, which keeps the referenced token's type.
  • The sections are $platforms, $contrast, $cvd, $apart, $gamut, $ansi16, $ansi256 and $terminal, all required, plus the free text $description and $meta.
  • The sixteen color tier is never inferred. A terminal token without an $ansi16 entry is an error, not a gap this module fills.

Summary

Types

ansi16()

A sixteen color entry: an ANSI SGR color number, or :default to inherit, and its ratatui name.

t()

Functions

ansi_name(code)

The ratatui color a sixteen color code stands for; :default is Color::Reset.

load(text)

Decodes a token file and parses it.

parse(root)

Parses a decoded token file, with its objects in declaration order.

value_references(token)

The tokens a token's value is made of: the one it references whole, or each one a shadow or a typography value references. Not its $modes, which replace the value rather than build it.

Types

ansi16()

@type ansi16() :: %{code: 0..15 | :default, ratatui: String.t()}

A sixteen color entry: an ANSI SGR color number, or :default to inherit, and its ratatui name.

t()

@type t() :: %Malachi.UI.TokenGen.Source{
  ansi16: %{required(String.t()) => ansi16()},
  ansi256: %{
    light: %{required(String.t()) => 16..255},
    dark: %{required(String.t()) => 16..255}
  },
  apart: %{min: float(), sets: [%{these: [String.t()], from: [String.t()]}]},
  contrast: [
    %{
      foreground: String.t(),
      background: String.t(),
      role: :text | :graphic,
      min: float()
    }
  ],
  cvd: %{min: float(), sets: [[String.t()]]},
  gamut: %{max: float()},
  terminal: %{
    inherited: %{background: String.t(), foreground: String.t()},
    distinct: [String.t()],
    painted16: %{
      light: %{background: ansi16(), foreground: ansi16()},
      dark: %{background: ansi16(), foreground: ansi16()}
    }
  },
  tokens: [Malachi.UI.TokenGen.Token.t()],
  tui: [String.t()]
}

Functions

ansi_name(code)

@spec ansi_name(0..15 | :default) :: String.t()

The ratatui color a sixteen color code stands for; :default is Color::Reset.

load(text)

@spec load(String.t()) :: {:ok, t()} | {:error, [String.t()]}

Decodes a token file and parses it.

parse(root)

@spec parse(Jason.OrderedObject.t()) :: {:ok, t()} | {:error, [String.t()]}

Parses a decoded token file, with its objects in declaration order.

value_references(token)

@spec value_references(Malachi.UI.TokenGen.Token.t()) :: [String.t()]

The tokens a token's value is made of: the one it references whole, or each one a shadow or a typography value references. Not its $modes, which replace the value rather than build it.