Interactive Study Guide

Transform a static study guide markdown file into an immersive, interactive learning experience served as a local web app. The output should feel like a NYT interactive feature or a Pudding.cool essay — editorial typography, generous whitespace, purposeful animation, and visualizations that reveal structure rather than decorate.

Guiding Principles

• Restraint over spectacle. Every animation must earn its place by revealing something the static text cannot. Avoid gratuitous motion.
• Content determines form. Each section gets the layout and interactivity best suited to its content type — never force a visualization where prose works better.
• Scroll as narrative. The primary interaction is scrolling. Use scroll-driven reveals, sticky elements, and waypoint transitions to create a reading rhythm.
• Typographic confidence. Large serif headings, measured line lengths, and ample vertical rhythm. The text itself should feel beautiful before any interactivity loads.
• Progressive enhancement. The page is readable and useful even if JavaScript fails. Interactivity layers on top.

Workflow

Step 1: Locate and Parse the Study Guide

Accept a path to the study guide markdown file. Parse it into structured sections using the known template format from codebase-study-guide:

If the markdown doesn't match this exact structure, adapt gracefully — detect sections by heading content rather than numbering.

Step 2: Set Up the Project

Run the scaffold script to create the Vite project:

bash scripts/scaffold.sh <output-directory> "<project-name>"

This creates a configured Vite project with D3, Prism.js, and the editorial design system pre-installed. After scaffolding, run npm install in the output directory.

Step 3: Build Section by Section

Transform each parsed section into its interactive counterpart. Consult references/section-strategies.md for detailed visualization patterns and code examples for each section type. Consult references/design-system.md for all typography, color, spacing, and motion tokens.

The section-to-visualization mapping:

Step 4: Wire Navigation and Transitions

Build a minimal navigation system:

• Left sidebar (desktop) or bottom sheet (mobile): Section titles as nav links with scroll-spy highlighting
• Progress indicator: Thin bar at top of viewport showing read progress
• Smooth scroll: Clicking a nav link animates to the section
• Section transitions: Each section fades in as it enters the viewport using IntersectionObserver

Step 5: Start the Dev Server

After building all components:

cd <output-directory> && npx vite --open

Step 6: Polish Pass

Before presenting to the user, verify:

• Typography hierarchy is clear — headings, body, code, and captions are visually distinct
• Whitespace is generous — sections breathe, nothing feels cramped
• Animations are smooth and purposeful — no jank, no gratuitous bouncing
• System map is interactive — nodes drag, hover shows info, click navigates
• Code blocks have syntax highlighting appropriate to the codebase's language
• Mobile layout works — single column, touch-friendly interactions
• prefers-reduced-motion is respected — all animations disable gracefully
• Color contrast meets WCAG AA — especially code blocks and muted text
• Navigation scroll-spy accurately tracks the current section
• Interactive elements (tabs, cards, checklists) respond immediately, no loading states needed

Resources

scripts/scaffold.sh

Creates a configured Vite project with dependencies and the editorial design system. Usage documented in Step 2.

references/section-strategies.md

Detailed visualization strategy and code patterns for each study guide section. The primary reference while building — consult before writing any section component.

references/design-system.md

Complete editorial design system: typography scale, color palette, spacing, motion tokens, and component-level styles. Every visual decision should reference these tokens.