Try the Sample Commands
Explore recorded sample responses in this browser demo. Choose a command or type 'help' to see what’s available.
The problem
Most web applications choose typography for brand or minimalism, which usually means geometric grotesque sans-serifs. Those crowd letters together and make mirrored characters easy to confuse. For readers with dyslexia, letters like b, d, p, and q look like rotations of each other, which leads to fatigue, reversals and stalls while reading.
The personal context: My brother was diagnosed with dyslexia early in life. Watching him use the web, with its ultra-thin fonts, cramped line heights and layout shifts, made the friction hard to miss. I wanted this site's typography chosen for legibility first.
Quantitative performance targets: Zero Cumulative Layout Shift (CLS = 0.000) across typography switches; sub-5ms Pretext canvas recalculation overhead; strict WCAG 2.1 Level AA contrast conformance (>= 7:1 for body copy); and 100% client-side persistence without layout flash (FOUT).
How it works
The site uses three typefaces, each for a different kind of text:
- Headings use Lexend, which educational researchers designed to reduce visual stress and speed up reading with wider letter-spacing and distinct glyph shapes.
- Prose and UI use Atkinson Hyperlegible, which the Braille Institute commissioned for low-vision readers. It gives easily confused characters distinct forms, such as uppercase 'I', lowercase 'l' and the number '1'.
- Dyslexia mode switches to OpenDyslexic, whose heavy-weighted letter bottoms are meant to anchor each letter's orientation so it doesn't seem to flip or swim.
To avoid a flash of unstyled text, an inline synchronous script in the document <head> reads the portfolio-font-mode preference from localStorage and applies data-font-mode="opendyslexic" prior to the initial paint.
Text in the Canvas 2D cards and hero modules is laid out by the Pretext engine. When the user switches font modes, the useFontPreference hook clears the font configuration and layout caches and recalculates in the same frame, so nothing overflows or clips.
How the pieces connect
flowchart TD
subgraph StorageInit [Persistent Storage & Head Script]
A[Browser LocalStorage] -->|portfolio-font-mode| B[Head Script Inline Execution]
B -->|Set data-font-mode| C[document.documentElement]
end
subgraph FontPipeline [Next.js Font Optimization]
D[next/font/google] -->|--font-lexend| E[Lexend Variable Weight]
D -->|--font-atkinson| F[Atkinson Hyperlegible]
G[next/font/local] -->|--font-opendyslexic| H[Self-Hosted OpenDyslexic .woff2]
end
subgraph CSSCascade [Tailwind CSS v4 & Attribute Selector]
C & E & F & H --> I[app/globals.css @theme inline]
I -->|Default| J[--font-sans: var --font-atkinson]
I -->|data-font-mode=opendyslexic| K[Override: font-family, line-height 1.75, letter-spacing +0.04em]
end
subgraph PretextEngine [Zero-CLS Pretext Text Engine]
L[useFontPreference Hook] -->|fontMode State Change| M[Clear Pretext LRU Caches]
M --> N[usePretextLayout Hook]
N --> O[Canvas 2D / SVG Hero & Card Reflow]
end
subgraph DiscoveryMatrix [4-Point Discovery Matrix]
P1[SkipToContent 1st Tab-Stop] --> L
P2[Navbar Desktop Pill & Mobile Drawer] --> L
P3[Command Palette Toggle Action] --> L
P4[Footer Persistent Strip Toggle] --> L
end
Implementation notes
Client-Side Typography Preference Hook (hooks/useFontPreference.tsx)
"use client";
import { useCallback, useEffect } from "react";
import { usePersistentState } from "@/hooks/usePersistentState";
import { clearCache } from "@chenglou/pretext";
import {
cssPropertyCache,
fontConfigCache,
textPrepareCache,
textLayoutCache,
richLayoutCache,
} from "@/lib/graphics-engine";
type FontMode = "default" | "opendyslexic";
function useFontPreference() {
const [fontMode, setStoredFontMode] = usePersistentState<FontMode>(
"portfolio-font-mode",
"default"
);
const isDyslexic = fontMode === "opendyslexic";
const clearAllFontCaches = useCallback(() => {
cssPropertyCache.clear();
fontConfigCache.clear();
textPrepareCache.clear();
textLayoutCache.clear();
richLayoutCache.clear();
clearCache();
}, []);
const setFontMode = useCallback(
(mode: FontMode) => {
setStoredFontMode(mode);
if (typeof document !== "undefined") {
if (mode === "opendyslexic") {
document.documentElement.setAttribute("data-font-mode", "opendyslexic");
} else {
document.documentElement.removeAttribute("data-font-mode");
}
}
clearAllFontCaches();
},
[setStoredFontMode, clearAllFontCaches]
);
const toggleDyslexiaMode = useCallback(() => {
setFontMode(isDyslexic ? "default" : "opendyslexic");
}, [isDyslexic, setFontMode]);
return { fontMode, isDyslexic, setFontMode, toggleDyslexiaMode };
}
Defensive CSS & Cognitive Spacing Overrides (app/globals.css)
/* OpenDyslexic High-Assurance Cognitive Mode */
[data-font-mode="opendyslexic"] {
--font-sans: var(--font-opendyslexic), system-ui, -apple-system, sans-serif !important;
--font-heading: var(--font-opendyslexic), system-ui, -apple-system, sans-serif !important;
font-family: var(--font-sans) !important;
line-height: 1.75 !important;
letter-spacing: 0.04em !important;
word-spacing: 0.08em !important;
}
[data-font-mode="opendyslexic"] h1,
[data-font-mode="opendyslexic"] h2,
[data-font-mode="opendyslexic"] h3,
[data-font-mode="opendyslexic"] h4,
[data-font-mode="opendyslexic"] h5,
[data-font-mode="opendyslexic"] h6 {
font-family: var(--font-heading) !important;
letter-spacing: 0.02em !important;
line-height: 1.5 !important;
}
Tradeoffs and lessons
- OpenDyslexic (.woff2) is served from
public/fonts/instead of a CDN. That removes a third-party round trip, keeps visitors' requests off another company's servers, and loads the font in sub-10ms. - OpenDyslexic mode raises line height (1.75) and character tracking (+0.04em), which makes containers 15-20% taller. That is one reason for the site's rule that text containers use
min-h-*instead of fixed heights. - Placing the dyslexia toggle inside
<SkipToContent />ensures keyboard and screen-reader users can activate accessible typography before navigating page contents. - Canvas 2D measurement needs its caches cleared synchronously on toggle. Otherwise the canvas cards measure with the old font's metrics and truncate text.