# Visual Explainer

> Specialist visual-authoring guide for diagrams, dense comparisons, plans, and tables. Decomposes visual requirements into primitives that can render standalone or compose inside lev.now RenderSpec pages.

- Skill: `lev-os/visual-explainer` (Agent Skill, multi-file: 32 files)
- Install (CLI): `npx skillmds@latest add lev-os/visual-explainer`
- Raw SKILL.md: https://api.skillmd.com/api/skills/lev-os/visual-explainer/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- License: MIT
- Author: lev-os (https://skillmd.com/u/lev-os)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/lev-os/visual-explainer

---


# 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`](../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](https://github.com/nicobailon/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:

```bash
# 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:

```css
/* 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.

**Use proactively.** Any time you'd render an ASCII box-drawing table in the terminal, generate an HTML table instead. This includes: requirement audits (request vs plan), feature comparisons, status reports, configuration matrices, test result summaries, dependency lists, permission tables, API endpoint inventories — any structured rows and columns.

Layout patterns:
- Sticky `<thead>` so headers stay visible when scrolling long tables
- Alternating row backgrounds via `tr:nth-child(even)` (subtle, 2-3% lightness shift)
- First column optionally sticky for wide tables with horizontal scroll
- Responsive wrapper with `overflow-x: auto` for tables wider than the viewport
- Column width hints via `<colgroup>` or `th` widths — let text-heavy columns breathe
- Row hover highlight for scanability

Status indicators (use styled `<span>` elements, never emoji):
- Match/pass/yes: colored dot or checkmark with green background
- Gap/fail/no: colored dot or cross with red background
- Partial/warning: amber indicator
- Neutral/info: dim text or muted badge

Cell content:
- Wrap long text naturally — don't truncate or force single-line
- Use `<code>` for technical references within cells
- Secondary detail text in `<small>` with dimmed color
- Keep numeric columns right-aligned with `tabular-nums`

### Timeline / Roadmap Views
Vertical or horizontal timeline with a central line (CSS pseudo-element). Phase markers as circles on the line. Content cards branching left/right (alternating) or all to one side. Date labels on the line. Color progression from past (muted) to future (vivid).

### Comparison / Tradeoff Analysis
For comparing two or more approaches, technologies, designs, or implementations. Use when the user asks to compare, evaluate tradeoffs, or decide between options.

**Structure:**
1. **Hero summary** — the core question being evaluated, in one sentence
2. **Candidates at a glance** — card per option with 2-3 key strengths and the primary tradeoff (use the Before/After panel pattern or card grid)
3. **Dimension-by-dimension breakdown** — data table with candidates as columns, evaluation dimensions as rows. Use the data table template. Status badges (strong/weak/neutral) per cell. Sticky header so candidate names stay visible.
4. **Deep dives** — for the 2-3 most important dimensions, expand with code snippets, diagrams, or concrete examples that go beyond the table summary
5. **Recommendation** — if the context supports one, state it clearly with confidence level and conditions ("Choose X if..., choose Y if...")

**Visual treatment:**
- Use the data table template (`./templates/data-table.html`) as the backbone
- KPI cards above the table summarizing: number of dimensions evaluated, winner count per candidate, overall recommendation
- Color-code candidates consistently throughout (e.g., Option A = teal, Option B = amber) using CSS variables
- Callout boxes for decisive factors that heavily tip the balance

**When to use vs. plain table:** If the comparison is 3 columns and 4 rows, a simple data table is fine. Use this richer structure when there are 5+ dimensions, the decision has real stakes, or the user needs to understand *why* not just *what*.

### Decision / Feedback Capture

Interactive decision-making pages with localStorage persistence. For structured choices where the user needs to evaluate options, record decisions, and export results — without losing progress on reload.

**When to use:** CDO deliberation outputs, architecture decision records, team polls, migration planning, any structured decision set with 5+ items that benefits from persistence.

**Structure:**
1. **Hero section** — title, subtitle with item/bucket counts
2. **Progress bar** — sticky, shows completion percentage
3. **Bucket sections** — decisions grouped by theme (2-6 buckets)
4. **Decision cards** — each with:
   - ID badge + title + wave/priority badge
   - Insight panel (1-2 sentences, key tension)
   - Collapsible detail (deeper analysis, optional)
   - Radio options grid (3 options + "Other" with text input)
   - Notes textarea
5. **Action bar** — sticky bottom with decided count, Reset All, Clear Saved Data, Copy JSON

**Required features (non-negotiable):**
- **localStorage auto-save** — debounced 300ms after any input/change event. Restore on page load. Visual "Saved ✓" indicator near progress bar. See "Form & Persistence Patterns" in `./references/css-patterns.md`
- **Event delegation** — click/input/focus handlers on `document`, not per-element. No DOM re-renders on interaction — toggle classes and update state directly
- **JSON export** — structured output with pageId, timestamp, all decisions with choice labels and notes. Clipboard API with `window.open` fallback
- **Progress tracking** — count of decided items, percentage bar
- **`data-page-id` attribute** — on `<main>` element for unique localStorage key per page instance

**Visual treatment:**
- Each decision card gets a left border accent when decided (green)
- Recommended options get a subtle border highlight (gold/amber)
- Selected options get a distinct background + border color
- Wave badges color-coded by priority tier
- Collapsible details use `<button>` toggle with ▸/▾ indicator

**Template reference:** `./templates/decision.html` — Warm Charcoal + Copper palette, Space Grotesk + IBM Plex Mono. Demonstrates all patterns including localStorage auto-save.

### Interaction Layer

Decision pages support an optional live connection to the Lev daemon for in-browser exec. When the daemon is running on `:9849`, the "Run with Claude" button sends prompts via WebSocket and shows streaming responses inline. When offline, it falls back to clipboard mode (existing v0.7.0 behavior).

**Connection manager** — `LevConnection` object auto-connects to `ws://localhost:9849/exec/stream` on page load. Health check via `/health` endpoint with 2s timeout. Auto-reconnects every 5s on disconnect.

**Connection indicator** — 8px dot in the progress bar area. Green = connected, amber = fallback (clipboard), gray = disconnected.

**Response panel** — Fixed panel above the action bar showing exec output. Copy and dismiss buttons. Appears on successful daemon exec, hidden by default.

**Search + Filter** — Search input with 200ms debounce filters cards by title/insight/detail text. Bucket filter chips toggle visibility per category. "Undecided only" checkbox hides decided cards. All filtering is pure DOM visibility toggling — no re-renders.

**Embed mode** — `?embed=true` query param hides hero, bucket nav, and action bar. Parent frames can request current decisions via `postMessage({ type: 'getDecisions' })`.

**Reference:** `./references/interaction-patterns.md` for full JavaScript patterns and CSS.

### Dashboard / Metrics Overview
Card grid layout. Hero numbers large and prominent. Sparklines via inline SVG `<polyline>`. Progress bars via CSS `linear-gradient` on a div. For real charts (bar, line, pie), use **Chart.js via CDN** (see `./references/libraries.md`). KPI cards with trend indicators (up/down arrows, percentage deltas).

### Implementation Plans

For visualizing implementation plans, extension designs, or feature specifications. The goal is **understanding the approach**, not reading the full source code.

**Don't dump full files.** Displaying entire source files inline overwhelms the page and defeats the purpose of a visual explanation. Instead:
- Show **file structure with descriptions** — list functions/exports with one-line explanations
- Show **key snippets only** — the 5-10 lines that illustrate the core logic
- Use **collapsible sections** for full code if truly needed

**Code blocks require explicit formatting.** Without `white-space: pre-wrap`, code runs together into an unreadable wall. See the "Code Blocks" section in `./references/css-patterns.md` for the correct pattern.

**Structure for implementation plans:**
1. Overview/purpose (what problem does this solve?)
2. Flow diagram (Mermaid or CSS cards)
3. File structure with descriptions (not full code)
4. Key implementation details (snippets)
5. API/interface summary
6. Usage examples

### Documentation (READMEs, Library Docs, API References)

When visualizing documentation, extract structure into visual elements:

| Content | Visual Treatment |
|---------|------------------|
| Features | Card grid (2-3 columns) |
| Install/setup steps | Numbered cards or vertical flow |
| API endpoints/commands | Table with sticky header |
| Config options | Table |
| Architecture | Mermaid diagram or CSS card layout |
| Comparisons | Side-by-side panels or table |
| Warnings/notes | Callout boxes |

Don't just format the prose — transform it. A feature list becomes a card grid. Install steps become a numbered flow. An API reference becomes a table.

### Prose Accent Elements

Use these sparingly within visual pages to highlight key points or provide breathing room. See "Prose Page Elements" in `./references/css-patterns.md` for CSS patterns.

- **Lead paragraph** — larger intro text to set context before diving into cards/grids
- **Pull quote** — highlight a key insight; one per page maximum
- **Callout box** — warnings, tips, important notes
- **Section divider** — visual break between major sections

**When to use:** A visual page explaining an essay might use a lead paragraph for the thesis, then cards for key arguments. A README visualization might use callout boxes for warnings but otherwise stay card/table-focused.

## Slide Deck Mode

An alternative output format for presenting content as a magazine-quality slide presentation instead of a scrollable page. **Opt-in only** — the agent generates slides when the user invokes `/generate-slides`, passes `--slides` to an existing prompt (e.g., `/diff-review --slides`), or explicitly asks for a slide deck. Never auto-select slide format.

**Before generating slides**, read `./references/slide-patterns.md` (engine CSS, slide types, transitions, nav chrome, presets) and `./templates/slide-deck.html` (reference template showing all 10 types). Also read `./references/css-patterns.md` for shared patterns and `./references/libraries.md` for Mermaid/Chart.js theming.

**Slides are not pages reformatted.** They're a different medium. Each slide is exactly one viewport tall (100dvh) with no scrolling. Typography is 2–3× larger. Compositions are bolder. The agent composes a narrative arc (impact → context → deep dive → resolution) rather than mechanically paginating the source.

**Content completeness.** Changing the medium does not mean dropping content. Follow the "Planning a Deck from a Source Document" process in `slide-patterns.md` before writing any HTML: inventory the source, map every item to slides, verify coverage. Every section, decision, data point, specification, and collapsible detail from the source must appear in the deck. If a plan has 7 sections, the deck covers all 7. If there are 6 decisions, present all 6 — not the 2 that fit on one slide. Collapsible details in the source become their own slides. Add more slides rather than cutting content. A 22-slide deck that covers everything beats a 13-slide deck that looks polished but is missing 40% of the source.

**Slide types (10):** Title, Section Divider, Content, Split, Diagram, Dashboard, Table, Code, Quote, Full-Bleed. Each has a defined layout in `slide-patterns.md`. Content that exceeds a slide's density limit splits across multiple slides — never scrolls within a slide.

**Visual richness:** Check `which surf` at the start. If surf-cli is available, generate 2–4 images (title slide background, full-bleed background, optional content illustrations) before writing HTML — see the Proactive Imagery section in `slide-patterns.md` for the workflow. Also use SVG decorative accents, per-slide background gradients, inline sparklines, and small Mermaid diagrams. Visual-first, text-second.

**Compositional variety:** Consecutive slides must vary spatial approach — centered, left-heavy, right-heavy, split, edge-aligned, full-bleed. Three centered slides in a row means push one off-axis.

**Curated presets:** Four slide-specific presets as starting points (Midnight Editorial, Warm Signal, Terminal Mono, Swiss Clean) plus the existing 8 aesthetic directions adapted for slides. Pick one and commit. See `slide-patterns.md` for preset CSS values.

**`--slides` flag on existing prompts:** When a user passes `--slides` to `/diff-review`, `/plan-review`, `/project-recap`, or other prompts, the agent gathers data using the prompt's normal data-gathering instructions, then presents the content as a slide deck instead of a scrollable page. The slide version tells the same story with different structure and pacing — but the same breadth of coverage. Don't use the slide format as an excuse to summarize or skip sections that the scrollable version would have included.

## Standalone File Structure

Standalone diagrams are single self-contained `.html` files. A visual inside Now is represented by normal RenderSpec components; do not wrap the entire page in one `custom-html` element merely to reuse this skeleton. Standalone structure:

```html
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Descriptive Title</title>
  <link href="https://fonts.googleapis.com/css2?family=...&display=swap" rel="stylesheet">
  <style>
    /* CSS custom properties, theme, layout, components — all inline */
  </style>
</head>
<body>
  <!-- Semantic HTML: sections, headings, lists, tables, inline SVG -->
  <!-- No script needed for static CSS-only diagrams -->
  <!-- Optional: <script> for Mermaid, Chart.js, or anime.js when used -->
</body>
</html>
```

## Quality Checks

Before delivering, verify:
- **The squint test**: Blur your eyes. Can you still perceive hierarchy? Are sections visually distinct?
- **The swap test**: Would replacing your fonts and colors with a generic dark theme make this indistinguishable from a template? If yes, push the aesthetic further.
- **Both themes**: Toggle your OS between light and dark mode. Both should look intentional, not broken.
- **Information completeness**: Does the diagram actually convey what the user asked for? Pretty but incomplete is a failure.
- **No overflow**: Resize the browser to different widths. No content should clip or escape its container. Every grid and flex child needs `min-width: 0`. Side-by-side panels need `overflow-wrap: break-word`. Never use `display: flex` on `<li>` for marker characters — it creates anonymous flex items that can't shrink, causing lines with many inline `<code>` badges to overflow. Use absolute positioning for markers instead. See the Overflow Protection section in `./references/css-patterns.md`.
- **Mermaid zoom controls**: Every `.mermaid-wrap` container must have zoom controls (+/−/reset buttons), Ctrl/Cmd+scroll zoom, and click-and-drag panning. Complex diagrams render too small without them. The cursor should change to `grab` when zoomed in and `grabbing` while dragging. See `./references/css-patterns.md` for the full pattern.
- **Printable**: Cmd+P should produce a clean, light-background PDF. Include the print stylesheet from `css-patterns.md`.
- **File opens cleanly**: No console errors, no broken font loads, no layout shifts.

## Anti-Patterns (AI Slop)

These patterns are explicitly forbidden. They signal "AI-generated template" and undermine the skill's purpose of producing distinctive, high-quality diagrams. Review every generated page against this list.

### Typography

**Forbidden fonts as primary `--font-body`:**
- Inter — the single most overused AI default
- Roboto, Arial, Helvetica — generic system fallbacks promoted to primary
- system-ui, sans-serif alone — no character, no intent

**Required:** Pick from the font pairings in `./references/libraries.md`. Every generation should use a different pairing from the last.

### Color Palette

**Forbidden accent colors:**
- Indigo-500/violet-500 (`#8b5cf6`, `#7c3aed`, `#a78bfa`) — Tailwind's default purple range
- The cyan + magenta + pink neon gradient

…(truncated)