SECTION 01
Store the relationship before choosing the pixels
A visual specification declares kind, title, description, typed items, values, details, groups, and caption so multiple semantic renderers can preserve the same meaning.
A lesson visual does not contain SVG coordinates or a screenshot. It contains labeled items and the instructional relationship among them. Chart values become bounded bars with visible numeric labels. Flows and timelines become ordered lists. Matrices and comparisons become native tables with headers, captions, and a focusable scroll region. Every figure connects its title and description through ARIA references and retains a visible figcaption.
This structure supports responsive design and nonvisual access from one content record. If CSS fails, the ordered lists and tables still express the sequence or comparison. If a chart parser cannot extract a number, the item's label, value string, and detail remain visible instead of disappearing behind an empty canvas. Authors can focus on accurate relationships, while the renderer owns layout, scale, and compact-screen behavior.
| Kind | Primary structure | Meaning retained without styling |
|---|---|---|
| Chart | Figure plus unordered list | Label, value, and detail for each measure |
| Flow | Figure plus ordered list | Decision steps remain in sequence |
| Timeline | Figure plus ordered list and time labels | Events remain chronologically readable |
| Matrix / comparison | Native table | Headers preserve row and column relationships |
SECTION 02
Require an image to teach something prose can name
Selected lessons add self-hosted images only when the metadata includes an objective, concise alternative text, a caption, a complete visual explanation, dimensions, and provenance.
Eight lesson concepts use purposeful generated imagery: four explanatory cartoons and four photorealistic fictional scenes. Every asset is a 1440-by-810 WebP, lazy loaded through the framework image component, and held below the release's 200 KB per-lesson budget. Assets use versioned, date-stamped paths and immutable cache headers, while the release manifest records a SHA-256 digest of each image. Width and height reserve layout space, while responsive sizes let the browser request an appropriate representation.
Accessibility metadata does more than repeat the filename. Alternative text briefly identifies the meaningful scene, the caption states the lesson, and the explanation spells out the complete instructional relationship for readers who cannot inspect the image. The objective connects the image to a lesson outcome. The credit discloses generated educational art, fictional people or scenarios, generator, and creation date. Exact rules, labels, calculations, and decision logic still live in semantic prose or visuals rather than only inside the pixels.
SECTION 03
Use the browser's speech engine as progressive enhancement
Narration is assembled from the complete section model, voiced only after a learner action, and controlled through native browser SpeechSynthesis lifecycle operations.
On the client, the lesson waits until after mount to detect SpeechSynthesis and SpeechSynthesisUtterance. It enumerates browser-provided voices, sorts them by language and name, responds to the voiceschanged event, and uses a stable voiceURI-based key. The chosen voice and rate are stored locally because available voices are properties of a browser and device, not the shared learner record. Default browser voice remains an explicit option. The portal does not bundle audio or operate a speech service; whether synthesis is local depends on the selected browser voice.
The spoken text includes heading, paragraphs, takeaways, visual labels and details, image caption and full explanation, case facts and choices, exam transfer, and checkpoint prompt. Playback never starts automatically. Listen creates a new utterance after canceling any old one; Pause toggles pause and resume; Stop cancels; changing voice or rate from the active section stops its narration so stale settings cannot continue there. End and error callbacks both restore idle controls.
- Detect support
Check speech engine and utterance constructor after mount.
- Load voices
Enumerate browser-provided voices and restore a valid saved choice.
- Learner selects Listen
Build complete section text and start one utterance.
- Control playback
Pause, resume, restart, stop, speed, or voice.
- Return to idle
End, error, cancel, or unmount clears active state.
SECTION 04
Test meaning, not just media presence
Browser tests verify narration controls and content, image delivery and metadata, responsive overflow, and unsupported-speech rendering; semantic fallback structures are implemented but not directly asserted by E2E.
The E2E suite installs a deterministic speech mock with two voices and records speak, pause, resume, cancel, text, rate, and selected voice. Pointer interactions choose a voice, reload to prove local persistence, exercise listen/pause/resume/stop, and simulate both end and error callbacks. The assertion checks that spoken text is substantive. Separate image loops verify natural dimensions, lazy loading, WebP responses, immutable caching, learning-objective metadata, disclosed fiction, and inclusion of the full explanation in spoken text.
Progressive enhancement is also tested by removing speech support before navigation. Listen and Voice become disabled, an explanatory message appears, and all four lesson sections remain rendered. At 320- and 375-pixel viewports, the suite checks that document scroll width does not exceed client width. Semantic list and table fallbacks are implemented in the renderer, but the current E2E suite does not directly assert every visual kind's fallback. These tests avoid claiming identical voices across platforms: the feature promises controls around voices the browser provides, with a functional text lesson when it provides none.
REFERENCES
Sources and further reading
- Images TutorialW3C Web Accessibility Initiative
Accessibility guidance for deciding when an image needs concise alternative text, a longer text equivalent, or decorative treatment.
- Understanding Success Criterion 1.1.1: Non-text ContentW3C Web Accessibility Initiative
Normative-context guidance supporting equivalent text for instructional relationships shown visually.
- SpeechSynthesisMozilla Developer Network
Browser API reference for enumerating installed voices and controlling speak, pause, resume, and cancel behavior.
- Server and Client ComponentsNext.js
Framework reference for keeping data access on the server while isolating interactive browser code behind explicit client boundaries.
KEEP EXPLORING
See the system in context
- Visual lesson — Inspect a purposeful explanatory image, semantic visual, and browser-provided narration controls.
- Accessibility settings — Configure reduced motion and other device-local learning preferences.
- Curriculum — Browse lessons that remain complete whether or not images or speech are available.