# Visual Explainer

> A Claude skill from vrajasekaran/claude-skills.

- **Type:** Skill
- **Install:** `agentstack add skill-vrajasekaran-claude-skills-visual-explainer`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [vrajasekaran](https://agentstack.voostack.com/s/vrajasekaran)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [vrajasekaran](https://github.com/vrajasekaran)
- **Source:** https://github.com/vrajasekaran/claude-skills/tree/master/skills/visual-explainer

## Install

```sh
agentstack add skill-vrajasekaran-claude-skills-visual-explainer
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

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
```css
.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:
```javascript
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:
```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](https://github.com/vrajasekaran)
- **Source:** [vrajasekaran/claude-skills](https://github.com/vrajasekaran/claude-skills)
- **License:** MIT

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-vrajasekaran-claude-skills-visual-explainer
- Seller: https://agentstack.voostack.com/s/vrajasekaran
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.