Reading profiles

From Zacess main at 2bc7be2. Edit this page on GitHub

A reading profile is how a person wants every document laid out. It lives in crates/zacess-core/src/profile.rs.

Rules

  • Applying a profile never alters the document. A profile is applied as a read-only view that borrows the document, so the original stays exactly as imported.
  • Profiles never change silently. Any adaptation is offered as a list of setting changes, each with its old and new value, for the person to accept or refuse.
  • Every contrast theme meets WCAG AAA (7:1) for body text, links and highlighted low-confidence text. A unit test checks each one.

Presets

Preset Font Size Line spacing Letter spacing Line length Theme Extras
Low Vision Atkinson Hyperlegible 24 pt 1.6 0.02 em 45 characters Yellow on black Extra large cursor, reading ruler
Dyslexia-Friendly Lexend 16 pt 1.75 0.12 em 60 characters Black on cream Large cursor, two-line reading ruler
Reduced Visual Clutter System 14 pt 1.5 None 65 characters Dark on light Decoration hidden
Screen Reader System 14 pt 1.5 None 70 characters Dark on light Decoration hidden, no ruler

Every preset uses one column and no motion. A preset is a starting point: it can be saved under a new name and changed.

Saving and exporting

Profiles are saved one JSON file per profile. Names are unique, ignoring case, spacing and punctuation. A profile can be created, updated, renamed, deleted, exported to a standalone file and imported again. An exported file is the JSON form below, so it can be shared or kept as a backup.

JSON form

An example is in examples/profile.json. A unit test parses that file.

Field Type Meaning
schema_version integer The version of this JSON form, currently 1. Versioning follows the document model rules
name string The profile name shown to the person
font.family string A font family name. Empty means the system font
font.fallback string sans_serif, serif or monospace, used when the font is not installed
font_size_pt number Body text size in points, 6 to 96
line_spacing number Line height as a multiple of the font size, 1 to 3
paragraph_spacing number Space after each paragraph in multiples of the font size, 0 to 5
character_spacing number Extra space between letters in multiples of the font size, 0 to 0.5
column_width integer The longest line in average character widths, 20 to 150
contrast string dark_on_light, light_on_dark, yellow_on_black, black_on_cream, high_contrast_dark, high_contrast_light, deep_contrast_dark or deep_contrast_light
cursor_size string standard, large (twice the system size) or extra_large (three times)
reading_ruler.enabled boolean Whether a band follows the line being read
reading_ruler.position number Where the band sits, from 0 (top of the view) to 1 (bottom)
reading_ruler.lines integer How many lines the band covers, 1 to 5
single_column boolean One column with nothing side by side. true when missing
reduce_motion boolean No animation or moving content. true when missing
hide_decoration boolean Hide decorative images and borders that carry no meaning. false when missing

Contrast themes

Theme Text Background Contrast
dark_on_light #111111 #ffffff 18.9:1
light_on_dark #f5f5f5 #121212 17.2:1
yellow_on_black #ffeb3b #000000 17.2:1
black_on_cream #000000 #fdf6e3 19.5:1
high_contrast_dark #ffffff #000000 21:1
high_contrast_light #000000 #ffffff 21:1
deep_contrast_dark #ffffff #000000 21:1
deep_contrast_light #000000 #ffffff 21:1

The two high contrast themes match the High Contrast Dark and High Contrast Light code themes. They take the code themes' link and focus colours, use the selection colour for the reading ruler and use the other theme's warning colour behind low-confidence text. Adding them changed none of the original four ids, so a profile saved before them loads unchanged. A unit test reads every id back.

The two deep contrast themes match the Deep Contrast Dark and Deep Contrast Light code themes, with a yellow focus ring on the dark one and a red focus ring on the light one. Their links are a shade lighter on the dark theme and a shade darker on the light one so they keep 7:1 on the reading ruler and the low-confidence background as well as the page. They come after the high contrast themes, so every earlier id keeps its meaning.

Every colour in each theme

Contrast is measured with the WCAG 2.2 relative luminance formula (contrast_ratio in profile.rs), against the theme's background unless the column says otherwise.

Theme Link Low-confidence background (text on it) Focus ring Reading ruler (text on it)
dark_on_light #0b3d91, 10.0:1 #ffe58a, 15.1:1 #0b3d91, 10.0:1 #dbe7ff, 15.2:1
light_on_dark #9cc4ff, 10.5:1 #5c4300, 8.5:1 #9cc4ff, 10.5:1 #24324a, 11.8:1
yellow_on_black #8fd3ff, 12.9:1 #4a2a00, 10.6:1 #ffffff, 21:1 #2a2a2a, 11.8:1
black_on_cream #003a8c, 9.8:1 #ffd27a, 14.8:1 #003a8c, 9.8:1 #efe3c0, 16.4:1
high_contrast_dark #8fd0ff, 12.6:1 #5a3a00, 10.3:1 #f5c400, 12.8:1 #0a2552, 15.0:1
high_contrast_light #003d99, 9.9:1 #ffd28a, 14.8:1 #003d99, 9.9:1 #fff1a0, 18.3:1
deep_contrast_dark #6bceff, 11.9:1 #403300, 12.4:1 #ffff00, 19.6:1 #1c1c38, 16.5:1
deep_contrast_light #0037df, 8.0:1 #fff1a0, 18.3:1 #b5200d, 6.6:1 #e8f0ff, 18.3:1

Low-confidence text also carries a dotted underline and the focus ring is an outline, so neither rests on colour alone. In the high and deep contrast themes the low-confidence background, the focus ring and the ruler are three different colours. Links keep at least 7:1 on the ruler and, in the deep contrast themes, on the low-confidence background too. Unit tests check all of this.