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 --openStep 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-motionis 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.