A "decodable" passage is a short text where every word can be sounded out using only the letter patterns a child has been taught so far. If a beginner has learned short vowels and single consonants, "Sam has a big pig" is decodable. "The rain came down" is not, because ai hasn't been taught yet. The child can't read it, guesses, and the practice turns into a memory test.
I build Dyslexia Steps, a free set of reading practice tools for kids (phonics lists, printable worksheets, small browser games). It's practice material, not a diagnosis tool. When we wrote our own five-step set of decodable fluency passages, I didn't trust myself to keep every word inside its step by eye. An adult reader doesn't notice that "storm" uses an r-controlled vowel. So I treated the passages like source code and gave them a linter that runs in CI.
Below: how the checker works, what it can't catch, and the audio-filename bugs I hit in other languages.
The data: passages are TypeScript, not prose
Each worksheet pack lives in lib/worksheets/dyslexia.ts as typed data. A passage page looks like this (trimmed):
// lib/worksheets/dyslexia.ts { id: "fluency-passages-step-1-cvc", step: 1, pages: [ { kind: "passage", title: "The Big Pig", lines: [ "Sam has a big pig.", "The pig is fat. It can dig.", "It digs in the mud,", "and the mud gets on Sam.", // ... ], talk: ["Where did the pig dig?", "What did Mom bring?"], }, // ... ], } A separate script (scripts/worksheets/build-dyslexia.mts) renders these to PDF with Playwright. The verifier only reads the data, so it doesn't care how the pages look.
Defining a "step" as regexes plus word lists
There are two ways a word can be allowed at a given step:
- It matches a spelling pattern taught at that step. CVC at step 1, digraphs (
sh,ch,th...) at step 3, blends and silent e at step 4, vowel teams and r-controlled vowels at step 5. - It's on an allowed list. Our own phonics word sets for that step, the Dolch sight-word lists for that step, or a short list of character names.
The patterns are built from small regex fragments:
// lib/worksheets/dyslexia.ts const C = "[bcdfghjklmnpqrstvwxyz]"; const ONSET3 = `(?:sh|ch|th|wh|qu|${C})`; const BLEND_ON = "(?:spl|spr|str|scr|shr|thr|bl|cl|fl|gl|pl|sl|br|cr|dr|fr|gr|pr|tr|sc|sk|sm|sn|sp|st|sw|tw)"; const CODA3 = `(?:sh|ch|tch|th|ck|${C})`; const BLEND_CO = "(?:nd|nt|mp|st|sk|sp|lt|lk|lp|ld|lf|ft|ct|pt|xt|nk|ng|nch|lch)"; const VOWEL5 = "(?:ai|ay|ee|ea|oa|ow|igh|ie|ue|ew|oo|ar|or|er|ir|ur|[aeiouy])"; export const STEP_PATTERNS: Record<1 | 2 | 3 | 4 | 5, RegExp[]> = { 1: [new RegExp(`^${C}[aeiou]${C}$`)], 2: [new RegExp(`^${C}[aeiou]${C}$`)], 3: [new RegExp(`^${ONSET3}[aeiou]${CODA3}$`)], 4: [ new RegExp(`^(?:${BLEND_ON}|${ONSET3})?[aeiou](?:${BLEND_CO}|${CODA3})?$`), new RegExp(`^(?:${BLEND_ON}|${ONSET3})?[aeiou]${C}e$`), // silent e ], 5: [ new RegExp(`^(?:${BLEND_ON}|${ONSET3})?${VOWEL5}(?:${BLEND_CO}|${CODA3}|ll|ss|ff|zz)?$`), new RegExp(`^(?:${BLEND_ON}|${ONSET3})?[aeiou]${C}e$`), ], }; Steps 1 and 2 share a pattern. What step 2 adds is the word-family lists (-at, -ug...), which come in through the second mechanism:
export const STEP_SETS = { 1: ["cvc"], 2: ["cvc", "families"], 3: ["cvc", "families", "digraphs"], 4: ["cvc", "families", "digraphs", "consonant-blends", "silent-e-words"], 5: ["cvc", "families", "digraphs", "patterns"], }; export const STEP_SIGHT = { 1: ["pre-k", "kindergarten", "first-grade"], // ... 5: ["pre-k", "kindergarten", "first-grade", "second-grade", "third-grade", "dolch-nouns"], }; These IDs point at the same data that powers the public word-list pages (for example the CVC word list). If a word is added to a list on the site, it becomes legal in passages at that step automatically, with no second copy to keep in sync.
Inflections: the cheap stemmer
"Hens", "digs" and "jumped" aren't in any list, but their roots are. A tiny function generates candidate bases:
export function bases(w: string): string[] { const out = [w]; if (w.endsWith("es")) out.push(w.slice(0, -2)); if (w.endsWith("s")) out.push(w.slice(0, -1)); if (w.endsWith("ed")) { out.push(w.slice(0, -2), w.slice(0, -1)); // jumped → jump, baked → bake if (/(.)\1ed$/.test(w)) out.push(w.slice(0, -3)); // hopped → hop } return out; } The -ed suffix isn't taught until step 5, so the verifier only lets a word drop -ed at step 5. Before that, "red" and "bed" pass as plain CVC words, while "jumped" fails:
// scripts/verify-dyslexia-packs.mjs return (w) => { const cands = bases(w).filter((b) => step === 5 || !w.endsWith("ed") || b === w); return cands.some((b) => names.has(b) || vocab.has(b) || STEP_PATTERNS[step].some((re) => re.test(b))); }; The gate
The verifier loops over every passage and sentence, tokenises, lowercases, strips a possessive 's, and records every word that isn't allowed at the pack's step. It also checks answer keys, because a worksheet with a wrong answer key is a bug too:
if (pg.kind === "circle") for (const r of pg.rows) if (r.options.filter((o) => o === r.target).length !== 1) err(p, `target not exactly once in row: ${r.target}`); if (pg.kind === "join" || pg.kind === "split") for (const it of pg.items) if (it.parts.join("") !== it.word) err(p, `parts don't make the word: ${it.parts.join("+")} ≠ ${it.word}`); (The error strings in the repo are in Turkish; I translated them here.) Other checks: the b/d fill-in-the-blank has to resolve with exactly b or d, the sorting bank has to equal the union of its columns, "make a word" answers have to be buildable from the boxes, and every pack in the code needs a generated PDF on disk, or the page would show a broken download button.
It runs in make verify, which is one stage of make check (lint, types, verify, build). Today's run:
✓ verify-dyslexia-packs: 11 paket, 1158 okuma kelimesi decodable, cevaplar tutarlı That's 11 packs and 1,158 reading words, all decodable at their step, with consistent answer keys.
To see where words land, I ran a few through the patterns alone, with no lists:
| Word | First step whose pattern accepts it | Correct? |
|---|---|---|
| cat | 1 | yes |
| hens | 1 (via bases) | yes |
| ship | 3 | yes |
| frog | 4 | yes |
| cake | 4 | yes |
| rain | 5 | yes |
| jumped | 5 (-ed gate) | yes |
| the | 4 | no, it's a sight word |
| said | 5 | no, it's irregular |
The last two rows are the honest part. More on that below.
Same idea, other languages
We also publish word lists in German, Spanish, French, Dutch, Brazilian Portuguese and Turkish. Each language's curriculum is written for that language, not translated from English. Those pages have their own verifier, scripts/verify-wordlists.mjs. It checks slugs, meta lengths, that every hyphenated syllable split re-joins to the word, that every fill-in has exactly one blank, and that every word has an audio file on disk.
Turkish gets a version of the decodability check that's simpler than the English regexes. Turkish schools teach letters in fixed groups, so a reading text for a letter may only use letters from that group and earlier ones:
// content/wordlists/tr/okuma-metinleri.ts export const TR_GROUPS = ["anetil", "okurım", "üsöydz", "çbgcş", "phvğfj"] as const; // scripts/verify-wordlists.mjs const gi = TR_GROUPS.findIndex((g) => g.includes(harf)); const allowed = new Set(TR_GROUPS.slice(0, gi + 1).join("")); for (const c of cumleler) { const out = [...new Set([...c.toLocaleLowerCase("tr")] .filter((ch) => /\p{L}/u.test(ch) && !allowed.has(ch)))]; if (out.length) errors.push(`tr/${slug}: letter outside group ${gi + 1} (${out.join("")}): "${c}"`); } Note toLocaleLowerCase("tr"). Plain toLowerCase() turns I into i, but in Turkish it should become ı, a different letter in a different group.
Current totals from the same run:
| Locale | Word-list pages | Words/syllables with audio |
|---|---|---|
| de | 60 | 1,619 |
| es | 76 | 2,202 |
| fr | 58 | 1,689 |
| nl | 34 | 956 |
| pt-br | 92 | 2,278 |
| tr | 87 | 2,437 |
What I got wrong
1. Stripping accents from audio filenames. Every word on the site has a pre-generated MP3, and the filename comes from audioKey(word). The first version normalised to ASCII by deleting combining marks after NFD. That was fine for German umlauts, which we map explicitly (Mäuse → maeuse). In Spanish and Portuguese it merged words that sound different:
v1 papa → p-papa v1 papá → p-papa v1 avô → p-avo v1 avó → p-avo v1 año → p-ano v1 ano → p-ano The Spanish word lists would have played "papa" (potato) when a child tapped "papá" (dad). The fix keeps the accent as a marker and maps ñ explicitly. It meant moving 126 existing files:
.replace(/ñ/g, "ny") .normalize("NFD").replace(/[̀-ͯ]/g, "_") // papá → p-papa- 2. Then Turkish broke the fix. ı (dotless i) has no NFD decomposition, so it isn't a combining mark. It fell through to [^a-z]+ → "-". Meanwhile ş decomposes to s + cedilla, the cedilla became _, and the final regex merged _ and the ı leftover into a single dash:
v2 sı → p-s- v2 şı → p-s- v2 cı → p-c- v2 çı → p-c- Those are four different syllables a Turkish beginner has to tell apart, and they were sharing two audio files. Now ı is mapped to iq before anything else (sı → p-siq, şı → p-s-iq). No other language uses ı, so no other filenames changed. Lesson: when a filename is a hash of meaning, write a test with the minimal pairs of every language you support, not just the alphabet.
3. Syllabified display generated its own audio. On some pages we show words split into syllables (pa-pá). An early version treated every displayed syllable as something to voice, so it generated MP3s nobody ever played. scripts/audio-orphans.mjs lists files no page references. In Spanish alone it found 439 of them, and we deleted them.
4. Variable fonts in PDFs. The worksheets use Lexend. Google Fonts' css2 API serves it as a variable font, and Chrome's PDF output embedded it as Type 3: six pages came out at 430 KB and looked blurry in some viewers. Requesting the old css API with an old user agent returns static per-weight files. Those embed as real subsetted TrueType.
5. The regex can't see pronunciation. This one is still true, and the table above shows it. "the" matches the step-4 shape (th + vowel), and "said" matches the step-5 vowel-team shape. Neither is read the way its pattern suggests. In practice both are on the Dolch pre-K list, which is allowed from step 1, so the passages are fine. But the checker accepts them for the wrong reason, and an irregular word not on a sight list could slip through the same way. A real fix needs a phoneme-level lexicon. For now the linter only guarantees that we didn't use a spelling pattern the child hasn't met. That's a narrower claim, but it holds. (For background on why decodability matters at all, our guide to decodable text covers it without the regex.)
Takeaways
- If content has rules, store it as data and lint it in CI. "Every word is decodable at step N" is just a test.
- Reuse the same word lists in the checker and on the site, so they can't drift apart.
- Any function that turns words into filenames needs minimal-pair tests across every language you ship.
- Write down what the check doesn't prove. Ours proves spelling patterns, not pronunciation.
The verifier is 81 lines, and it now runs on every check.
This post was drafted with help from an AI assistant. Code, numbers and command output come from our repository and were checked by me.