Visual-Explainer Skill Report

comprehensive skill analysis & documentation

A visual-explainer agent skill that transforms complex terminal output into styled HTML pages. Replaces ASCII art and box-drawing tables with professional diagrams, interactive Mermaid charts, and readable typography.

      graph TD
        A[Why Use It] --> B[ASCII Art]
        A --> C[Bad Tables]

        B -->|1-3 nodes| D[Acceptable]
        B -->|>5 nodes| E[Unreadable]
        C -->|4+ rows/cols| F[Painful]

        G[Solution] --> H[Styled HTML]
        H --> I[Mermaid Diagrams]
        H --> J[Typography]
        H --> K[Zoom Controls]

        L[Commands] --> M[/generate-web-diagram]
        L --> N[/generate-visual-plan]
        L --> O[/diff-review]
        L --> P[/plan-review]
        L --> Q[/project-recap]
        L --> R[/fact-check]

🏗️ Core Structure

The skill operates on a SKILL.md workflow document that defines design principles, routing logic, and quality checkpoints. It reads from multiple reference files to absorb a diverse design vocabulary without repetition.

      flowchart TD
        A[SKILL.md
workflow + design principles]
        A --> B[references/]
        B --> C[css-patterns.md
layouts, animations, theming]
        B --> D[libraries.md
Mermaid, Chart.js, fonts]
        B --> E[responsive-nav.md
sticky TOC for multi-section pages]
        B --> F[slide-patterns.md
slide engine, transitions, presets]

        A --> G[templates/]
        G --> H[architecture.html
CSS Grid architecture layout]
        G --> I[mermaid-flowchart.html
Mermaid diagrams with zoom]
        G --> J[data-table.html
HTML table with KPI cards]
        G --> K[slide-deck.html
10 slide types]

        A --> L[~/.agent/diagrams/
output directory]

📊 Diagram Types (11)

Flowchart

General-purpose flowcharts with decisions and branching

Gantt / Schedule

Project timelines and task scheduling

ER Diagram

Entity-relationship models with cardinality

Mind Map

Branching diagrams for concepts and breakdowns

Class Diagram

Object-oriented class structures with inheritance

Network

Node and edge topology visualizations

State Machine

State transitions and lifecycle diagrams

YAML + JSON

Embedded configuration visualization

Timeline

Historical progression and version history

Mermaid

Direct Mermaid rendering with zoom controls

Dashboard

Chart.js visualizations with KPI cards

🎨 Aesthetic Directions (9)

Monochrome Terminal

Editorial

Blueprint

Neon

Paper / Ink

Sketch

IDE‑Inspired

Data‑Dense

Gradient Mesh

      Color Palette Constraint: Indigo/violet (#8b5cf6, #7c3aed, #a78bfa) and #d946ef (fuchsia) are forbidden. Use teal, slate, amber, emerald, or safe palette alternatives instead.
    

⚡ Slash Commands

Command	Purpose	Flag
/generate-web-diagram	General-purpose HTML diagram generator
/generate-visual-plan	Blueprint-style feature implementation plans
/generate-slides	Magazine-quality slide deck presentations
/diff-review	Visual code diff review with panels and code review	--slides (slide mode)
/plan-review	Plan vs codebase with architecture comparison	--slides (slide mode)
/project-recap	Quick mental-model snapshot for context-switching	--slides (slide mode)
/fact-check	Document accuracy verification vs actual code

🔮 Mermaid Deep Theming

Always use theme: 'base' to enable full variable customization. Preload dark mode via prefers-color-scheme and apply CSS overrides to prevent hard-coded colors from breaking in the opposite theme.

Setting	Value	Notes
theme	base	Enables all themeVariables
look	classic	Clean lines, no fill
layout	elk	For complex graphs (>15 nodes)
fontSize	16px	Default scaling
zoom	CSS zoom	Fixed in v0.4.3

      Forbidden in themeVariables: Indigo/violet colors that hardcode text color. Use CSS overrides for .nodeLabel, .edgeLabel, and .actor to ensure theme-switching reliability.
    

📜 Version History

[0.4.3] — 2026-03-01

Mermaid Zoom Fix

- Replaced transform: scale() with CSS zoom property for proper overflow scrolling in all directions
- Changed align-items from flex-start to center for vertical diagram centering
- Added min-height: 400px to prevent vertical flowchart compression
- Removed unnecessary .mermaid-inner wrapper

[0.3.0] — 2026-02-26

Anti-Slop Guardrails

- Added explicit "Anti-Patterns (AI Slop)" section with forbidden patterns
- Categorized aesthetics as "Constrained" (safer) vs "Flexible" (use caution)
- Explicit forbidden fonts: Inter, Roboto, Arial, Helvetica, system-ui alone
- Added "The Slop Test" — 7-point checklist for quality validation

[0.2.0] — 2026-02-25

Slide Deck Mode

- 10 slide types: Title, Divider, Content, Split, Diagram, Dashboard, Table, Code, Quote, Full-Bleed
- Cinematic transitions with staggered child reveals
- 4 curated presets: Midnight Editorial, Warm Signal, Terminal Mono, Swiss Clean
- New /generate-slides prompt template

[0.1.0] — 2026-02-16

Initial Release

- 11 diagram types with rendering approach routing
- 9 aesthetic directions with Mermaid deep theming
- Proactive table rendering instead of ASCII
- Optional AI-generated illustrations via surf-cli

Diagram Types

Aesthetics

Commands

Slide Presets

📚 Libraries & Typography

Chart.js

Bar, line, pie/doughnut, radar charts; optional sparklines

Anime.js

Staggered reveals, path drawing, count-up numbers

Google Fonts

13 font pairings, display + mono, optically sized for reading

      Typography by Content Voice: Match fonts to prose voice (literary vs technical vs bold vs minimal). Prefer Literata for screen reading.
    

      flowchart LR
        A[Install] --> B[Pi]
        A --> C[Claude Code]

        B -->|pi install
visual-explainer| D[Automatic Setup]

        C -->|Git clone
& copy commands| D

        D --> E[~/.claude/skills/
visual-explainer]
        E --> F[~/.claude/commands/
_*.md]

✅ Quality Checklist (The Slop Test)

12px font min Color+shape Overflow protection Zoom controls Reduced motion No gradients on text No emoji headers Dark mode active

Generated from visual-explainer SKILL.md and reference documentation