Profile format

From Zacess Profile v1.0.0. Edit this page on GitHub

Spec version 1, draft. This document is versioned apart from zprf, the reference tool in the zacess-profile crate. The tool's version is in Cargo.toml and its changes are in CHANGELOG.md. A change to what a valid profile is raises the spec version, as does a change to what a field means.

The machine-readable form is profile.schema.json, a JSON Schema (draft 2020-12). Where this document and the schema differ, the schema is a bug and this document wins.

Purpose

A profile records what a person needs to read a screen comfortably: contrast floors, a font and size, spacing, cursor size and freedom from motion. It may also carry colours. An app that reads a profile applies the needs it can and leaves the rest alone. A tool that writes colours for an app must not write any pair that falls below the profile's floors.

File format

A profile is a TOML 1.0 file encoded as UTF-8. The conventional file extension is .toml. The schema describes the same structure as JSON, so an app may store or send a profile as JSON and validate it against the schema. zprf itself reads and writes TOML only.

Unknown fields are errors. A reader must refuse a profile with a field it does not know, rather than ignore it, so that a misspelt need such as reduse_motion is never silently dropped.

A reader must refuse a profile whose spec_version is newer than the newest version it supports.

Top level

Field Type Required Meaning
spec_version integer yes The spec version the profile follows. 1 for this document
name string yes The name shown to the person. One line: it must hold at least one character that is not white space and no control characters (U+0000 to U+001F and U+007F to U+009F). When id is missing it must also hold an ASCII letter or digit, since the file names come from it
id string no Lowercase ASCII letters and digits joined by single dashes, matching ^[a-z0-9]+(-[a-z0-9]+)*$, used to name files. When missing, it is the name in lowercase with every run of other characters replaced by one dash
description string no One sentence on who the profile is for
appearance dark or light no Whether the background is dark or light. When missing, it is worked out from the background: dark when white has more contrast with it than black does. A profile whose appearance disagrees with its background is invalid
needs table no See Needs
palette table no See Palette

Needs

Every field is optional. A missing field means the person has no need there, so an app keeps its own setting, except where a default is given.

Field Type Default Meaning
contrast table see below The floors in Contrast
font.family string none A font family name with no double quotes, backslashes or control characters, since writers place it inside quoted strings. Empty or missing leaves each app on its own font
font.fallback sans_serif, serif or monospace none The generic family to use when the font is not installed
font.size_pt number, 6 to 96 none Text size in points. An app that sizes text in CSS pixels uses four thirds of this value
reduce_motion boolean true No blinking cursors, animation, smooth scrolling or flashing bells
cursor_size standard, large or extra_large none Large and extra large ask for a block cursor. Where only a bar is offered, the bar is two or three times the standard width
focus_ring_width_px integer, 1 to 10 none The width of the keyboard focus outline in CSS pixels, for apps that can set it
line_spacing number, 1 to 3 none Line height as a multiple of the font size
character_spacing number, 0 to 0.5 none Extra space between letters as a fraction of the font size
column_width integer, 20 to 150 none The longest comfortable line in characters. Editors show it as a ruler
single_column boolean none One column with nothing side by side. For apps with a layout to change
hide_decoration boolean none Hide decorative images and borders that carry no meaning. For apps with decoration to hide

reduce_motion defaults to true because animation can be a barrier and its absence rarely is.

Contrast

Ratios use the WCAG 2.2 definitions of relative luminance and contrast ratio, from 1 to 21. A pair passes when its unrounded ratio is at least the floor. A reader that prints a ratio should round it down, so a printed figure never overstates the real one.

Field Default Applies to
text 7.0 Text, the accent and syntax colours on the background and on panels. The cursor on the background, the character under a block cursor, selected text on the selection block, text on the accent and the default text over the current line and a soft selection. The default text on a terminal slot used as a fill
non_text 3.0 Borders and the focus ring on the background and on panels. The selection block against the background
overlay 4.5 Syntax colours over the current line and over a soft selection. Interface text and the accent over the current line
terminal 7.0 Each of the sixteen terminal colours on the background
terminal_dim 4.5 Terminal slots listed in palette.terminal.dim
highlight_distance 0.08 The OKLab distance from the background to the current line and to a soft selection, so neither disappears
colour_vision_distance 0.04 The OKLab distance between two paired colours as a person with protanopia, deuteranopia or tritanopia sees them
tone_difference 0.05 The difference in tone between two paired colours. Tone is the cube root of relative luminance, the OKLab lightness of the grey with the same luminance, which is all a viewer with no colour vision has to go on
check_error_warning true Whether error and warning are held to the paired colour floors as a pair. The Zacess themes do not pair them, so false keeps a themes palette as it is
apca none When set, an APCA Lc floor (absolute value, APCA-W3 0.0.98G-4g) for the default text and every syntax colour on the background, on top of the WCAG ratio

The defaults are WCAG 2.2 AAA for text (success criterion 1.4.6) and the WCAG 2.2 floor for non-text contrast (success criterion 1.4.11).

Palette

Every colour is a string in the form #rrggbb, in sRGB. Every colour is optional. A colour that is missing is derived (see Derivation) and a colour that is present is never changed. The one exception is surface_alt, which is never derived: when it is missing it takes the value of surface wherever it is drawn and adds no pairs.

Interface colours

These sit directly in the [palette] table.

Field Meaning
background The main background every other colour is measured on
foreground Default text
surface Panels, bars, sidebars and floating windows
surface_alt The second panel colour, for apps that draw two: activity and status bars, inactive tabs and list rows. Optional. Falls back to surface when missing
muted Secondary text such as line numbers and descriptions
border Borders and dividers
accent The one accent: the active tab, the current search match and buttons
accent_foreground Text drawn on the accent
link Links
focus_ring The outline that shows keyboard focus
cursor The text cursor
cursor_text The character under a block cursor
selection_background The selection block, where selected text takes one colour
selection_foreground Selected text on the selection block
selection_soft A background-only selection, where selected text keeps its own colours
line_highlight The band behind the current line
error, warning, info Message text

Syntax colours

These sit in [palette.syntax]. Each role has a font style that a writer of an editor theme should apply, so that no role is told apart by colour alone.

Field Style Meaning
keyword bold Declarations and other keywords such as const, class and fn
control bold Control flow such as if, return, for and import
function Function and method names
type Types, classes, interfaces and enums
variable Variables and identifiers
parameter italic Function parameters
property Object properties, fields and keys
string Strings and characters
number Numbers, booleans and other constants
comment italic Comments, held to the same floor as code
operator Operators and punctuation
tag bold Markup tags
attribute Markup attributes
regex Regular expressions and escapes
invalid underline Invalid code
added, removed, changed Lines in a diff

Terminal colours

These sit in [palette.terminal].

Field Type Meaning
ansi array of exactly 16 colours Slots 0 to 7 are black, red, green, yellow, blue, magenta, cyan and white. Slots 8 to 15 are their bright forms
dim array of slot numbers Slots checked at needs.contrast.terminal_dim rather than needs.contrast.terminal
background_slots array of slot numbers Slots that programs use as a fill behind text, such as black on a dark terminal. They are checked as a fill under the default text instead of as text

Pairs

A checker measures every pair below and compares it with the floor named. A profile passes only when every pair passes. A writer of app config should draw only these pairs, so that a palette that passes is readable everywhere it is written.

A pair on surface_alt is measured only when the profile sets it. When it is missing, those pairs are the pairs on surface, which are measured already.

Foreground On Floor
foreground background, surface, surface_alt, line_highlight and selection_soft text
muted, link, error, warning, info and accent background, surface and surface_alt text
muted, link, error, warning, info and accent line_highlight overlay
cursor background text
cursor_text cursor text
selection_foreground selection_background text
accent_foreground accent text
border and focus_ring background, surface and surface_alt non_text
selection_background background non_text
every syntax colour background, surface and surface_alt text
every syntax colour line_highlight and selection_soft overlay
each terminal slot not in background_slots background terminal (terminal_dim for slots in dim)
foreground each terminal slot in background_slots text
line_highlight and selection_soft background, as an OKLab distance highlight_distance
foreground and every syntax colour background, as APCA Lc, only when apca is set apca
each pair in Paired colours each other, as a tone difference tone_difference
each pair in Paired colours each other, as an OKLab distance under each of the three simulations colour_vision_distance

Paired colours

Some roles are drawn next to each other and are told apart by colour, so they must also stay apart for a person with a colour vision deficiency. Each pair below is checked for a tone difference of at least tone_difference and an OKLab distance of at least colour_vision_distance under each of protanopia, deuteranopia and tritanopia. A simulation applies the Machado, Oliveira and Fernandes (2009) matrix at full severity to linear sRGB, clamps each channel to the gamut and rounds the result to 8 bit sRGB before it is measured.

A pair marked always is checked whatever the font styles of its roles, because its colours are often red and green. Every other pair is checked only when both roles share a font style from Syntax colours, since a difference in style already tells them apart.

Pair Checked
keyword and function, keyword and type, keyword and variable same style
control and keyword, control and variable, control and function same style
function and variable, function and type, function and property, function and string same style
type and variable, type and property same style
variable and property, variable and parameter same style
parameter and type, parameter and property same style
property and string, string and comment same style
number and variable, number and operator same style
comment and variable, invalid and variable same style
tag and attribute, attribute and string same style
string and number, string and regex, string and invalid always
added and removed, added and changed, removed and changed always
error and warning always, unless check_error_warning is false

The syntax pairs are the pairs the Zacess themes check, with the same floors.

Derivation

A tool that completes a profile must keep every colour the profile sets. When no colour can meet a floor, for example a text floor of 18:1 on a mid grey, it must fail and say which colour and floor could not be met. It must never hand back a derived colour that fails against the background or against another derived colour. A pair that fails because of a colour the profile sets, such as a comment colour that is too dim, is reported as that pair failing.

zprf derives colours in OKLCH. Each role has a fixed hue. Lightness moves away from the background until the floor is met with a small margin on every surface the colour is drawn on, surface_alt included when it is set. When an APCA floor is set the colour must meet that as well. Chroma is reduced where needed to stay inside the sRGB gamut. Before handing a profile back it checks every pair a derived colour takes part in and stops on any failure the rule above puts on a derived colour, naming the colour and the floor. The exact colours it chooses are not part of this spec and may change between tool versions. The guarantee that they pass is.

Every role solved this way starts at the same floor and so at the same tone, which paired colours must not share. zprf then places the derived syntax colours and the derived error and warning one at a time, each at the nearest lightness on its own hue where it meets its floors and stays apart from every role placed before it. Colours the profile sets are placed first and never move. When the band of lightness above the floors is too narrow for every pair, derivation fails and names the pair.

Relation to the Zacess reading profile

The Zacess reader keeps its own reading profiles in JSON. The fields this spec shares with it keep their meaning.

Reading profile This spec
font.family and font.fallback needs.font.family and needs.font.fallback
font_size_pt needs.font.size_pt
line_spacing, character_spacing and column_width the same names in needs
cursor_size, single_column, reduce_motion and hide_decoration the same names in needs
contrast (a theme id) a starter profile in profiles/, such as zacess-yellow-on-black
paragraph_spacing and reading_ruler not in spec version 1

Example

examples/minimal.toml states needs and one colour. The starter profiles in profiles are complete examples with every colour set.

spec_version = 1
name = "Large text, no motion"

[needs]
reduce_motion = true

[needs.font]
size_pt = 18

Versioning

  • A new optional field with a default that keeps every existing profile valid and unchanged in meaning is a minor change to this document. It does not raise spec_version.
  • Removing a field, renaming one, changing a default or changing a pair or a floor raises spec_version.
  • Readers must accept every spec version up to the newest one they support.
  • While spec version 1 is a draft, a pair or a floor may still be added to it, as the paired colours were. A profile that passed before such a change can then fail check and name the new pair. Marking version 1 final freezes its pairs and floors under the rules above.