Phonics Checklist

The ⚠️ Watch Out section in each session file lists spec-specific violations. Read it before writing a single line of code.

Timer Lifecycle Pattern

Every manager that uses setTimeout or setInterval must follow this exact pattern. Missing any part is a bug.

class SomeManager {
    constructor() {
        // Declare ALL timer IDs as null at construction.
        this._mainTimer = null;
        this._shakeTimer = null;   // even short cosmetic timers
        this.onComplete = null;
    }

    cancel() {
        // cancel() clears EVERY timer and resets callbacks.
        // Call this at the start of start()/open() AND from showLessonSelect().
        clearTimeout(this._mainTimer);  this._mainTimer = null;
        clearTimeout(this._shakeTimer); this._shakeTimer = null;
        this._close();          // if this manager controls an overlay
        this.onComplete = null; // prevent stale callbacks
    }

    complete() {
        const cb = this.onComplete;  // ← save callback FIRST, before cancel() nulls it
        this.cancel();               // cleanup: clears timers, overlay, and onComplete
        // ... save state ...
        if (cb) cb();
    }

    skip() {
        this.complete(); // ← delegates — don't duplicate cancel logic here
    }

    start(data, onComplete) {
        this.cancel(); // ← defensive reset — prevents stacked listeners on re-entry
        this.onComplete = onComplete;
        // ... initialize fresh state ...
    }
}

Key rules:

• Every setTimeout(...) call → store the return value in this._somethingTimer
• Short cosmetic timers (e.g., shake removal after 400 ms) still need IDs — they can fire on detached DOM
• Use el.isConnected guard inside stored shake timers: if (el.isConnected) el.classList.remove(...)
• cancel() is the single source of truth for cleanup — never inline clearTimeout elsewhere
• showLessonSelect() must call managerInstance.cancel() for every manager

Sequence timers (arpeggio notes, multi-step animations): use an array instead of a single ID:

constructor() { this._pendingTimers = []; }
cancel()      { this._pendingTimers.forEach(clearTimeout); this._pendingTimers = []; }
// In play method:
const id = setTimeout(() => this._playTone(...), i * 20);
this._pendingTimers.push(id);

Defensive Re-initialization

Every start() / open() / show() method that can be called more than once must reset state first:

// ❌ Missing — re-entry stacks a new focus-trap handler on top of the old one
start(lesson, progress, onComplete) {
    this.lesson = lesson;
    // ...
}

// ✅ Correct — cancel() resets everything; _open() adds exactly one listener
start(lesson, progress, onComplete) {
    this.cancel();   // always call cancel() first
    this.lesson = lesson;
    // ...
}

This applies to any manager that opens an overlay — TutorialManager, and any future managers — wherever start() / open() / show() can be called more than once.

Screen Visibility

• Screens → .active class (el.classList.add('active') / .remove('active'))
• Overlays (settings, PIN, tutorial, celebration) → .open class
• Any element toggled visible/hidden → a semantic class like .hidden { display: none } — NOT style.display
• No exceptions for "internal" elements like review sections — they still use a class

Event Handlers

• Always addEventListener — never onclick= HTML attributes or .onclick = property assignment.
• For elements with multiple behavior states (next button in a multi-step flow): bind once in the constructor and dispatch on this.step — do NOT rebind on each step.
• This applies to dynamically created elements (word chips, sort buckets, tile speakers, etc.).

innerHTML Safety

• Never interpolate user-facing data (lesson titles, words) into innerHTML.
• Use createElement + textContent for dynamic content.
• When innerHTML is truly needed for structure, use escHtml() on all variable values.
• container.innerHTML = '' to clear is fine — that's not interpolation.

Singleton Managers

• Managers (tutorialManager, sortManager, audioManager, narrativeManager) → initialize in game.init(), not lazily in startLesson().
• Never window.x = window.x || new X() — reuses stale state on second play.

SaveManager (one localStorage key only)

• One key: 'phonics-progress' — always SaveManager.load() / SaveManager.save().
• Never call localStorage.getItem/setItem from outside SaveManager.
• lessonId keys are strings: use String(id) when reading/writing data.lessons[id].
• When adding lessonId + 1: coerce to number first: Number(lessonId) + 1.

CSS

• ID selectors (#foo) override class selectors (.bar) — never put display: in a base #id rule.
• Use @keyframes (not transition) for enter/exit animations on iOS Safari.
• Secondary text: var(--text-secondary) (#595143) — never #636e72 (fails WCAG AA on cream background).

iOS Safari

• Web Speech API: 50ms delay between speechSynthesis.cancel() and speak().
• Web Audio: Create AudioContext lazily on first user gesture — never in a constructor. ctx.resume() is async — chain oscillator scheduling inside .then(), never immediately after calling it: ctx.resume().then(() => scheduleOscillator()).

Focus Management

On open: focus the first focusable element inside the overlay/dialog.

On close: return focus to whichever element triggered the opening.

• User-triggered dialog (e.g., settings gear → panel): return to the trigger button.
• Programmatically-opened dialog (e.g., tutorial opens automatically on lesson start): return focus to the first logical element in the now-active view — e.g., #board-grid .tile or #board-back-btn. Never leave focus in a void.

Focus trap: Tab/Shift-Tab stays within the overlay; Escape closes/skips.

• Query focusable elements dynamically inside the trap handler (step content changes between steps).
• Exclude .hidden elements from focusable set.

Matched/disabled tiles: tabindex="-1" + aria-disabled="true"; restored on refill.

aria-pressed

Use aria-pressed only on buttons with a persistent binary state. Do NOT add it to pure action triggers.

• Set aria-pressed="false" on creation for toggle buttons; update to "true" when active.
• Matched tiles: set tabindex="-1" + aria-disabled="true" (not aria-pressed).
• Native <button> elements don't need aria-pressed unless they toggle state.

Dynamic aria-label

• Static aria-label in HTML is fixed — VoiceOver reads the attribute, not the textContent.
• Whenever you set textContent on an element that has (or needs) an aria-label, update the aria-label too:

// ❌ VoiceOver says "Stars earned" regardless of actual star count
starsEl.textContent = '★★☆';

// ✅ VoiceOver says "2 of 3 stars earned"
starsEl.textContent = '★★☆';
starsEl.setAttribute('aria-label', '2 of 3 stars earned');

Optional Chaining for Lesson JSON Fields

Lesson JSON fields beyond the required core (id, title, gradeLevel, patterns, wordPool) may be absent. Use optional chaining:

// ❌ Throws if lesson.patternLabels is undefined
const label = lesson.patternLabels[pattern];

// ✅ Safe
const label = lesson.patternLabels?.[pattern] || pattern;

Fields that may be absent: patternLabels, patternHint, tutorialWords, explorer.

Don't Duplicate Existing Work

Check what already exists before adding new infrastructure:

• Settings panel: #settings-panel with _bindSettingsPanel() — do not add a second one.
• PIN dialog: #pin-dialog with _openPinDialog() — do not use prompt().
• Speech mute: stored in SaveManager.load().muteSpeech — do not create a separate localStorage key.
• SFX mute: stored in SaveManager.load().muteSfx — same pattern.

Shuffling

• Never array.sort(() => Math.random() - 0.5) — biased. Use Fisher-Yates:

  for (let i = arr.length - 1; i > 0; i--) {
      const j = Math.floor(Math.random() * (i + 1));
      [arr[i], arr[j]] = [arr[j], arr[i]];
  }
  

WCAG Non-Negotiables

• Never add user-scalable=no to viewport — violates WCAG 1.4.4.
• Touch targets ≥ 44×44px on all interactive elements.
• No color-only state indicators — use shape/text + color.