The colors, fonts and sizes a page draws with (spec/04 §2, §3).
A theme is a struct of named slots: "series_1" … "series_n" for the categorical
colors; the furniture "axis", "grid", "text", "background" and "surface"; the
five roles "good", "warning", "bad", "info" and "neutral"; and
"font_family", "font_size", "label_size" and "title_size". Its colors are one
color table (§2.2):
the theme's own colors over the default theme's, its extensions' and the CSS named
colors, with the furniture and the series as names too, so Macaw.Layers.Color.color(:red)
is the theme's red. Everything reads a theme through resolve/3, in the mode its output
needs:
:literal- the stored value, which a canvas needs: a color a literal%Macaw.Layers.Color{};:css- a custom-property reference with the literal as its fallback,var(--mw-axis, #666666), so a stylesheet can override it from any ancestor.
Its colors are terms (§2.1): a literal is %Macaw.Layers.Color{}, read from text at the
edge (Macaw.Layers.Color.parse!/1, ~RGB"#3b6fa8"), and a string is never a color.
Its names are strings (§2.1), the library's, its extensions' and a host's alike: its
own name and its dark and light, the slots, the keys of ramps, colors and styles, and the name in every typed color
({:color, "good"}, {:ramp, "status", 0.5}). A name given as an atom is read as its
string, once, when the theme is built (new/1, merge/2, a document read), so :info
and "info" are one name; every function that takes a name takes either spelling. Its
words — a style's keys and atom values, defaults — are kept as given.
Meaning: ramps, roles and cues
A series color promises distinct, never a meaning. A theme also carries four ramps
whose meaning the library fixes (§2.3): "status", "thermal", "diverging" and
"sequential", each a list of anchors interpolated in CIE Lab, and every role and ramp is
held to its contract when a theme is built by new/1 or merge/2.
Whole styles: the style palette
styles carries the design over to whole styles (§2.4): style series, the roles as whole
looks, view states, furniture styles and modifiers, the names the library's and its
registered extensions' (§3.4). style/2 reads one, the default theme's where the theme
lacks it.
Examples
iex> Macaw.Layers.Theme.resolve(Macaw.Layers.Theme.default(), :axis, :css)
{:ok, "var(--mw-axis, #666666)"}
iex> Macaw.Layers.Theme.resolve(Macaw.Layers.Theme.dark(), {:series, 11}, :literal)
{:ok, %Macaw.Layers.Color{r: 127.0, g: 179.0, b: 230.0, opacity: 1.0}}
iex> Macaw.Layers.Theme.resolve(Macaw.Layers.Theme.default(), :warning, :css)
{:ok, "var(--mw-warning, #bd7407)"}
iex> Macaw.Layers.Theme.resolve(Macaw.Layers.Theme.default(), {:ramp, :status, 0.5}, :css)
{:ok, "var(--mw-warning, #bd7407)"}Ported from visualize's Visualize.Theme.
Summary
Types
How a slot renders: a CSS reference with its fallback, or the stored value.
One of the four ramps whose meaning the library fixes (§2.3): "status", "thermal",
"diverging" or "sequential", an atom given read as its string.
A position along a ramp: t in 0..1, clamped.
A slot name, or {:series, i} for the i-th series color, cycling.
A name of the style palette, or {:style, i} for the i-th style series entry.
Functions
The built-in theme of a name, "default", "dark", "color_safe" or "print", an atom
read as its string, or nil.
:ok, or {:error, subject, message} for the first ramp, color or palette entry of the
theme that breaks its contract, subject being {:ramp, name}, {:color, name} or
{:style, name} and message naming the term broken with the values measured.
A color value held to a profile (§4): under :roles a value with a literal color among
its leaves is {:literal_color, value} at []; under :open every color passes. A term
that is no color value is {:type, :color_value}, text :color_text, and a profile that
is neither {:enum, [:roles, :open]} at [:profile]. A builder's answer is checked as
its value.
Whether name is of the theme's color table, answered without building the list. A
name is its string, an atom read as its string.
Every name of the theme's color table, sorted: its color slots, its own and the default theme's colors, its extensions' and the CSS named colors.
The color-vision-safe theme: default/0 with its status ramp blue → orange → red, which
survives the commonest color-vision deficiencies, in place of green → amber → red.
The color slots: the series, then the furniture, then the five roles.
The custom-property name of a slot or a color name: --mw- and the name with _ as -.
A name is lower-case letters, digits and _, starting with a letter: {:ok, property},
any other {:type, :word} at [], so a stylesheet can never be broken out of through a
name.
A role's cue besides its hue: its glyph and its dash (nil for solid), so a status reads
without its hue. The role by its name, an atom read as its string: {:ok, cue}, or
anything but a role as {:enum, roles} at [:role].
The dark theme: light text and axes on #1b1e24.
A data color under the contrast guard (§4): {:ok, literal}, its literal color, where it
reaches 3:1 against the theme's background, {:error, {:contrast, ratio}} where it does
not, and {:error, :unreadable} for a term that is no color value or does not resolve,
text included.
The light theme: dark text and axes on white.
The contrast floors a theme offered to people holds against its own background: text
at least 4.5:1, axis and every series color at least 3:1, grid at least 1.2:1, and a
surface different from the grid. :ok, or {:error, faults}, each {slot, {:contrast, ratio, floor}}, the slot by its name, or {"surface", {:equal, "grid"}}.
A theme's fault as a person reads it, its path from the fields: the kernel's words
(Macaw.Layers.Fault.format/2), and a theme's own reasons.
The contrast ink for a text drawn on under: the literal color of the theme's text or
background, whichever contrasts more (text on a tie), or black or white, whichever
contrasts more, when neither reaches 4.5:1. under is a literal %Macaw.Layers.Color{},
or nil for the theme's background: {:ok, ink}, or text as :color_text at [:under]
and any other term {:type, :color}. A slot that holds no literal color, in a theme built
by hand, is skipped.
The theme with the given fields replaced, ramps, colors, styles and defaults merged
key by key over its own: {:ok, theme}, or every fault, as new/1 judges them. A color
builder's answer (Macaw.Layers.Color.color/1 and the rest) stands for its value wherever
a field holds a color.
merge/2, or an ArgumentError naming every fault.
default/0 with the given fields replaced; ramps, colors, styles and defaults
merged key by key: {:ok, theme}, or every fault by path from the fields, judged as a
theme document's node is (§5), so a theme written in code and one read from a document
answer one way. The faults: an unknown field, :unknown_key; a series or furniture
color that is not a literal color, {:type, :color} (a string is never a color: read
text with Macaw.Layers.Color.parse/1, or write it in the source as ~RGB"#555555"); an
empty series, {:type, :colors}, and one too long, {:limit, :series, max, n}; a
field of the wrong shape; a name given both as its atom and its string,
{:duplicate, :name}; an extension that can't be held (extensions:, at
[:extensions, i | …]); untrusted text that is unsafe, {:unsafe, kind}; and each ramp,
color or palette entry that breaks its contract, {:contract, message} at [:ramps | :colors | :styles, name] (§2.6). format/1 words them.
new/1, or an ArgumentError naming every fault: a theme written in code.
The print theme: paper. A white background and surface, near-black text and axes, a grid
dark enough to survive a photocopy, the color-safe status ramp, and role styles whose
fills are hatches of the role's color, so a grayscale copy keeps each role apart.
The color at t along the theme's ramp name, as a literal color: the anchors spread
evenly over 0..1 and interpolated in CIE Lab, a position on an anchor the anchor's
literal, t clamped. A theme that lacks the ramp takes the default theme's, never a series
color.
The four ramps whose meaning the library fixes, by name.
The slot's value: the stored literal, or a CSS custom-property reference that falls back
to its CSS text. A color is a literal %Macaw.Layers.Color{} under :literal; sizes are
numbers under :literal and gain px under :css. A ramp position is its literal in
both modes, as CSS text under :css, except where a status role stands, {:ramp, "status", 0 | 0.5 | 1}, which resolves as the role while the table holds the role there.
A name, of a slot, a color or a ramp, is its string, an atom read as its string.
The five roles: the status ramp's three fixed points, then "info" and "neutral".
The "series_k" slot the positive index i cycles to over the theme's series.
The theme's slot names: "series_1" to "series_n", then the fixed slots.
The palette entry name as one style node in its parts: the theme's own, the default
theme's entry whole where the theme lacks it, or an extension's default. {:style, i}
cycles over the style series; in a role's entry :cue becomes the role's dash and glyph,
a solid dash leaving the key out. {:ok, style}, or a name not of the palette as
{:unknown_style, name} at [], and anything that is neither a name nor {:style, i},
i a positive integer, as {:type, :style_name}.
The theme's palette names: its style series, the default's ten when it has none of its own, then the roles, the states, the furniture and the modifiers, then its extensions'.
Every ramp, color and palette entry of the theme that breaks its contract, as
{subject, message} in check/1's order, each contract run alone.
Types
@type mode() :: :css | :literal
How a slot renders: a CSS reference with its fallback, or the stored value.
One of the four ramps whose meaning the library fixes (§2.3): "status", "thermal",
"diverging" or "sequential", an atom given read as its string.
A position along a ramp: t in 0..1, clamped.
@type slot() :: String.t() | atom() | {:series, pos_integer()}
A slot name, or {:series, i} for the i-th series color, cycling.
@type style_name() :: String.t() | atom() | {:style, pos_integer()}
A name of the style palette, or {:style, i} for the i-th style series entry.
@type t() :: %Macaw.Layers.Theme{ axis: Macaw.Layers.Color.t(), background: Macaw.Layers.Color.t(), colors: %{optional(String.t()) => term()}, dark: String.t() | nil, defaults: map(), extensions: [module()], font_family: String.t(), font_size: number(), grid: Macaw.Layers.Color.t(), label_size: number(), light: String.t() | nil, name: String.t(), ramps: %{optional(String.t()) => list()}, series: [Macaw.Layers.Color.t(), ...], styles: %{optional(String.t()) => map() | list() | String.t()}, surface: Macaw.Layers.Color.t(), text: Macaw.Layers.Color.t(), title_size: number() }
Functions
The built-in theme of a name, "default", "dark", "color_safe" or "print", an atom
read as its string, or nil.
iex> Macaw.Layers.Theme.builtin(:color_safe).name
"color_safe"
iex> Macaw.Layers.Theme.builtin(:house)
nil
:ok, or {:error, subject, message} for the first ramp, color or palette entry of the
theme that breaks its contract, subject being {:ramp, name}, {:color, name} or
{:style, name} and message naming the term broken with the values measured.
iex> Macaw.Layers.Theme.check(Macaw.Layers.Theme.dark())
:ok
iex> status = Enum.map(~w(#c23238 #bd7407 #4ca34b), &Macaw.Layers.Color.parse!/1)
iex> theme = %{Macaw.Layers.Theme.default() | ramps: %{"status" => status}}
iex> {:error, {:ramp, "status"}, message} = Macaw.Layers.Theme.check(theme)
iex> message =~ "good (0) must be green or blue"
true
@spec check_color(term(), :roles | :open) :: :ok | {:error, [Macaw.Layers.Fault.t(), ...]}
A color value held to a profile (§4): under :roles a value with a literal color among
its leaves is {:literal_color, value} at []; under :open every color passes. A term
that is no color value is {:type, :color_value}, text :color_text, and a profile that
is neither {:enum, [:roles, :open]} at [:profile]. A builder's answer is checked as
its value.
Whether name is of the theme's color table, answered without building the list. A
name is its string, an atom read as its string.
iex> theme = Macaw.Layers.Theme.default()
iex> Enum.map([:red, "bad", :axis, "series_3", :steelblue, :series_99, :thick], &Macaw.Layers.Theme.color_name?(theme, &1))
[true, true, true, true, true, false, false]
Every name of the theme's color table, sorted: its color slots, its own and the default theme's colors, its extensions' and the CSS named colors.
iex> names = Macaw.Layers.Theme.color_names(Macaw.Layers.Theme.default())
iex> Enum.all?(~w(red amber bad axis series_3 steelblue), &(&1 in names))
true
@spec color_safe() :: t()
The color-vision-safe theme: default/0 with its status ramp blue → orange → red, which
survives the commonest color-vision deficiencies, in place of green → amber → red.
The color slots: the series, then the furniture, then the five roles.
@spec css_name(atom() | String.t()) :: {:ok, String.t()} | {:error, [Macaw.Layers.Fault.t(), ...]}
The custom-property name of a slot or a color name: --mw- and the name with _ as -.
A name is lower-case letters, digits and _, starting with a letter: {:ok, property},
any other {:type, :word} at [], so a stylesheet can never be broken out of through a
name.
iex> Macaw.Layers.Theme.css_name(:series_1)
{:ok, "--mw-series-1"}
@spec cue(String.t() | atom()) :: {:ok, %{glyph: atom(), dash: String.t() | nil}} | {:error, [Macaw.Layers.Fault.t(), ...]}
A role's cue besides its hue: its glyph and its dash (nil for solid), so a status reads
without its hue. The role by its name, an atom read as its string: {:ok, cue}, or
anything but a role as {:enum, roles} at [:role].
iex> Macaw.Layers.Theme.cue(:warning)
{:ok, %{glyph: :triangle, dash: "6 3"}}
@spec dark() :: t()
The dark theme: light text and axes on #1b1e24.
@spec data_color(t(), term()) :: {:ok, Macaw.Layers.Color.t()} | {:error, {:contrast, float()} | :unreadable}
A data color under the contrast guard (§4): {:ok, literal}, its literal color, where it
reaches 3:1 against the theme's background, {:error, {:contrast, ratio}} where it does
not, and {:error, :unreadable} for a term that is no color value or does not resolve,
text included.
@spec default() :: t()
The light theme: dark text and axes on white.
The contrast floors a theme offered to people holds against its own background: text
at least 4.5:1, axis and every series color at least 3:1, grid at least 1.2:1, and a
surface different from the grid. :ok, or {:error, faults}, each {slot, {:contrast, ratio, floor}}, the slot by its name, or {"surface", {:equal, "grid"}}.
@spec format(Macaw.Layers.Fault.t()) :: String.t()
A theme's fault as a person reads it, its path from the fields: the kernel's words
(Macaw.Layers.Fault.format/2), and a theme's own reasons.
iex> Macaw.Layers.Theme.format({[:axis], {:type, :color}})
~s|axis: must be a literal color, and text never is one: read it with Macaw.Layers.Color.parse/1, or write ~RGB"..."|
@spec ink(t(), Macaw.Layers.Color.t() | nil) :: {:ok, Macaw.Layers.Color.t()} | {:error, [Macaw.Layers.Fault.t(), ...]}
The contrast ink for a text drawn on under: the literal color of the theme's text or
background, whichever contrasts more (text on a tie), or black or white, whichever
contrasts more, when neither reaches 4.5:1. under is a literal %Macaw.Layers.Color{},
or nil for the theme's background: {:ok, ink}, or text as :color_text at [:under]
and any other term {:type, :color}. A slot that holds no literal color, in a theme built
by hand, is skipped.
iex> import Macaw.Layers.Color, only: [sigil_RGB: 2]
iex> theme = Macaw.Layers.Theme.default()
iex> for under <- [~RGB"#3b6fa8", nil, ~RGB"#777777"], {:ok, ink} = Macaw.Layers.Theme.ink(theme, under),
...> do: Macaw.Layers.Color.to_css(ink)
["#ffffff", "#333333", "#000000"]
@spec merge(t(), keyword() | map()) :: {:ok, t()} | {:error, [Macaw.Layers.Fault.t(), ...]}
The theme with the given fields replaced, ramps, colors, styles and defaults merged
key by key over its own: {:ok, theme}, or every fault, as new/1 judges them. A color
builder's answer (Macaw.Layers.Color.color/1 and the rest) stands for its value wherever
a field holds a color.
iex> {:ok, theme} = Macaw.Layers.Theme.new(name: :house, styles: %{muted: %{opacity: 0.4}})
iex> Macaw.Layers.Theme.style(theme, :muted)
{:ok, %{opacity: 0.4}}
iex> {:error, [{[:styles, "warning"], {:contract, message}} | _]} =
...> Macaw.Layers.Theme.new(name: :house, colors: %{warning: Macaw.Layers.Color.parse!("#f5c242")})
iex> message
~s|fill {:color, "warning"} is 1.65:1 against #ffffff; a role style's paint must reach 3:1 (WCAG 1.4.11, non-text contrast)|Names are strings (§2.1): a name given as an atom is its string, so a host's "info"
and the library's :info are one name, the one given winning; a name given both ways in
one map is {:duplicate, :name} at it.
iex> Macaw.Layers.Theme.new!(colors: %{"info" => Macaw.Layers.Color.parse!("#2f5d8a")})
...> |> Macaw.Layers.Theme.resolve(:info, :css)
{:ok, "var(--mw-info, #2f5d8a)"}
merge/2, or an ArgumentError naming every fault.
@spec new(keyword() | map()) :: {:ok, t()} | {:error, [Macaw.Layers.Fault.t(), ...]}
default/0 with the given fields replaced; ramps, colors, styles and defaults
merged key by key: {:ok, theme}, or every fault by path from the fields, judged as a
theme document's node is (§5), so a theme written in code and one read from a document
answer one way. The faults: an unknown field, :unknown_key; a series or furniture
color that is not a literal color, {:type, :color} (a string is never a color: read
text with Macaw.Layers.Color.parse/1, or write it in the source as ~RGB"#555555"); an
empty series, {:type, :colors}, and one too long, {:limit, :series, max, n}; a
field of the wrong shape; a name given both as its atom and its string,
{:duplicate, :name}; an extension that can't be held (extensions:, at
[:extensions, i | …]); untrusted text that is unsafe, {:unsafe, kind}; and each ramp,
color or palette entry that breaks its contract, {:contract, message} at [:ramps | :colors | :styles, name] (§2.6). format/1 words them.
iex> {:ok, theme} = Macaw.Layers.Theme.new(axis: Macaw.Layers.Color.parse!("#555555"))
iex> theme.axis
%Macaw.Layers.Color{r: 85.0, g: 85.0, b: 85.0, opacity: 1.0}
iex> Macaw.Layers.Theme.new(axis: "#555")
{:error, [{[:axis], {:type, :color}}]}
new/1, or an ArgumentError naming every fault: a theme written in code.
@spec print() :: t()
The print theme: paper. A white background and surface, near-black text and axes, a grid
dark enough to survive a photocopy, the color-safe status ramp, and role styles whose
fills are hatches of the role's color, so a grayscale copy keeps each role apart.
@spec ramp(t(), ramp_name(), number()) :: {:ok, Macaw.Layers.Color.t()} | {:error, [Macaw.Layers.Fault.t(), ...]}
The color at t along the theme's ramp name, as a literal color: the anchors spread
evenly over 0..1 and interpolated in CIE Lab, a position on an anchor the anchor's
literal, t clamped. A theme that lacks the ramp takes the default theme's, never a series
color.
iex> Macaw.Layers.Theme.ramp(Macaw.Layers.Theme.default(), :thermal, 0.25)
{:ok, %Macaw.Layers.Color{r: 141.0, g: 165.0, b: 203.0, opacity: 1.0}}The faults: a ramp the theme doesn't have, {:unknown_ramp, name} at [:name]; a
position that is no number, {:type, :number} at [:t]; and a ramp whose anchors are not
all literal colors (a theme built by hand), {:unresolved_ramp, name} at [:name].
@spec ramp_names() :: [String.t(), ...]
The four ramps whose meaning the library fixes, by name.
iex> Macaw.Layers.Theme.ramp_names()
["status", "thermal", "diverging", "sequential"]
@spec resolve(t(), slot() | ramp_position(), mode()) :: {:ok, Macaw.Layers.Color.t() | String.t() | number()} | {:error, [Macaw.Layers.Fault.t(), ...]}
The slot's value: the stored literal, or a CSS custom-property reference that falls back
to its CSS text. A color is a literal %Macaw.Layers.Color{} under :literal; sizes are
numbers under :literal and gain px under :css. A ramp position is its literal in
both modes, as CSS text under :css, except where a status role stands, {:ramp, "status", 0 | 0.5 | 1}, which resolves as the role while the table holds the role there.
A name, of a slot, a color or a ramp, is its string, an atom read as its string.
{:ok, value}, or the faults: a name that is no slot or color of the theme, a series
slot beyond the palette among them, {:unknown_slot, name} at []; a name whose chain
reaches no literal (a theme built by hand), {:unresolved_color, name}; a ramp
position's faults as ramp/3 gives them; a series index that is no positive integer,
{:type, :pos_integer} at [:i]; a term that is no slot, {:type, :slot}; and a mode
that is neither, {:enum, [:literal, :css]} at [:mode].
@spec role_names() :: [String.t(), ...]
The five roles: the status ramp's three fixed points, then "info" and "neutral".
@spec series_slot(t(), pos_integer()) :: String.t()
The "series_k" slot the positive index i cycles to over the theme's series.
iex> Macaw.Layers.Theme.series_slot(Macaw.Layers.Theme.default(), 11)
{:ok, "series_1"}
The theme's slot names: "series_1" to "series_n", then the fixed slots.
iex> Macaw.Layers.Theme.new!(series: [Macaw.Layers.Color.parse!("#3b6fa8"), Macaw.Layers.Color.parse!("#d9730d")])
...> |> Macaw.Layers.Theme.slots()
...> |> Enum.take(4)
["series_1", "series_2", "axis", "grid"]
@spec style(t(), style_name()) :: {:ok, map()} | {:error, [Macaw.Layers.Fault.t(), ...]}
The palette entry name as one style node in its parts: the theme's own, the default
theme's entry whole where the theme lacks it, or an extension's default. {:style, i}
cycles over the style series; in a role's entry :cue becomes the role's dash and glyph,
a solid dash leaving the key out. {:ok, style}, or a name not of the palette as
{:unknown_style, name} at [], and anything that is neither a name nor {:style, i},
i a positive integer, as {:type, :style_name}.
iex> Macaw.Layers.Theme.style(Macaw.Layers.Theme.default(), :warning)
{:ok, %{fill: %{type: :solid, color: {:color, "warning"}}, stroke: %{type: :solid, color: {:color, "warning"}, dash: "6 3"}, marker: %{shape: :triangle}}}
iex> Macaw.Layers.Theme.style(Macaw.Layers.Theme.default(), :muted)
{:ok, %{opacity: 0.25}}
The theme's palette names: its style series, the default's ten when it has none of its own, then the roles, the states, the furniture and the modifiers, then its extensions'.
Every ramp, color and palette entry of the theme that breaks its contract, as
{subject, message} in check/1's order, each contract run alone.