Module figures
A module may include figures/ and an optional figures.yml list. Filenames are relative to figures/, not to the module. Empty lists are allowed; unlisted assets are not. Example:
- file: cover.webp
kind: scene
alt: Invented colleagues discussing a notebook at a café table
caption: Generated scene, not a photograph of real people.
tool: Image generation tool name
- file: approval.svg
kind: workflow
alt: A proposal goes to a human approval gate before publication
caption: Approval sequence taught in this module (s1).
sources: [s1]
objective: 100.1-a
tool: Mermaid
source_file: approval.mmd
Kinds are scene, infographic, and workflow. Alt text is always non-empty. Caption and tool are text fields; record the generating tool when applicable. Infographics and workflows require non-empty source ids from the module's sources.yml and an objective id from its level map. Their sources pass the same checked-source gate as text citations. Workflows require an SVG and its matching .mmd source alongside it. Only .webp, .png, .svg and listed workflow sources are permitted, each under 400 KB. Paths cannot escape figures/. SVG scripts, event handlers, and external references are forbidden; references may only target same-document #ids.
Infographics also require text_file: figure-text/<name>.md, relative to the module folder (not figures/). This must be an existing, non-whitespace Markdown file inside figure-text/; absolute paths, .., symlink escapes and other extensions are rejected. text_file is not allowed on scenes or workflows. All files in figure-text/ must be listed by an infographic. The text must carry the infographic's data as a table or list. The viewer renders this Markdown inline after the caption in a disclosure labelled Figure data as text, including tables and escaped raw HTML. No additional fetch or service-worker asset is needed for this inline text.
In gears,  renders a figure with the manifest's alt and escaped caption. Only listed images render. A scene named cover.webp also appears above the lesson. Assets are copied and precached by both the standalone viewer and Pages build. Figures use the Wren Café 14px card radius and 12px mono captions; no remote image access is enabled. Images have a hard 320px minimum width, including when the phone's content column is narrower. The figure scrolls horizontally rather than shrinking the image below that floor, and is keyboard focusable for scrolling. This preserves the intended minimum display width for 12px diagram text; art authors must still choose a viewBox and label sizes that are legible at 320px.
Spec: the lesson viewer
Builder: Devin. Reviewers: Devin Review and Claude. Bob merges.
What it does
Shows any module in any of its three gears, with a gear switch that keeps the learner's place, the module's quiz, its workbook, and its public stamp.
Rules
- Static site in
apps/viewer/, built from the module folders at build time; no content is copied into code. Published on GitHub Pages only when Bob and Ken make the course public. - Gear switch: plain, standard, technical. Switching keeps the learner at the same objective (use the
<!-- objectives: … -->marks as anchors). - Citations render as numbered notes linking to
sources.ymlentries, with each source's checked date. - The quiz runs in the browser from
quiz.json: one item at a time, thewhyshown after answering, score at the end. Answers and scores stay in the open page; they are never saved or sent. - The level map lists modules in their level's course order with reading time for each gear. After a workbook, the next available module opens in plain gear. The final workbook links to the level map.
- From the level map, learners can opt in to remembering their last lesson page and finished quizzes. Only those progress markers are kept in this browser's local storage. The map shows a Resume link and finished-quiz ticks, and "Forget my progress" erases the markers and turns off remembering.
- Review mode (deep review #6):
review/<level>/pages built fromlevels/<level>/review-sets.json, a level review mixed from every module and "come back in 2 days / 1 week" sets. Each item names its module and links to the lesson part it tests; the score page lists the modules to reread. Items reuse module quiz items by ref, or are new items thattools/check_modules.pyholds to a stated objective and a checked source. New items stay out of the build until the two reviewers of each module they draw on approve them;build.py --draftsshows them, bannered, for those reviewers. Review pages store nothing, so they cannot remind the learner to come back. - The public stamp on every module: version, as-of date, status, the two reviewers' names and roles, the red-team lead, the board sign-off date, and a link to
ERRATA.md. A module that is notpublishedshows a clear "Draft, not yet reviewed" banner. - Accessibility: WCAG 2.2 AA, keyboard, screen readers, reduced motion, 200% zoom. Uses the Wren Café design system from the Foundation site.
Done when
- Builds from the repo with one command and renders module 100.1 in all three gears.
- Tests cover gear switching at an objective anchor, citation rendering, quiz scoring, the draft banner and review mode (mixed items, reread links, drafts left out of the public build).
python3 tools/check_modules.pyand the app's tests pass in CI.