coco-research Visual Explainer
Generate self-contained HTML pages that explain systems, code changes, plans, data, and technical concepts visually. Use this skill for diagram requests, architecture overviews, diff/plan reviews, project recaps, comparison tables, slide decks, and any visual explanation.
Trigger and delivery rules
- Prefer an HTML page over terminal ASCII when the output is inherently visual.
- If a table would have 4+ rows or 3+ columns, render it as HTML and give only a short chat summary.
- Write files to
~/.agent/diagrams/or the explicit eval output path. Use descriptive filenames. - Open generated pages in the browser when running normally. In Pi package installs, use
visual_explainerwithpreparefor planning/context andrenderonly after the complete HTML document exists. - The final page must be a complete self-contained HTML document, including embedded CSS and any needed JS.
Reference routing
Read only the references needed for the current output:
| Need | Read |
|---|---|
| Text-heavy architecture/cards | ./templates/architecture.html |
| Mermaid flowcharts, sequence, ER, state, class, C4, data flow | ./templates/mermaid-flowchart.html, Mermaid sections in ./references/libraries.md |
| Data tables, comparisons, audits | ./templates/data-table.html |
| Slide decks | ./templates/slide-deck.html, ./references/slide-patterns.md |
| CSS layout, overflow, depth, collapsibles, SVG connectors, generated images | ./references/css-patterns.md |
| Pages with 4+ major sections | ./references/responsive-nav.md |
| Prose-heavy pages | “Prose Page Elements” in css-patterns.md, typography sections in libraries.md |
Choose the representation
| Content | Default representation |
|---|---|
| Flowchart, pipeline, state machine, decision tree | Mermaid |
| Sequence, ER/schema, class, C4, topology-focused architecture | Mermaid |
| Text-heavy architecture, module internals, implementation plans | CSS grid cards, optionally with a Mermaid overview |
| 15+ element architecture | Hybrid: small Mermaid overview + CSS detail cards |
| Comparison/audit/status matrix | Semantic HTML <table> |
| Timeline/roadmap | CSS timeline |
| Dashboard/metrics | CSS grid + charts/KPIs |
| Slide deck | 100dvh slides using slide template patterns |
Mermaid invariants
- Use
theme: 'base'with customthemeVariablesmatching the page palette. - For complex diagrams use ELK layout when available.
- Never use bare
<pre class="mermaid">. - Use the canonical
diagram-shellpattern fromtemplates/mermaid-flowchart.html:.diagram-shell>.mermaid-wrap>.zoom-controls+.mermaid-viewport>.mermaid-canvas. - Every Mermaid diagram needs zoom in/out/reset/expand controls, Ctrl/Cmd+scroll zoom, drag panning, and click-to-expand.
- Prefer
flowchart TDfor complex diagrams. UseLRonly for simple 3–4 node linear flows. - Use
<br/>in quoted flowchart labels. Do not use escaped\nlabels. - Never define page-level
.node; Mermaid uses it internally. Use namespaced page classes such as.ve-card. - For 15+ elements, do not cram everything into one Mermaid diagram. Use the hybrid overview + cards pattern.
Layout and style invariants
- Use semantic HTML where it helps accessibility and copy/paste:
<table>, headings, lists,<details>, captions. - Use CSS custom properties for palette:
--bg,--surface,--border,--text,--text-dim, and 3–5 accents. - Pick a clear aesthetic direction before writing: blueprint, editorial, paper/ink, terminal, IDE-inspired, or data-dense.
- Avoid generic defaults: no body font that is only Inter, Roboto, Arial, Helvetica, or system-ui; no violet/fuchsia Tailwind-default accents as the main palette (
#8b5cf6,#7c3aed,#a78bfa,#d946ef); no cyan+magenta+purple neon dashboard; no gradient-mesh blobs. - Good font pair families: DM Sans + Fira Code; Instrument Serif + JetBrains Mono; IBM Plex Sans + IBM Plex Mono; Bricolage Grotesque + Fragment Mono; Plus Jakarta Sans + Azeret Mono.
- Good accent directions: terracotta+sage, teal+slate, rose+cranberry, amber+emerald, deep blue+gold.
- Prevent overflow:
min-width: 0on grid/flex children,overflow-wrap: break-wordfor long text, and scroll containers for wide tables/code. - Do not set
display: flexdirectly on<li>when list markers matter. - Use depth sparingly: hero/elevated only for primary sections; flat/recessed for reference material.
- Use entrance/hover animation only when it clarifies hierarchy. Respect
prefers-reduced-motion. Do not use continuous glow, pulse, or breathing effects on static content.
Slide deck mode
Use slides only when explicitly requested or when a command asks for slides. Slides are a different medium, not a paginated article:
- Each slide is one viewport (
100dvh) with no page-level scrolling. - Use larger type, fewer objects per slide, varied compositions, and visible navigation.
- Include slide nav chrome from
slide-deck.html: prev/next controls, slide count, keyboard navigation, and carousel dots/indicators. - Before writing HTML, inventory the source and map every source item to slides.
- Do not drop content to fit a fixed slide count. Add slides instead.
- Use the 10 slide types from
slide-patterns.md: Title, Section Divider, Content, Split, Diagram, Dashboard, Table, Code, Quote, Full-Bleed.
Optional generated images
If surf is available, generated images may be embedded as base64 for hero banners, conceptual illustrations, or educational visuals. Skip images for data-heavy, structural, or Mermaid/CSS-suitable content. Pages must stand on CSS, typography, and diagrams without images.
Final checklist
Before delivery, verify:
- complete HTML document;
- output written to the requested path;
- no console errors when opened;
- no horizontal overflow at normal desktop width;
- fonts load with fallbacks;
- tables preserve rows/columns and wrap long text;
- Mermaid diagrams use
diagram-shellwith zoom/pan/expand; - slides fit one viewport, include carousel dots, and preserve source coverage;
- visual hierarchy makes the main idea obvious in the first viewport;
- styling would still be recognizable if compared against a generic dark/violet template.