Writing a profile
From Zacess Profile v0.2.2. Edit this page on GitHub
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. This page is a guide to writing one. The full rules are in the profile format, spec version 1, which is a draft.
The file
A profile is a TOML 1.0 file in UTF-8, usually named with .toml.
The JSON Schema
(draft 2020-12) describes the same structure, so an app may also store a profile as JSON and
validate it against the schema. zprf itself reads and writes TOML only.
Two fields are required. spec_version is 1 and name is the name shown to the person.
The smallest useful profile states a need and nothing else:
spec_version = 1
name = "Large text, no motion"
[needs]
reduce_motion = true
[needs.font]
size_pt = 18Unknown fields are errors. A misspelt need such as reduse_motion is refused rather than
silently dropped.
The top level
| Field | Meaning |
|---|---|
spec_version |
The spec version the profile follows: 1 |
name |
The name shown to the person, on one line |
id |
Optional. Lowercase letters and digits joined by single dashes, used to name the rendered files. When missing it is made from the name |
description |
Optional. One sentence on who the profile is for |
appearance |
Optional. dark or light. When missing it is worked out from the background |
Needs
Every need is optional. A missing need means the person has none there, so each app keeps its own
setting. The one exception is reduce_motion, which is true unless the profile turns it off,
because animation can be a barrier and its absence rarely is.
| Field | Takes | What it asks for |
|---|---|---|
contrast |
a table | The floors every colour is held to. See what is checked |
font.family |
a font name | The font. Empty or missing leaves each app on its own |
font.fallback |
sans_serif, serif or monospace |
The generic family when the font is not installed |
font.size_pt |
6 to 96 | Text size in points |
reduce_motion |
true or false |
No blinking cursors, animation, smooth scrolling or flashing bells |
cursor_size |
standard, large or extra_large |
Large and extra large ask for a block cursor |
focus_ring_width_px |
1 to 10 | The width of the keyboard focus outline |
line_spacing |
1 to 3 | Line height as a multiple of the font size |
character_spacing |
0 to 0.5 | Extra space between letters as a fraction of the font size |
column_width |
20 to 150 | The longest comfortable line in characters, shown as a ruler |
single_column |
true or false |
One column with nothing side by side |
hide_decoration |
true or false |
No decorative images and borders that carry no meaning |
Each app applies the needs it has a setting for. The accessibility statement lists every need per app, including where an app has no setting.
Colours
Every colour is optional and written as #rrggbb. A colour you set is never changed. A colour you
leave out is derived: zprf derive and zprf check solve it in OKLCH to meet the profile's own
floors. The colours sit in three tables.
[palette]holds the interface colours:background,foreground,surface,surface_alt,muted,border,accent,accent_foreground,link,focus_ring,cursor,cursor_text, the three selection colours,line_highlightanderror,warningandinfo.[palette.syntax]holds the syntax colours, each with a font style that writers apply so no role rests on colour alone: bold keywords, control flow and tags, italic parameters and comments and underlined invalid code.[palette.terminal]holds the sixteen ANSI colours inansi, withdimandbackground_slotsnaming slots that are measured differently.
surface_alt is the one colour that is never derived. When it is missing it takes the value of
surface and adds no pairs. The colour vision checks page says
what changes when it is set.
Start from needs, finish with colours
Write the needs and any colour you care about, then let derive fill in the rest:
zprf derive mine.toml --out complete.toml
zprf check complete.tomlEach colour derive chose is marked # derived in the file it writes, so your choices stay apart
from the tool's. Starting from one of the starter profiles
works too: every colour is already set and checked.
Versions of the format
The format is versioned apart from the tool. A new optional field that keeps every existing
profile valid does not raise spec_version. Removing or renaming a field, changing a default or
changing a pair or a floor raises it. While version 1 is a draft, a pair or a floor may still be
added to it, so a profile that passed before can fail check after an update and name the new
pair.