The problem
Most modern web applications choose typography based exclusively on brand aesthetics or minimalism, relying on geometric grotesque sans-serifs that induce visual crowding and character mirror confusion for neurodivergent readers. For individuals with dyslexia, letters like b, d, p, and q appear rotationally symmetrical, causing cognitive fatigue, visual reversals, and reading stalls.
The personal context: My brother was diagnosed with dyslexia early in life. Watching him navigate the modern web (where ultra-thin fonts, cramped line heights, and layout shifts are ubiquitous) made the friction undeniable. Standard web design optimizes for visual coolness; accessible engineering optimizes for cognitive clarity, legibility, and orientation.
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
Tripartite Typography Hierarchy: We architected a three-tier typography system grounded in cognitive research:
- Headings (Lexend): Developed specifically by educational researchers to reduce visual stress and increase reading speed through expanded letter-spacing and distinct glyph silhouettes.
- Prose & UI (Atkinson Hyperlegible): Commissioned by the Braille Institute to maximize character disambiguation for low-vision readers, emphasizing distinct forms for confusing pairs (e.g. uppercase 'I', lowercase 'l', and number '1').
- Dyslexia Mode (OpenDyslexic): A specialized typeface utilizing heavy weighted bottoms to anchor character orientation in mental space, preventing rotational flipping and visual swimming.
Client-Side Persistent Mode & Zero-FOUT Initialization: To eliminate flashing 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.
Zero-CLS Dynamic Pretext Layout Reflow: Text rendered in custom Canvas 2D cards and hero modules utilizes the Pretext layout engine. When the user switches font modes, the useFontPreference hook purges the font configuration and layout caches, triggering an immediate recalculation within the current frame to prevent layout overflow or bounding-box clipping.
How the pieces connect
MERMAIDCopy
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)
TYPESCRIPTCopy
"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)
CSSCopy
/* 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
- Self-Hosted WOFF2 vs. External CDNs: Serving OpenDyslexic (.woff2) locally from
public/fonts/ removed third-party network roundtrips, isolated user telemetry, and guaranteed sub-10ms font initialization.
- Visual Density vs. Readability: OpenDyslexic increases line height (1.75) and character tracking (+0.04em). This expands container heights by 15-20%, reinforcing our defensive CSS rule that text containers must use
min-h-* rather than rigid fixed heights.
- First Tab-Stop Accessibility: Placing the dyslexia toggle inside
<SkipToContent /> ensures keyboard and screen-reader users can activate accessible typography before navigating page contents.
- Pretext Cache Invalidation: Canvas 2D measurement requires clearing computed property caches synchronously on toggle; otherwise, canvas cards would measure using obsolete font metrics, inducing text truncation.