Interactive Visualization Creator

Interactive Visualization Creator

When to Use: Building interactive visualizations for Next.js/React sites that need to both look stunning AND teach concepts effectively through interactivity.

When NOT to Use: Static charts (use a charting library), pure decoration with no pedagogical purpose, or backend data dashboards (use admin tooling).

Core Insight: The best visualizations are not fancy effects in search of a purpose. They make concepts viscerally obvious that would take paragraphs of text to explain poorly. Every animation, every interaction, every color choice must serve comprehension.

The Golden Thread

These are the invariant truths distilled from 100+ production visualizations across jeffrey_emanuel_personal_site, frankentui_website, frankensqlite_website, and asupersync_website. They are non-negotiable:

See GOLDEN-THREAD.md for the complete deep-dive with code examples from all four projects.

Quick Router

Visualization Type Selector

See COMPONENT-PATTERNS.md for architecture and code for each type.

Creation Workflow

Phase 1: Concept Design

1. Decompose the concept: Use the Concept Decomposition Engine to identify entities, states, transitions, and the teaching variable
2. Define the teaching goal: What concept should the reader understand after interacting?
3. Identify the "aha moment": What specific interaction makes the concept click? (See 5 aha patterns)
4. Choose visualization type: Use the decision tree above
5. Sketch the states: What are the discrete states/phases the user will see?

Phase 2: Architecture

1. Select technology stack: See Tech Selection below
2. Establish visual aesthetic: Derive dark canvas, glass surfaces, and color palette from accent color using AESTHETIC-DNA.md
3. Design interaction model: Desktop hover vs mobile tap paths
4. Plan quality tiers: What degrades on low-end devices?
5. Define color semantics: Map colors to meaning before coding

Phase 3: Implementation

1. Build the static frame first: SVG structure, node positions, layout
2. Add the stepper/controller: Navigation controls for temporal visualizations
3. Wire up animations: Framer Motion transitions between states
4. Add interactivity: Hover/click/drag handlers
5. Implement device adaptation: Touch detection, quality scaling, bottom sheets
6. Add accessibility: reduced-motion, ARIA labels, keyboard nav

Phase 4: Page Composition

1. Choose narrative arc: Select a page template that matches your content
2. Allocate scroll budget: Assign vertical space per section using the scroll budget calculator
3. Choreograph entrances: Apply SectionShell pattern with staggered reveals
4. Run the billboard test: Screenshot random scroll positions — each must be coherent

Phase 5: Polish

1. Assign narrative beats: Map each section's emotional intent to a Motion Lexicon beat for exact spring/color/timing recipes
2. Spring-tune all transitions: Adjust stiffness/damping until motion feels natural
3. Add micro-interactions: Haptic feedback, particle bursts, glow effects
4. Test on real mobile: Not just browser resize - actual touch interactions
5. Validate pedagogy: Does a first-time viewer actually learn the concept?

Tech Selection Guide

Technology Anti-Patterns

• Never use D3 for DOM manipulation in React (use D3 for math, React for rendering)
• Never use Three.js for flat diagrams (SVG is simpler and more accessible)
• Never use CSS keyframe animations for interactive state (can't respond to user input)
• Never use react-spring AND Framer Motion together (pick one animation library)
• Never use force-directed layout for fixed diagrams (compute positions deterministically)

Key Reusable Patterns

Stepper Controller — The single most reusable pattern (used in 30+ visualizations). Prev/Next/Play controls with keyboard support, auto-play, step dots, and haptic feedback. Full implementation in QUICK-REFERENCE.md.

Semantic Colors — Consistent across all visualizations: emerald=success, red=error, amber=warning, cyan=active, sky=info, violet=accent, slate=muted. Color is never the sole indicator — always pair with icons/labels/shapes. Full palette in GOLDEN-THREAD.md.

Spring Physics — Default transitions: { type: "spring", stiffness: 200, damping: 25 }. Snappy: stiffness: 400, damping: 35. Magnetic: stiffness: 150, damping: 15, mass: 0.1. Full configs in QUICK-REFERENCE.md.

Validation Checklist

Before considering any visualization complete:

• Teaches something: A non-expert can explain the concept after interacting
• Works without animation: Meaningful in static/reduced-motion mode
• Desktop interaction: Hover states, keyboard navigation, cursor feedback
• Mobile interaction: Touch targets >= 44px, haptic feedback, no hover-dependent UI
• Performance: Lazy init via IntersectionObserver, RAF for physics, no layout thrashing
• Accessibility: prefers-reduced-motion, ARIA labels, focus indicators, color-not-alone
• Spring-tuned: All motion uses spring physics (not linear/ease), feels natural
• Semantic colors: Consistent with the color system above
• No orphaned animations: All RAF/intervals cleaned up on unmount
• TypeScript types: All props, state, and callbacks fully typed

References