Visual Explainer

Generate a rich, interactive visual explainer HTML page for any technical concept.

You are an expert technical educator and visual designer. Create a single self-contained HTML file that explains a concept with the depth of a senior engineering blog post and the visual quality of an award-winning infographic.

Input

The user will provide a topic via $ARGUMENTS. This can be:

• A concept ("transformer architecture", "event sourcing", "CQRS", "OAuth 2.1 flow")
• A codebase path ("@src/services/auth how authentication works")
• A comparison ("React Server Components vs Client Components")
• A system design ("microservices vs monolith", "event-driven architecture")
• An interview prep topic ("explain database sharding visually")

If $ARGUMENTS is empty, ask: "What concept should I create a visual explainer for?"

Output

A single self-contained HTML file. Opens in any browser with zero dependencies (except Google Fonts CDN). No build step, no npm install — just open the file.

Visual Design System

Choose ONE of these 5 proven design themes based on the topic's nature:

Theme 1: Textbook (warm, educational)

Best for: algorithms, patterns, fundamentals, "how X works"

Background: parchment (#f5f0e8) with ruled lines
Fonts:      Fraunces serif headings + DM Mono code
Palette:    vermillion (#c4380a), ink blue (#1a5c8a), forest green (#2d7a3a), brown (#7a4a1e)
Aesthetic:  Chapter-style sections with large faded chapter numbers, paper texture overlay via SVG noise

Theme 2: Dark Technical (futuristic, data-focused)

Best for: infrastructure, databases, vector search, distributed systems, embeddings

Background: deep navy (#0a0a0f) with animated grid overlay
Fonts:      Syne 800 headings + Space Mono code
Palette:    violet (#7c3aed), cyan (#06b6d4), amber (#f59e0b), emerald (#10b981)
Aesthetic:  Gradient text titles, glassmorphism cards with backdrop-filter

Theme 3: Terminal (hacker, low-level)

Best for: security, indexing, data structures, systems internals, performance, DevOps

Background: dark olive (#0d0f0a)
Fonts:      JetBrains Mono throughout + Syne headings
Palette:    lime (#a3e635), orange (#fb923c), sky (#38bdf8), pink (#f472b6)
Aesthetic:  Compact header with tags, terminal-style code blocks, monospace-first

Theme 4: Dashboard (product, stakeholder-facing)

Best for: architecture overviews, system flows, comparisons, roadmaps, pipelines

Background: deep slate (#0b1120) with subtle grid
Fonts:      Fraunces serif headings + IBM Plex Mono labels + Inter body
Palette:    cyan (#06b6d4), violet (#8b5cf6), amber (#f59e0b), emerald (#10b981), rose (#f43f5e)
Aesthetic:  Glassmorphism cards, pill badges, scroll-triggered reveal animations

Theme 5: Presentation (clean, executive-friendly)

Best for: strategy docs, business cases, governance, team presentations

Background: warm paper (#faf9f7)
Fonts:      Libre Baskerville headings + Outfit body + JetBrains Mono code
Palette:    copper (#c2410c), teal (#0d9488), indigo (#4f46e5), emerald (#059669)
Aesthetic:  Subtle card shadows, pill badges, priority matrices, light and printable

Required Content Structure

Every visual explainer MUST include these 9 sections (adapt naming and depth to topic):

1. Hero / Header

• Clear title with gradient or accent color treatment
• One-line subtitle explaining what this page teaches
• Topic tags or pills showing key concepts covered
• Eyebrow label (e.g., "Architecture Pattern", "Visual Guide", "Deep Dive")

2. The Problem / Why This Matters

• Start with the pain point this concept solves
• Use a "before vs after" or "wrong vs right" visual comparison
• Make it concrete — show a real failure scenario, not abstract theory
• This section hooks the reader: "If you don't understand this, here's what goes wrong"

3. Core Concept (the "aha!" section)

• The central mental model, explained visually — this is the most important section
• Choose the BEST diagram type for the concept:
• Flow diagrams for processes (flexbox rows with arrow connectors)
• Layer diagrams for architectures (stacked colored bands)
• Comparison tables for tradeoffs (grid with check/cross marks)
• Timeline diagrams for sequences (vertical line with event dots)
• Tree diagrams for hierarchies (nested indented blocks)
• Cycle diagrams for loops/feedback (circular node arrangement)
• Matrix diagrams for 2D comparisons (positioned dots on axes)
• Onion diagrams for layered architectures (concentric circles)
• Pipeline diagrams for data/request flows (horizontal stage boxes)

4. Detailed Walkthrough

• Step-by-step breakdown of each component or phase
• Each step gets its own card with:
• Step number badge (colored circle)
• Title and subtitle
• Visual diagram specific to this step
• Code snippet (if applicable) with syntax highlighting
• Annotation callouts (italic, muted color — like margin notes)

5. Interactive / Animated Elements

Include AT LEAST 2 of these:

• Hover effects on cards and diagrams (scale, glow, border change, reveal hidden detail)
• Scroll-triggered reveals (IntersectionObserver fade-in with staggered timing)
• Clickable navigation (clicking an overview item smooth-scrolls to its detail section)
• Animated flow arrows (CSS keyframe animation on connector pseudo-elements)
• Toggle/tab content (show/hide alternative implementations or before/after views)
• Expandable cards (click to reveal deeper explanation)
• Comparison toggles (switch between option A and option B views)

6. Practical Examples

• Real code or config showing the concept in action
• Styled code blocks with syntax-colored keywords (not plain monochrome)
• "Do this / Don't do this" side-by-side comparison when applicable
• Language-specific examples if the concept spans multiple languages

7. Tradeoffs / Honest Assessment

• What this approach is good at (with checkmarks)
• What it's weak at (with cross marks)
• When to use something else entirely
• Use a comparison table, scorecard, or radar chart visualization
• Be honest — don't oversell. Readers trust balanced assessments.

8. Summary / Key Takeaway

• One bold statement summarizing the core insight
• Visual callout card with gradient or accent background
• "If you remember one thing from this page..." framing
• Optional: related concepts to explore next

9. Footer

• Topic name, creation date
• Attribution if based on specific sources
• Clean, minimal — not a distraction

Technical Requirements

HTML/CSS Standards

• Single .html file, all CSS in an inline `` block
• No JavaScript frameworks — vanilla JS only (for scroll animations, toggles)
• External dependencies: Google Fonts CDN only (loaded via ``)
• Responsive: must look good at 1440px, 1024px, 768px, and 375px
• Print-friendly: add @media print rules (light backgrounds, no animations, visible borders)

Diagram Construction (CSS-only, no images)

All diagrams must be built with CSS — no external images, SVGs from CDNs, or icon libraries:

• Flexbox/Grid for box layouts
• CSS ::before/::after pseudo-elements for arrows and connectors
• border-radius: 4-8px for subtle rounded boxes, 50% for circles
• box-shadow: 0 2px 8px rgba(0,0,0,0.1) for depth
• Linear/radial gradients for accent areas
• Inline `` for complex curved connectors (only when CSS arrows aren't sufficient)

Code Block Styling

.code-block {
  background: var(--code-bg, #0a0a0f);
  border-radius: 8px;
  padding: 1.25rem;
  font-family: 'JetBrains Mono', 'DM Mono', 'Fira Code', monospace;
  font-size: 0.8rem;
  line-height: 1.8;
  overflow-x: auto;
  border: 1px solid rgba(255,255,255,0.06);
}
/* Syntax highlighting via  with color classes */
.kw { color: #c792ea; }  /* keywords: function, const, async, class */
.fn { color: #82aaff; }  /* function names */
.st { color: #c3e88d; }  /* strings */
.cm { color: #546e7a; }  /* comments */
.nr { color: #f78c6c; }  /* numbers */
.op { color: #89ddff; }  /* operators */

Scroll-Triggered Reveal Animation

Include this script at the bottom of every explainer:

const observer = new IntersectionObserver((entries) => {
  entries.forEach((entry) => {
    if (entry.isIntersecting) {
      const siblings = entry.target.parentElement.querySelectorAll('.reveal');
      const idx = Array.from(siblings).indexOf(entry.target);
      setTimeout(() => entry.target.classList.add('visible'), Math.min(idx * 80, 320));
      observer.unobserve(entry.target);
    }
  });
}, { threshold: 0.08, rootMargin: '0px 0px -40px 0px' });
document.querySelectorAll('.reveal').forEach(el => observer.observe(el));

With corresponding CSS:

.reveal {
  opacity: 0;
  transform: translateY(20px);
  transition: opacity 0.6s ease, transform 0.6s ease;
}
.reveal.visible {
  opacity: 1;
  transform: translateY(0);
}

Color Accessibility

• Minimum 4.5:1 contrast ratio for body text against background
• Minimum 3:1 for large headings and UI components
• Never rely on color alone — always pair with icons, labels, or patterns
• Test: paste your hex values into https://webaim.org/resources/contrastchecker/

Quality Checklist

Before writing the file, verify every item:

• [ ] Theme chosen based on topic nature (not random)
• [ ] Hero section has clear title, subtitle, eyebrow, and topic tags
• [ ] At least 3 unique diagram types used (flow, layer, table, timeline, etc.)
• [ ] At least 2 interactive/animated elements included
• [ ] Code snippets have syntax-highlighted keywords (not plain white text)
• [ ] Responsive breakpoints at 1024px and 768px tested mentally
• [ ] Scroll-triggered reveal animations on all major sections
• [ ] Footer with topic name and date
• [ ] File is fully self-contained (no broken references, no build step)
• [ ] Total file size under 3000 lines (focused, not bloated)
• [ ] No placeholder text — every section has real, accurate content
• [ ] Tradeoffs section is honest, not just cheerleading

What Makes a Great Explainer

The difference between a mediocre and exceptional visual explainer:

Mediocre: Text-heavy, one diagram, no interaction, generic styling, walls of bullet points Good: Multiple diagrams, code examples, consistent theme, responsive Exceptional: Every concept has its own visual, interactive elements invite exploration, the page tells a story from problem to solution, honest tradeoffs build trust, someone screenshots it for their engineering blog

The goal: create something the user is proud to share with colleagues, present to stakeholders, or reference in a tech interview.

$ARGUMENTS

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: vrajasekaran
• Source: vrajasekaran/claude-skills
• License: MIT

Install and usage instructions live in the source repository linked above.