Macaw.Layers.Theme (macaw_layers v0.2.2)

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;
:css - a custom-property reference with the literal as its fallback, var(--mw-axis, #666666), so a stylesheet can override it from any ancestor.

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)
"var(--mw-axis, #666666)"
iex> Macaw.Layers.Theme.resolve(Macaw.Layers.Theme.dark(), {:series, 11}, :literal)
"#7fb3e6"
iex> Macaw.Layers.Theme.resolve(Macaw.Layers.Theme.default(), :warning, :literal)
"#bd7407"
iex> Macaw.Layers.Theme.resolve(Macaw.Layers.Theme.default(), {:ramp, :status, 0.5}, :css)
"var(--mw-warning, #bd7407)"

Ported from visualize's Visualize.Theme.

Summary

Types

mode()

How a slot renders: a CSS reference with its fallback, or the stored value.

ramp_name()

One of the four ramps whose meaning the library fixes (§2.3).

ramp_position()

A position along a ramp: t in 0..1, clamped.

slot()

A slot name, or {:series, i} for the i-th series color, cycling.

style_name()

A name of the style palette, or {:style, i} for the i-th style series entry.

t()

Functions

builtin(name)

The built-in theme of a name, :default, :dark, :color_safe or :print, by either spelling, or nil.

check(theme)

: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.

check_color(value, profile)

A color value held to a profile (§4): under :roles a value with a literal string among its leaves is {:error, {:literal_color, value}}; under :open every color passes.

color_name?(theme, name)

Whether name is of the theme's color table, answered without building the list.

color_names(theme)

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.

color_safe()

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.

color_slots(theme)

The color slots: the series, then the furniture, then the five roles.

css_name(name)

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; any other raises ArgumentError, so a stylesheet can never be broken out of through a name.

cue(role)

A role's cue besides its hue: its glyph and its dash (nil for solid), so a status reads without its hue. Raises ArgumentError for anything but a role.

dark()

The dark theme: light text and axes on #1b1e24.

data_color(theme, value)

A data color under the contrast guard (§4): {:ok, literal} where it reaches 3:1 against the theme's background, {:error, {:contrast, ratio}} where it does not, and {:error, :unreadable} for a value that does not resolve.

default()

The light theme: dark text and axes on white.

floors(theme)

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}} or {:surface, {:equal, :grid}}.

ink(theme, under)

The contrast ink for a text drawn on under: the literal of the theme's text or background, whichever contrasts more (text on a tie), or #000000/#ffffff, whichever contrasts more, when neither reaches 4.5:1. under is a color string, a %Macaw.Layers.Color{}, or nil for the theme's background; an unreadable string is nil, and a slot whose own value does not parse is skipped.

merge(theme, fields)

The theme with the given fields replaced, ramps, colors, styles and defaults merged key by key over its own; the checks of new/1 apply.

new(fields)

default/0 with the given fields replaced; ramps, colors, styles and defaults merged key by key. An unknown field raises KeyError; an empty series, or a ramp, color or palette entry that breaks its contract, raises ArgumentError (§2.6).

print()

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.

ramp(theme, name, t)

The color at t along the theme's ramp name, as a literal: the anchors spread evenly over 0..1 and interpolated in CIE Lab, a position on an anchor the anchor as written, t clamped. A theme that lacks the ramp takes the default theme's, never a series color.

ramp_names()

The four ramps whose meaning the library fixes.

resolve(theme, slot, mode)

The slot's value: the stored literal, or a CSS custom-property reference that falls back to it. Sizes are numbers under :literal and gain px under :css. A ramp position is its literal in both modes, except where a status role stands, {:ramp, :status, 0 | 0.5 | 1}, which resolves as the role while the table holds the role there. An unknown name, or a series slot beyond the palette, raises ArgumentError.

role_names()

The five roles: the status ramp's three fixed points, then :info and :neutral.

series_slot(theme, i)

The :series_k slot the positive index i cycles to over the theme's series.

slots(theme)

The theme's slot names: :series_1 to :series_n, then the fixed slots.

style(theme, name)

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. Any other name raises ArgumentError.

style_names(theme)

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'.

violations(theme)

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.