Chapter 08
Accessibility
Inkwell is quiet, and quiet can be hard to read. This chapter reports the real contrast of its colours, including the pairs that fall short, and the rules that keep the rest usable.
Built with
- WCAG 2 contrast
- prefers-reduced-motion
- Focus
Numbers, not adjectives
Measured contrast.
Every ratio below is computed when the site is built, from the colours in globals.css. Nothing is typed by hand, so the table cannot say a pair passes after someone changes a colour.
The yardsticks are WCAG 2: 4.5:1 for body text (level AA), 7:1 for the stricter AAA, and 3:1 for large text and interface parts such as icons and borders.
| Text on surface | Used for | Light | Dark |
|---|---|---|---|
| foreground on background | Body text on the page | 14.34:1AAA | 15.85:1AAA |
| foreground on background-elevated | Text inside cards | 13.95:1AAA | 14.92:1AAA |
| foreground on background-surface | Text in inset wells | 12.60:1AAA | 13.90:1AAA |
| foreground-muted on background | Supporting copy | 6.60:1AA | 8.66:1AAA |
| foreground-muted on background-elevated | Supporting copy in cards | 6.42:1AA | 8.15:1AAA |
| foreground-subtle on background | Labels and metadata | 4.54:1AA | 4.69:1AA |
| foreground-subtle on background-elevated | Labels and metadata in cards | 4.42:1Large text and UI only | 4.41:1Large text and UI only |
| primary on background | Links, focus rings, violet text | 3.83:1Large text and UI only | 7.44:1AAA |
| primary on background-elevated | Violet text in cards | 3.73:1Large text and UI only | 7.00:1AAA |
| accent-warm on background | The accent spark | 2.53:1Below 3:1 | 12.03:1AAA |
| success on background | Success messages | 4.17:1Large text and UI only | 7.12:1AAA |
| error on background | Error messages | 4.94:1AA | 5.69:1AA |
| background on primary | Text on a violet button | 3.83:1Large text and UI only | 7.44:1AAA |
Honest findings
Where it falls short.
5 of the 12 pairs above do not reach 4.5:1 in at least one theme. They are marked in the table. Most are accents or secondary text rather than body copy. The one to watch is the subtle grey used for small labels: it sits right at the line, and small labels count as small text. Each gap has a rule below, but they are real, and a design system that hid them would not be worth trusting.
foreground-subtle on background-elevated
Labels and metadata in cards. Light 4.42:1, dark 4.41:1.
primary on background
Links, focus rings, violet text. Light 3.83:1, dark 7.44:1.
primary on background-elevated
Violet text in cards. Light 3.73:1, dark 7.00:1.
accent-warm on background
The accent spark. Light 2.53:1, dark 12.03:1.
success on background
Success messages. Light 4.17:1, dark 7.12:1.
What to do about them: keep violet text to headings, links and interface parts in the light theme, never small body copy. Treat accent-warm as decoration, never as the only carrier of meaning. Do not pair success green with small text without an icon or a word beside it. Changing a token to fix a pair is a design decision, so it belongs in globals.css, then in this table.
Hands and thumbs
Touch and phones.
On touch screens the learn guides give every control at least 2.5rem (40px) of height, and a short chip gets extra padding, because a chip that looks fine is often hard to hit. Text inputs are 16px on phones, because anything smaller makes iOS zoom the page when the box is focused. And a phone never scrolls sideways: code wraps, tables become stacked labelled cards, and tab rows wrap onto more lines.
@media (pointer: coarse), (max-width: 640px) { .pega-app main :is(button, summary, select, [role='tab'], [role='radio']):not(.sr-only) { min-height: 2.5rem; }}Movement and the keyboard
Motion and focus.
Entrances and the doodle animations have a prefers-reduced-motion fallback in globals.css. A person who asks their device for less motion gets the end state with no travel.
The guide search dialog is the reference for keyboard behaviour. Ctrl or Cmd plus K opens it, and so does / when you are not typing in a field. It is marked as a modal dialog, arrow keys move through the results, Enter opens one, Escape closes it, Tab stays inside it, and focus returns to the control that opened it.
For every new thing
Rules to follow.
- Check any new text and surface pair against the table before you ship it. Aim for 4.5:1 for body text.
- Never carry meaning by colour alone. Add a word or an icon.
- Give anything that loops or travels a reduced-motion fallback.
- Make controls at least 40px tall on touch, and inputs at least 16px.
- A dialog traps focus, closes on Escape and returns focus when it closes.
- Never let a phone scroll sideways.