Visualization

Making the invisible visible — structure, state, data, or process rendered so the eye can do the parsing. The umbrella for the whole family: data viz (quantities → position/length/color), diagrams (structure → boxes and arrows), dashboards (state → layout), and Infrastructure diagrams (topology → canvas). The unifying claim: vision is the highest-bandwidth sense humans have, and a good visualization is pre-attentive computation — the brain answers “where is the spike / which node is hot / what depends on what” before conscious reading starts.

What separates good from decorative, in one line each:

• Encode the comparison you care about — position and length beat area and color; the “lie factor” (graphic distortion vs data distortion) must stay near 1 (Tufte’s discipline)
• Maximize data-ink — delete what isn’t data before decorating what is (Performance engineering’s elimination ladder, applied to pixels)
• One chart, one question — if the viewer must hold two questions, it’s two charts
• Show the baseline — a sparkline without its range is decoration; a flame graph without the full stack is a lie about where time goes

HTML as the agent-to-human channel

Claude Code team’s own practice (“The Unreasonable Effectiveness of HTML”, captured → clippings/claude-dev-blog-using-claude-code-the-unreasonable-effectiveness-of-html.md): Markdown has become the dominant agent→human format, but it’s now the bottleneck — “I tend to not actually read more than a 100-line Markdown file, and I certainly am not able to get anyone else in my organization to read it.” HTML wins on information density (tables, design, illustrations, code, interaction, workflows, spatial layout, images in one file), shareability (browsers render it natively; “the chance of someone actually reading your spec is much higher”), and — the distinctive one — two-way interaction: sliders/knobs in the document that adjust a design and emit a “copy as prompt” payload back into the agent. The loop the viz.h artifacts lane already runs locally; the use-case catalog (specs/planning, code review, design prototypes, reports) is a checklist worth mining.

The craft’s odd truth: visualization is debugging for humans — the same discipline as Performance engineering observability (flame graphs, dashboards) but pointed at understanding, not just operations. The show-me / visual-explainer tools in the Hermes stack are this note’s agent-side manifestation: an agent that can draw the thing can be checked by a human at a glance.

Related: Concepts visualization (the specific style catalog) · Infrastructure diagrams (topology branch) · Markdown Slideshows (visualization-as-presentation) · Performance engineering (flame graphs as the native viz of profiling)

Token economics of the plan format: trq212’s HTML-plans skill

Thariq (@trq212) (749❤ / 61k views, both tweets captured): a skill that makes better HTML plans in Claude Code — “simple language, shows code snippets, surfaces questions & makes mockups. Linting reduces the normal failure cases.” The follow-up carries the economics argument: “a big advantage of doing planning like this is that it’s a lot more token efficient compared to raw HTML — the model doesn’t need to remake the components or logic to do common things like state machines, diagrams, code snippets.” That completes the family’s cost ledger: claude.dev argued HTML beats Markdown for agent→human output; answer-me-with-html quantified it (6.1× fewer tokens); trq212 adds the missing half — plan-side components (mockups, state machines, diagrams) as reusable primitives instead of regenerated raw HTML each time. Kin: plannotator (OSS) (review surface on the plan), the technical-manual pattern (grounded generation; exemplar PDFs in _research/assets/), Vibecoding vs AI engineering retro→plan pipeline.

Corroboration from HumanLayer (dexhorthy, 77❤ — captured): “this looks a lot like the ‘outline’ skill we bundle with humanlayer that mixes in /show-me with a planning language. I like the mix-in of HTML for questions and interactive diagrams. The questions → clipboard pipeline is cool.” Independent shop converging on the same shape = plan-language + HTML questions/diagrams is becoming a genre, not a one-off.

Input-side economics: mdream, HTML→Markdown for LLMs (2026-10-07)

mdream (OSS) (975★ TypeScript/Rust, MIT; captured): “the fastest HTML to markdown convertor on GitHub. Optimized for LLMs and supports streaming” — up to 92% token reduction vs raw HTML; GFM output (frontmatter, tables, code blocks); streaming conversion (“convert HTML as input arrives and join the output to match one-shot”); Rust NAPI + WASM/edge + pure-JS engines; powers Cloudflare Browser Run’s /markdown and /crawl endpoints; site-wide llms.txt generation via crawler/Docker/Vite/GitHub Action. This note’s ledger has covered output-side economy (answer-me HTML, trq212 primitives) — mdream is the input-side sibling: the same content/chrome split, applied to what agents read rather than what they emit. Kin: CLIs for agents (feeding agents efficiently), Markdown won (the durable-text-layer thesis, now with an engine), Code Mode’s structural-ingestion argument.