A theme as a document (spec/04 §5): stored and shipped as a value, and judged as one.

• the value is %{version: v, theme: node} (to_map/1), and a store's fragment %{theme: node} (fragment/1), a library entry of kind :theme, reads as the same document;
• the JSON form is {"$version": v, "theme": {…}} (to_json/1), each color a tag (a literal $rgb, $color, $series, $ramp, the transforms by name, $blend, $contrast) and pinned steps $steps, written and read by the JSON adapter (Macaw.Layers.Form, Macaw.Layers.Color.Form), every name in ramps, colors, styles and defaults a string, as the theme holds it, and every word (an entry's keys and atom values) read from the library's vocabulary and the registered extensions' words (Macaw.Layers.Theme.Extension.words/0).

from_map/2 judges the value as terms, after the version check, with no form written or read; from_json/2 reads the JSON form through the adapter's gates (spec/01 §5: the limits, the version, the migration) to the same value. A name given both as its atom and as its string in one name map of a value is {:duplicate, :name} at its path. Then: a node that is a name reads as the built-in theme of that name, any other name is {:unknown_theme, name}; a variable anywhere is {:unresolved, :var, name}, since nothing applies a theme; a key the theme does not have is :unknown_key; and every contract a ramp, color or palette entry breaks is {:contract, message} at [:theme, :ramps | :colors | :styles, name].

The line is at version 2: a literal color is a term, tagged $rgb in the JSON form. Version 1 wrote it as CSS text; its step tags each string at a color position that Macaw.Layers.Color.parse/1 reads, so a version 1 document, or a bundle's entry of one, reads to the same theme.

As a fragment type (spec/02 §1), ramps, colors, styles and defaults are :union name maps and every other key :override, so a theme document stacks over a built-in as Macaw.Layers.Theme.new/1 merges.

iex> theme = Macaw.Layers.Theme.new(name: :house, axis: Macaw.Layers.Color.parse!("#555555"))
iex> Macaw.Layers.Theme.Document.from_map(Macaw.Layers.Theme.Document.to_map(theme))
{:ok, theme}
iex> Macaw.Layers.Theme.Document.from_map(%{theme: :dark})
{:ok, Macaw.Layers.Theme.dark()}

Ported from visualize's Visualize.Chart.Theme.