---
name: build-visual-courseware
description: Build, restyle, validate, and package user-supplied course outlines, manuscripts, slide text, or existing decks as polished interactive 16:9 HTML courseware. Use for courseware layout, visual page systems, Notion-style editable infographics, classroom exercises, closing Q&A, page-aware AI assistants, responsive/print QA, screenshots, PDF, and delivery archives while preserving the supplied content and its sources.
---

# Build Visual Courseware

Build a complete, local-first courseware deliverable from content the user supplies. Use the scripts for deterministic setup and checking; use judgment for page selection and visual composition.

## Start here

1. Run `node scripts/doctor.mjs`. Report missing required dependencies with the printed repair advice; do not install silently.
2. Read all supplied text and assets. Create a source pointer for every page; never invent claims, cases, data, attribution, or modules.
3. Run `node scripts/scaffold.mjs --output <folder> --title <course-title>` for a new project.
4. Edit `course-manifest.json`, then run `node scripts/validate-manifest.mjs <folder>/course-manifest.json`.
5. Read [references/source-manifest.md](references/source-manifest.md) for the content contract and [references/page-type-catalog.md](references/page-type-catalog.md) to choose page types.
6. Build pages with [assets/starter/](assets/starter/), [assets/components/](assets/components/), and [assets/icons/notion-icons.svg](assets/icons/notion-icons.svg). Preserve page IDs and manifest order.
7. For diagrams, read [references/notion-infographics.md](references/notion-infographics.md) and [references/diagram-recipes.md](references/diagram-recipes.md). Keep labels as live text and precise relationships as HTML/CSS/SVG.
8. If an on-page helper is needed, use [references/ai-assistant.md](references/ai-assistant.md). Never embed credentials.
9. Run `node scripts/audit-static.mjs <folder>`, then `python3 scripts/audit-browser.py <folder>`.
10. Read [references/browser-qa.md](references/browser-qa.md), inspect all contact sheets, and fix each failed page. Use [references/failure-field-guide.md](references/failure-field-guide.md) for known failure patterns.
11. Run `python3 scripts/render-courseware.py <folder> <evidence-folder>` for screenshots, contact sheets, PDF, and the final browser report.
12. Apply [references/delivery-checklist.md](references/delivery-checklist.md), then run `node scripts/package-courseware.mjs <folder> <output.zip>`.

## Non-negotiable page rhythm

- First page: cover.
- Early page: agenda or learning route.
- Between chapters: chapter divider.
- Inside chapters: vary judgment, relationship, evidence, case, and activity pages; avoid uninterrupted card grids.
- Add an exercise only when the supplied outline contains a real task, timebox, and output.
- Before the close: summary.
- Last page: Q&A.

## Visual rules

- Use navy `#17324D`, graphite `#17212B`, muted teal `#2F6F73`, ice `#E8F1F2`, and white as the base system.
- Avoid gradients, 3D effects, heavy shadows, and yellow/gold/orange emphasis.
- Keep one primary communication task per page.
- Split before shrinking projection text.
- Keep exact comparisons in real tables and all important labels selectable/searchable.
- Use diagrams only when spatial structure improves comprehension.
- Keep navigation, keyboard, fullscreen, mobile, print, and assistant behavior intact.
- Keep delivery assets local unless the user explicitly accepts an online dependency.

## Resource routing

- Layout tokens and composition: [references/page-system.md](references/page-system.md)
- Page-type decision catalog: [references/page-type-catalog.md](references/page-type-catalog.md)
- Notion visual language: [references/notion-infographics.md](references/notion-infographics.md)
- Diagram construction recipes: [references/diagram-recipes.md](references/diagram-recipes.md)
- Page-aware AI assistant: [references/ai-assistant.md](references/ai-assistant.md)
- Manifest and source traceability: [references/source-manifest.md](references/source-manifest.md)
- Responsive and print behavior: [references/responsive-print.md](references/responsive-print.md)
- Browser measurement and review: [references/browser-qa.md](references/browser-qa.md)
- Symptoms, causes, fixes, regressions: [references/failure-field-guide.md](references/failure-field-guide.md)
- Final gate and archive contents: [references/delivery-checklist.md](references/delivery-checklist.md)

The generic, fully rendered example is in [assets/demo/](assets/demo/); proof artifacts are in [evidence/](evidence/).
