explainer-visuals

Explainer Visuals

Create animated, interactive visuals that make complex ideas intuitive.

Philosophy

Great explainer visuals don't just illustrate—they reveal. They show the structure hidden in complexity, the motion implicit in static descriptions, the relationships that words struggle to convey.

Core principles:

• Earned complexity: Start simple, add layers through interaction or animation
• Semantic motion: Movement carries meaning, not just attention
• Readable at rest: The static state communicates the core idea
• Progressive disclosure: Let viewers control depth of exploration

Discovery Process

Before creating any visual, conduct a brief discovery interview using AskUserQuestion. Understand not just WHAT to visualize, but WHY this idea needs visual treatment.

Discovery Questions

Ask 1-2 focused questions from these categories:

Understanding the idea:

• "What's the single most important insight viewers should take away?"
• "What makes this concept hard to explain in words alone?"
• "Is there a common misconception this visual should correct?"

Understanding the context:

• "Where will this appear in your essay? (Opening hook, supporting evidence, climactic reveal, summary)"
• "What's the surrounding content's tone? (Academic, conversational, provocative, instructive)"

Understanding the audience:

• "What does your reader already know about this topic?"
• "Should this feel like a quick insight or an explorable deep-dive?"

Skip discovery only if the user has already provided rich context about their goals.

Visual Format Selection

Choose format based on the nature of the idea:

Concept Type	Optimal Format	Why
Transformation/Change	Morphing animation	Shows before→after as continuous process
Hierarchy/Structure	Zoomable treemap or nested diagram	Reveals layers through interaction
Process/Flow	Stepped animation with scrubber	User controls pace of revelation
Comparison	Side-by-side with synchronized animation	Parallel structure highlights differences
Accumulation/Growth	Building animation	Each element adds to previous
Relationship/Network	Force-directed graph	Reveals emergent structure
Distribution/Proportion	Animated unit chart or waffle	Makes quantities tangible
Cycle/Feedback	Looping animation with entry points	Shows perpetual motion of systems
Timeline/Sequence	Horizontal scroll with annotations	Natural reading direction
Spatial/Geographic	Annotated map with zoom	Grounds abstract in physical
Mental Model	Metaphor-based diagram	Connects abstract to familiar
Trade-off/Tension	Slider-controlled balance	Shows interdependence

Design System

Typography

font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;

--text-hero: 2rem;      /* Single key number or word */
--text-title: 1.25rem;  /* Visual title */
--text-label: 0.875rem; /* Axis labels, annotations */
--text-micro: 0.75rem;  /* Secondary details */

Color Palettes

Minimal (default):

--ink: #1a1a2e;        /* Primary elements */
--ink-light: #4a4a68;  /* Secondary elements */
--accent: #e94560;     /* Single highlight */
--ground: #fafafa;     /* Background */
--ground-alt: #f0f0f5; /* Alternate regions */

Data-rich (when showing categories):

--cat-1: #4e79a7; --cat-2: #f28e2c; --cat-3: #e15759;
--cat-4: #76b7b2; --cat-5: #59a14f; --cat-6: #af7aa1;

Adapt to essay context:

• Technical/analytical → cooler palette, more contrast
• Personal/reflective → warmer palette, softer edges
• Provocative/challenging → bolder accent, higher saturation

Motion Principles

const EASE = {
  standard: 'cubic-bezier(0.4, 0, 0.2, 1)',  // Smooth, natural
  enter: 'cubic-bezier(0, 0, 0.2, 1)',       // Start fast, settle
  exit: 'cubic-bezier(0.4, 0, 1, 1)',        // Start slow, accelerate
  bounce: 'cubic-bezier(0.34, 1.56, 0.64, 1)' // Slight overshoot
};

const DURATION = {
  micro: 100,    // Color, opacity
  fast: 200,     // Small movements
  medium: 350,   // Standard transitions
  slow: 500,     // Large movements
  dramatic: 800  // Major reveals
};

Motion semantics:

• Fade = existence (appear/disappear)
• Scale = importance (emphasize/de-emphasize)
• Translate = relationship (group/separate)
• Morph = identity (transform)
• Rotate = state (toggle, cycle)

Technology Selection

Choose the simplest tool that achieves the effect:

Complexity	Tool	Use When
Simple	Pure CSS	State transitions, hovers, basic transforms
Standard	Vanilla JS + CSS	Sequenced animations, scroll triggers, simple interactions
Complex	GSAP	Timeline sequences, physics, SVG morphing
Data-driven	D3.js	Force layouts, maps, data-bound transitions

For most explainer visuals, vanilla JS + CSS is sufficient.

Code Structure

Every visual is a self-contained HTML file:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Visual: [Concept Name]</title>
  <style>
    *, *::before, *::after { box-sizing: border-box; margin: 0; padding: 0; }
    :root { /* Design tokens */ }
    /* Component styles */
  </style>
</head>
<body>
  <figure class="explainer-visual" role="img" aria-label="[Description]">
    <!-- Visual content -->
    <figcaption class="visually-hidden">[Accessible description]</figcaption>
  </figure>
  <script>
    // Animation and interaction logic
  </script>
</body>
</html>

Accessibility Requirements

.visually-hidden {
  position: absolute; width: 1px; height: 1px;
  padding: 0; margin: -1px; overflow: hidden;
  clip: rect(0, 0, 0, 0); border: 0;
}

@media (prefers-reduced-motion: reduce) {
  *, *::before, *::after {
    animation-duration: 0.01ms !important;
    transition-duration: 0.01ms !important;
  }
}

Every visual must include:

1. role="img" aria-label="..." on container
2. Full text alternative in .visually-hidden caption
3. Respect prefers-reduced-motion
4. Keyboard-accessible interactions
5. Visible focus states

Patterns Reference

See references/patterns.md for implementation patterns:

• Morphing shape transitions
• Scroll-driven storytelling
• Interactive slider diagrams
• Annotated step-through animations
• Force-directed relationship graphs
• Unit/waffle chart animations

Delivery

Output as single HTML file that:

1. Is completely self-contained (inline all CSS/JS)
2. Works when opened directly in browser
3. Can be embedded via iframe
4. Includes comments explaining key decisions

For library-dependent visuals (D3, GSAP), include CDN links with integrity hashes.

Quality Checklist

Before delivering:

• Static state communicates the core idea
• Animation reveals insight, not just decorates
• Interactions are discoverable (cursor hints, hover states)
• Works on mobile (touch-friendly, responsive)
• Reduced motion alternative exists
• Accessible description is complete
• Code is commented for future modification
• File size reasonable (<100KB simple, <500KB complex)