Visual Explainer

Design technical diagrams, visualizations, and data tables. Always open the result in the browser. Never fall back to ASCII art when this skill is loaded.

Relationship to Now

Read ../now/SKILL.md when the request mixes readable content with visuals, teaching, sales copy, feedback, document navigation, publishing, or capability-backed actions. Now owns the canonical RenderSpec component graph; this skill is its specialist visual-authoring path.

• Decompose every request into audience requirements, claims/evidence, reading sequence, visual relationships, and interactions before selecting primitives.
• Treat the command lenses below as research and QA recipes, not page schemas or fixed experiences.
• Prefer ordinary RenderSpec components: diagram, chart, data-table, section, card, code-block, document, navigation, action, and feedback. For educational or persuasive visuals, compose the same graph with objective, source-list, exercise, evidence, decision, proof, or testimonial where those semantics are required.
• Use custom-html only when the graph cannot express a load-bearing visual or interaction. Include typed export metadata so the artifact is not an opaque HTML island.
• A lesson, technical brief, sales letter, reader, and feedback surface can all include the same visual components. Do not force prose out of a visual composition or force a whole request through one visual template.

For educational visuals, apply Teach-quality authoring: ground the explanation in the learner's mission and current knowledge, target one tangible win, source load-bearing claims, reduce acquisition difficulty, and add retrieval/practice/feedback when skill retention matters. Mission/resource/learning-record/glossary files remain content inputs; they never select a lesson route or replace RenderSpec.

Proactive table rendering. When you're about to present tabular data as an ASCII box-drawing table in the terminal (comparisons, audits, feature matrices, status reports, any structured rows/columns), generate an HTML page instead. The threshold: if the table has 4+ rows or 3+ columns, it belongs in the browser. Don't wait for the user to ask — render it as HTML automatically and tell them the file path. You can still include a brief text summary in the chat, but the table itself should be the HTML page.

Command Interface

Single entry point: /visual-explainer <type> [args...] [all|publish]

Everything after /visual-explainer is an arg. The first arg may select a lens for investigation and QA. It does not select a schema or mandatory layout. Remaining args provide context. The last arg can be a quality mode.

Lenses

Type	What it does	Example
diagram	Freeform visual explanation	diagram websocket lifecycle
comparison	Tradeoff analysis between options	comparison rust vs go for cli tools
diff-review	Visual diff review of code changes	diff-review main
plan-review	Plan vs codebase analysis	plan-review ./plan.md
project-recap	Mental model snapshot	project-recap 2w
fact-check	Verify claims against code	fact-check ./diagram.html
slides	Magazine-quality slide deck	slides api design overview
visual-plan	Implementation spec with state machines	visual-plan add caching layer
decision	Interactive decision capture with persistence	decision cdo-s8 architecture decisions

If no lens matches, treat the entire arg string as a visual topic and select primitives after decomposition.

Quality Modes

Appended as the final arg:

Mode	Behavior
(default)	Local only. Generate and open in browser. Standard quality checks (squint, swap, themes, overflow, zoom).
all	Full quality gate. All standard checks + print stylesheet verification + responsive testing (375px, 768px, 1440px) + slop test + fact-check pass on any claims. For thorough local review.
publish	all + publish via here.now. External audience — every quality check runs, then ./skills/here-now/scripts/publish.sh deploys the result. Returns the live URL.

publish implies all. You never publish without running the full gate.

Examples

/visual-explainer comparison sqlite vs postgres for agent memory
/visual-explainer diff-review HEAD all
/visual-explainer diagram kubernetes pod lifecycle publish
/visual-explainer project-recap 30d
/visual-explainer fact-check
/visual-explainer slides visual-explainer skill overview publish

Arg Parsing

1. Split $@ into tokens
2. Match the first token against the lens table (case-insensitive, supports aliases: compare→comparison, diff→diff-review, recap→project-recap, plan→plan-review, check→fact-check, feedback→decision, decide→decision, poll→decision)
3. Pop the last token — if it's publish or all, set quality mode accordingly
4. Everything between type and quality mode is the context/topic args

Workflow

1. Think (5 seconds, not 5 minutes)

Before writing HTML, commit to a direction. Don't default to "dark theme with blue accents" every time.

Visual is always default. Even essays, blog posts, and articles get visual treatment — extract structure into cards, diagrams, grids, tables.

Prose patterns (lead paragraphs, pull quotes, callout boxes) are accent elements within visual pages, not a separate mode. Use them to highlight key points or provide breathing room, but the page structure remains visual.

For prose accents, see "Prose Page Elements" in ./references/css-patterns.md. For everything else, use the standard freeform approach with aesthetic directions below.

Who is looking? A developer understanding a system? A PM seeing the big picture? A team reviewing a proposal? This shapes information density and visual complexity.

What relationships must become visible? Architecture, sequence, causality, data flow, schema/ER, state, hierarchy, comparison, chronology, or metrics each need different primitives. Select per relationship instead of declaring the whole request one content type.

What aesthetic? Pick one and commit. The constrained aesthetics (Blueprint, Editorial, Paper/ink) are safer — they have specific requirements that prevent generic output. The flexible ones (IDE-inspired) require more discipline.

Constrained aesthetics (prefer these):

• Blueprint (technical drawing feel, subtle grid background, deep slate/blue palette, monospace labels, precise borders) — see websocket-implementation-plan.html for reference
• Editorial (serif headlines like Instrument Serif or Crimson Pro, generous whitespace, muted earth tones or deep navy + gold)
• Paper/ink (warm cream #faf7f5 background, terracotta/sage accents, informal feel)
• Monochrome terminal (green/amber on near-black, monospace everything, CRT glow optional)

Flexible aesthetics (use with caution):

• IDE-inspired (borrow a real, named color scheme: Dracula, Nord, Catppuccin Mocha/Latte, Solarized Dark/Light, Gruvbox, One Dark, Rosé Pine) — commit to the actual palette, don't approximate
• Data-dense (small type, tight spacing, maximum information, muted colors)

Explicitly forbidden:

• Neon dashboard (cyan + magenta + purple on dark) — always produces AI slop
• Gradient mesh (pink/purple/cyan blobs) — too generic
• Any combination of Inter font + violet/indigo accents + gradient text

Vary the choice each time. If the last diagram was dark and technical, make the next one light and editorial. The swap test: if you replaced your styling with a generic dark theme and nobody would notice the difference, you haven't designed anything.

2. Structure

Read the reference material before generating. Don't memorize it — read it each time to absorb the patterns.

• For text-heavy architecture overviews (card content matters more than topology): read ./templates/architecture.html
• For flowcharts, ER diagrams, state machines, mind maps, data flows: read ./templates/mermaid-flowchart.html
• For sequence diagrams: read ./templates/sequence-diagram.html
• For data tables, audits, feature matrices: read ./templates/data-table.html
• For comparisons and tradeoff analysis: read ./templates/comparison.html
• For timelines and roadmaps: read ./templates/timeline.html
• For dashboards and metrics pages: read ./templates/dashboard.html
• For implementation plans and feature specs: read ./templates/implementation-plan.html
• For interactive decision/feedback capture: read ./templates/decision.html
• For slide deck presentations (when --slides flag is present or /generate-slides is invoked): read ./templates/slide-deck.html and ./references/slide-patterns.md
• For prose-heavy publishable pages (READMEs, articles, blog posts, essays): read the "Prose Page Elements" section in ./references/css-patterns.md and "Typography by Content Voice" in ./references/libraries.md

For CSS/layout patterns and SVG connectors, read ./references/css-patterns.md.

For pages with 4+ sections (reviews, recaps, dashboards), also read ./references/responsive-nav.md for section navigation with sticky sidebar TOC on desktop and horizontal scrollable bar on mobile.

Choosing a rendering approach:

Content type	Approach	Why
Architecture (text-heavy)	CSS Grid cards + flow arrows	Rich card content (descriptions, code, tool lists) needs CSS control
Architecture (topology-focused)	Mermaid	Visible connections between components need automatic edge routing
Flowchart / pipeline	Mermaid	Automatic node positioning and edge routing
Sequence diagram	Mermaid	Lifelines, messages, and activation boxes need automatic layout
Data flow	Mermaid with edge labels	Connections and data descriptions need automatic edge routing
ER / schema diagram	Mermaid	Relationship lines between many entities need auto-routing
State machine	Mermaid	State transitions with labeled edges need automatic layout
Mind map	Mermaid	Hierarchical branching needs automatic positioning
Data table	HTML <table>	Semantic markup, accessibility, copy-paste behavior
Timeline	CSS (central line + cards)	Simple linear layout doesn't need a layout engine
Dashboard	CSS Grid + Chart.js	Card grid with embedded charts

Mermaid theming: Always use theme: 'base' with custom themeVariables so colors match your page palette. Use layout: 'elk' for complex graphs (requires the @mermaid-js/layout-elk package — see ./references/libraries.md for the CDN import). Override Mermaid's SVG classes with CSS for pixel-perfect control. See ./references/libraries.md for full theming guide.

Mermaid containers: Always center Mermaid diagrams with display: flex; justify-content: center;. Add zoom controls (+/−/reset) to every .mermaid-wrap container.

Mermaid scaling: Diagrams with 10+ nodes render too small by default. For 10-12 nodes, increase fontSize in themeVariables to 18-20px and set INITIAL_ZOOM to 1.5-1.6. For 15+ elements, don't try to scale — use the hybrid pattern instead (simple Mermaid overview + CSS Grid cards). See "Architecture / System Diagrams" below.

Mermaid layout direction: Prefer flowchart TD (top-down) over flowchart LR (left-to-right) for complex diagrams. LR spreads horizontally and makes labels unreadable when there are many nodes. Use LR only for simple 3-4 node linear flows. See ./references/libraries.md "Layout Direction: TD vs LR".

Mermaid CSS class collision constraint: Never define .node as a page-level CSS class. Mermaid.js uses .node internally on SVG <g> elements with transform: translate(x, y) for positioning. Page-level .node styles (hover transforms, box-shadows) leak into diagrams and break layout. Use the namespaced .ve-card class for card components instead. The only safe way to style Mermaid's .node is scoped under .mermaid (e.g., .mermaid .node rect).

AI-generated illustrations (optional). If surf-cli is available, you can generate images via Gemini and embed them in the page for creative, illustrative, explanatory, educational, or decorative purposes. Check availability with which surf. If available:

# Generate to a temp file (use --aspect-ratio for control)
surf gemini "descriptive prompt" --generate-image /tmp/ve-img.png --aspect-ratio 16:9

# Base64 encode for self-containment (macOS)
IMG=$(base64 -i /tmp/ve-img.png)
# Linux: IMG=$(base64 -w 0 /tmp/ve-img.png)

# Embed in HTML and clean up
# <img src="data:image/png;base64,${IMG}" alt="descriptive alt text">
rm /tmp/ve-img.png

See ./references/css-patterns.md for image container styles (hero banners, inline illustrations, captions).

When to use: Hero banners that establish the page's visual tone. Conceptual illustrations for abstract systems that Mermaid can't express (physical infrastructure, user journeys, mental models). Educational diagrams that benefit from artistic or photorealistic rendering. Decorative accents that reinforce the aesthetic.

When to skip: Anything Mermaid or CSS handles well. Generic decoration that doesn't convey meaning. Data-heavy pages where images would distract. Always degrade gracefully — if surf isn't available, skip images without erroring. The page should stand on its own with CSS and typography alone.

Prompt craft: Match the image to the page's palette and aesthetic direction. Specify the style (3D render, technical illustration, watercolor, isometric, flat vector, etc.) and mention dominant colors from your CSS variables. Use --aspect-ratio 16:9 for hero banners, --aspect-ratio 1:1 for inline illustrations. Keep prompts specific — "isometric illustration of a message queue with cyan nodes on dark navy background" beats "a diagram of a queue."

3. Style

Apply these principles to every diagram:

Typography is the diagram. Pick a distinctive font pairing from the list in ./references/libraries.md. Every page should use a different pairing from recent generations.

Forbidden as --font-body: Inter, Roboto, Arial, Helvetica, system-ui alone. These are AI slop signals.

Good pairings (use these):

• DM Sans + Fira Code (technical, precise)
• Instrument Serif + JetBrains Mono (editorial, refined)
• IBM Plex Sans + IBM Plex Mono (reliable, readable)
• Bricolage Grotesque + Fragment Mono (bold, characterful)
• Plus Jakarta Sans + Azeret Mono (rounded, approachable)

Load via <link> in <head>. Include a system font fallback in the font-family stack for offline resilience.

Color tells a story. Use CSS custom properties for the full palette. Define at minimum: --bg, --surface, --border, --text, --text-dim, and 3-5 accent colors. Each accent should have a full and a dim variant (for backgrounds). Name variables semantically when possible (--pipeline-step not --blue-3). Support both themes.

Forbidden accent colors: #8b5cf6 #7c3aed #a78bfa (indigo/violet), #d946ef (fuchsia), the cyan-magenta-pink combination. These are Tailwind defaults that signal zero design intent.

Good accent palettes (use these):

• Terracotta + sage (#c2410c, #65a30d) — warm, earthy
• Teal + slate (#0891b2, #0369a1) — technical, precise
• Rose + cranberry (#be123c, #881337) — editorial, refined
• Amber + emerald (#d97706, #059669) — data-focused
• Deep blue + gold (#1e3a5f, #d4a73a) — premium, sophisticated

Put your primary aesthetic in :root and the alternate in the media query:

/* Light-first (editorial, paper/ink, blueprint): */
:root { /* light values */ }
@media (prefers-color-scheme: dark) { :root { /* dark values */ } }

/* Dark-first (neon, IDE-inspired, terminal): */
:root { /* dark values */ }
@media (prefers-color-scheme: light) { :root { /* light values */ } }

Surfaces whisper, they don't shout. Build depth through subtle lightness shifts (2-4% between levels), not dramatic color changes. Borders should be low-opacity rgba (rgba(255,255,255,0.08) in dark mode, rgba(0,0,0,0.08) in light) — visible when you look, invisible when you don't.

Backgrounds create atmosphere. Don't use flat solid colors for the page background. Subtle gradients, faint grid patterns via CSS, or gentle radial glows behind focal areas. The background should feel like a space, not a void.

Visual weight signals importance. Not every section deserves equal visual treatment. Executive summaries and key metrics should dominate the viewport on load (larger type, more padding, subtle accent-tinted background zone). Reference sections (file maps, dependency lists, decision logs) should be compact and stay out of the way. Use <details>/<summary> for sections that are useful but not primary — the collapsible pattern is in ./references/css-patterns.md.

Surface depth creates hierarchy. Vary card depth to signal what matters. Hero sections get elevated shadows and accent-tinted backgrounds (ve-card--hero pattern). Body content stays flat (default .ve-card). Code blocks and secondary content feel recessed (ve-card--recessed). See the depth tiers in ./references/css-patterns.md. Don't make everything elevated — when everything pops, nothing does.

Animation earns its place. Staggered fade-ins on page load are almost always worth it — they guide the eye through the diagram's hierarchy. Mix animation types by role: fadeUp for cards, fadeScale for KPIs and badges, drawIn for SVG connectors, countUp for hero numbers. Hover transitions on interactive-feeling elements make the diagram feel alive. Always respect prefers-reduced-motion. CSS transitions and keyframes handle most cases. For orchestrated multi-element sequences, anime.js via CDN is available (see ./references/libraries.md).

Forbidden animations:

• Animated glowing box-shadows (@keyframes glow { box-shadow: 0 0 20px... }) — this is AI slop
• Pulsing/breathing effects on static content
• Continuous animations that run after page load (except for progress indicators)

Keep animations purposeful: entrance reveals, hover feedback, and user-initiated interactions. Nothing should glow or pulse on its own.

4. Deliver

Output location: When invoked inside a Now composition, author/update the RenderSpec under ~/.agents/levnow/ and render through plugins/now/src/cli.ts. For a standalone visual-only request, write self-contained HTML to ~/.agents/diagrams/. Use descriptive filenames in either location.

Before delivery, verify requirement coverage: every requested claim, relationship, and interaction must map to a rendered component or an explicitly justified custom-html block.

Quality gate — run the checks for the active quality mode:

Check	Default	all	publish
Squint test	yes	yes	yes
Swap test	yes	yes	yes
Both themes	yes	yes	yes
Info completeness	yes	yes	yes
No overflow	yes	yes	yes
Mermaid zoom controls	yes	yes	yes
Printable (Cmd+P)	—	yes	yes
Responsive (375/768/1440px)	—	yes	yes
Slop test (7-point)	—	yes	yes
Fact-check claims	—	yes	yes
Publish via here.now	—	—	yes

Open in browser:

• macOS: open ~/.agents/diagrams/filename.html
• Linux: xdg-open ~/.agents/diagrams/filename.html

Publish flow (when quality mode is publish):

1. Run all quality checks above
2. Fix any issues found
3. Run ./skills/here-now/scripts/publish.sh ~/.agents/diagrams/filename.html --client visual-explainer
4. Return the live URL to the user

External audience means higher stakes — publish pages get every quality check because a broken diagram at a live URL is worse than a broken diagram on localhost.

Tell the user the file path (and live URL if published) so they can re-open or share it.

Diagram Types

Architecture / System Diagrams

Three approaches depending on complexity:

Simple topology (under 10 elements): Use Mermaid. A graph TD with custom themeVariables produces readable diagrams with automatic edge routing.

Text-heavy overviews (under 15 elements): CSS Grid with explicit row/column placement. Sections as rounded cards with colored borders and monospace labels. Vertical flow arrows between sections. The reference template at ./templates/architecture.html demonstrates this pattern. Use when cards need descriptions, code references, tool lists, or other rich content that Mermaid nodes can't hold.

Complex architectures (15+ elements): Use the hybrid pattern — a simple Mermaid overview (5-8 nodes showing module relationships) followed by detailed CSS Grid cards for each module's internals. This gives you visual topology AND readable details. The overview diagram uses module names with <small> tags for key function names. The cards below show full function lists with new/modified badges. Never try to cram 15+ elements into a single Mermaid diagram — it will render unreadably small even with zoom controls.

Flowcharts / Pipelines

Use Mermaid. Automatic node positioning and edge routing produces proper diagrams with connecting lines, decision diamonds, and parallel branches — dramatically better than CSS flexbox with arrow characters. Prefer graph TD (top-down); use graph LR only for simple 3-4 node linear flows. Color-code node types with Mermaid's classDef or rely on themeVariables for automatic styling.

Sequence Diagrams

Use Mermaid. Lifelines, messages, activation boxes, notes, and loops all need automatic layout. Use Mermaid's sequenceDiagram syntax. Style actors and messages via CSS overrides on .actor, .messageText, .activation classes.

Data Flow Diagrams

Use Mermaid. Data flow diagrams emphasize connections over boxes — exactly what Mermaid excels at. Use graph TD (or graph LR for simple linear flows) with edge labels for data descriptions. Thicker, colored edges for primary flows. Source/sink nodes styled differently from transform nodes via Mermaid's classDef.

Schema / ER Diagrams

Use Mermaid. Relationship lines between entities need automatic routing. Use Mermaid's erDiagram syntax with entity attributes. Style via themeVariables and CSS overrides on .er.entityBox and .er.relationshipLine.

State Machines / Decision Trees

Use Mermaid. Use stateDiagram-v2 for states with labeled transitions. Supports nested states, forks, joins, and notes. Decision trees can use graph TD with diamond decision nodes.

stateDiagram-v2 label caveat: Transition labels have a strict parser — colons, parentheses, <br/>, HTML entities, and most special characters cause silent parse failures ("Syntax error in text"). If your labels need any of these (e.g., cancel(), curate: true, multi-line labels), use flowchart TD instead with rounded nodes and quoted edge labels (|"label text"|). Flowcharts handle all special characters and support <br/> for line breaks. Reserve stateDiagram-v2 for simple single-word or plain-text labels.

Mind Maps / Hierarchical Breakdowns

Use Mermaid. Use mindmap syntax for hierarchical branching from a root node. Mermaid handles the radial layout automatically. Style with themeVariables to control node colors at each depth level.

Data Tables / Comparisons / Audits

Use a real <table> element — not CSS Grid pretending to be a table. Tables get accessibility, copy-paste behavior, and column alignment for free. The reference template at ./templates/data-table.html demonstrates all patterns below.