interactive-study-guide

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:

Section	Heading Pattern	Content Type
Purpose	## 1. Why This Exists	Prose with problem/approach/users
Threshold Concepts	## 2. The Big Ideas	Named concepts with code locations
System Map	## 3. System Map	Mermaid diagram + table
Request Walkthrough	## 4. Walking Through a Request	Sequence diagram + annotated code steps
Deep Dives	## 5. System Deep Dives	Multiple ### 5.X subsections
Patterns	## 6. Patterns & Conventions	Named patterns + naming table
Boundaries	## 7. Boundaries & External Systems	Table of external systems
Testing	## 8. Testing Strategy	Prose with exploration prompts
Next Steps	## 9. Your Next Steps	Checklists by day

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:

Section	Interactive Treatment
Purpose	Full-bleed hero with large serif typography. Animated text that fades in on load. The problem statement presented as a bold pull-quote. No interactivity needed — let the words breathe.
Threshold Concepts	Cards that start collapsed showing only the concept name. Click to expand with a smooth height transition. Show "you'll see this in" file paths as clickable pills. Subtle connecting lines between related concepts.
System Map	Interactive D3 force-directed graph replacing the Mermaid diagram. Nodes are draggable. Hover shows the one-line purpose from the table. Click a node to scroll to its deep dive section. Animated edges show data flow direction.
Request Walkthrough	Scroll-driven step-through. A sticky diagram panel on the left animates as the reader scrolls through annotated code steps on the right. Each step highlights the active system in the diagram. Code blocks use syntax highlighting with line-by-line reveal.
Deep Dives	Tabbed interface where each system is a tab. Within each tab: purpose as a bold header, pattern name as a linked badge, abstractions table, interfaces shown as a mini connection diagram, and the exploration task in a distinct callout box.
Patterns	Searchable/filterable card grid. Each card shows pattern name, where it appears (as code-location pills), and why. Cards flip or expand on click to show the full description. Naming conventions shown as a styled reference table.
Boundaries	Clean data table with hover-to-expand rows. Each row shows the external system, its role, and integration pattern. Consider a simple boundary diagram showing inside/outside the system.
Testing	Minimal treatment — styled prose with the exploration prompt in a distinct interactive callout (checkbox that reveals a hint).
Next Steps	Interactive checklist with local storage persistence. Progress bar at the top. Days presented as horizontal timeline nodes. Completed items get a satisfying check animation.

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.