Lens Design System
A code-truthful spec for a cross-browser accessibility extension. The palette is warm parchment + forest green — low-contrast fatigue at the system level. The typeface is Atkinson Hyperlegible, designed by the Braille Institute for readers with low vision. Every token maps to a real value in src/tokens.css and the live site CSS; when code and this doc disagree, code wins.
The extension that knows you.
Lens is a profile that travels with you. Three principles hold the design together — break any one and it stops feeling trustworthy.
Forest green on warm parchment. Never cold white.
The palette reduces eye strain at the system level: warm parchment replaces harsh white; near-black ink replaces pure black; forest green communicates trust without the clinical coldness of a standard blue primary.
Backgrounds — warm parchment
Text — near-black scale
Brand — forest green family
Atkinson Hyperlegible — the accessible choice is the right choice.
Designed by the Braille Institute specifically for readers with low vision. Exaggerated letterform distinctions — I vs l vs 1, O vs 0 — reduce misreads without looking clinical. It's the only typeface that earns a spot in an accessibility product on merit, not aesthetics. JetBrains Mono appears only on system-flavoured labels.
A 4 px base scale.
Eight steps, doubling loosely from 4 px to 96 px section rhythm. Mirrors the --lens-space-* tokens in the shipped src/tokens.css.
Soft but not ambiguous — corners stay legible.
Four steps from pill to chip. Soft enough to reduce visual sharpness on high-contrast displays; distinct enough that buttons and cards keep their shape.
Shadows are near-black alpha — never grey, never blue.
On a warm parchment canvas, grey shadows read as clashing cool tones. Near-black alpha (--shadow-rgb: 20, 20, 19) keeps every surface feeling like it belongs on the same warm page.
The popup, buttons, and filter badges.
Key components rendered on the parchment stage — what a user sees when they click the Lens toolbar icon.
Buttons
Extension popup
Color-blindness filter badges (8 supported)
Motion that explains what happened, nothing more.
Short, purposeful, never decorative. With prefers-reduced-motion on, every animation here collapses to a plain opacity fade — a hard requirement for a product used by people with vestibular disorders.
Plain, calm, honest. No medical language.
The copy respects the user without medicalising them. "Adapted for your reading profile" rather than "disability accommodation." Straightforward, lowercase-comfortable, and clear about what Lens is and isn't doing.
"Adapted for your reading profile."
"Lens is paused here for your safety."
"Show original" — not "disable Lens"
"Accessibility mode enabled."
"Disability settings applied."
"Warning: this page may not be accessible."
Five ways to break the trust.
If a new screen does any of these, it isn't Lens anymore.
- Don't use a pure-white background. #ffffff creates the eye strain Lens was built to reduce. Always use the warm parchment canvas.
- Don't use grey shadows. All shadows use near-black alpha. Grey turns the warm canvas cold.
- Don't substitute another typeface for the extension UI. Atkinson Hyperlegible is non-negotiable for Lens's own chrome. The user's reading view is a different matter — they may choose their font.
- Don't send content to the backend passively. Adaptation only runs on explicit user action. No background scanning, no passive observation, no "improving the experience" data collection.
- Don't adapt sensitive domains by default. The hardcoded block list exists for a reason. No new feature should silently override it.
Where every token actually lives.
This page documents the system; the shipped CSS defines it. When they disagree, code wins.