antoniocascais Visual Explainer
Turn dense conversation content into ONE self-contained light-themed HTML page optimized for fast visual comprehension. The audience is a senior DevOps/SRE engineer — technical/architecture rendering matters most.
Output contract (non-negotiable)
- One file. A single
.htmlwith ALL CSS and JS inlined. Zero external dependencies — no CDN links, no web fonts pulled over the network, no JS libraries. Must open by double-clicking. - Location. Write to
/tmp/with a descriptive kebab-case filename, e.g./tmp/k8s-ingress-tradeoffs.html. - Diagrams are built with inline SVG or styled HTML/CSS — never an external diagramming lib.
- After writing, report the absolute file path. Do NOT auto-open or start a server.
Workflow
- Source the content. By default, use the relevant content from the current conversation (the brainstorm/wall-of-text just produced). If the user points at a file, Read it. Use
$ARGUMENTSas a topic/focus hint if provided. - Decompose into chunks. Break the content into logical sections. For each chunk, pick the best visual format (see mapping below).
- Build from the design system. Start from
assets/template.html— it has the full inline CSS design system and JS for tabs/accordions. Copy component patterns from it and fromreferences/content-shapes.md. Do not invent a new style; reuse the system so output is consistent. - Adapt density. Use collapsible
<details>accordions or tabs where they cut clutter (long detail, alternatives, deep-dives). Keep content static and visible where scanning is better (summaries, key tables, the main diagram). - Lead with a summary. Top of page = a short orienting summary + key-insight callout(s). Then drill into detail. Highlight key terms inline.
- Write + report. Write the file to
/tmp/, then give the user the path.
Picking the right visual format
Match each content chunk to a format. Full snippets in references/content-shapes.md.
| Content shape | Use |
|---|---|
| System/architecture, data flow, request path | Inline-SVG or CSS box-and-arrow diagram |
| Sequential process, runbook, pipeline stages | Stepper / numbered flow |
| Options, tradeoffs, "X vs Y", decision | Comparison table or pros/cons grid + recommendation callout |
| Distinct concepts / components at same level | Card grid |
| Caveats, gotchas, key takeaways, warnings | Callout boxes (note / tip / warning / key-insight) |
| Hierarchy, taxonomy, mind-map | Nested CSS tree or radial mind-map |
| Long detail behind a summary | <details> accordion or tabs |
| Definitions / mental models | Card with highlighted key term + short body |
Design principles
- Light, clean, minimal. White/near-white background, generous whitespace, restrained accent palette, strong typography hierarchy. Docs-site feel, not a dashboard.
- Scannable. A reader should grasp the structure in ~5 seconds: clear headings, a sticky/visible section nav or TOC for longer pages, consistent component styling.
- Color carries meaning. Reserve accent colors for callout semantics (info/tip/warn/insight) and diagram emphasis — don't decorate randomly.
- Self-contained fonts. Use a system font stack; never fetch web fonts.
See references/content-shapes.md for the component library and assets/template.html for the base.