Concepts visualization

The specific craft of visualizing concepts — workflows, mental models, architectures — rather than data. The catalog of styles that work, with named references:

The Yarchi editorial spec-sheet style ★

The favorite (2026-10-03): @undefinedKi (Yarchi)‘s infographic for Addy Osmani’s agent setup (clippings/x-2106049676621308223.md, image archived at assets/visualization/yarchi-agent-setup.jpg). The style grammar, deconstructed:

• Vertical numbered pipeline — stages flow top-to-bottom (01 Define → 06 Ship), thin connector arrows; the reading order is never ambiguous
• Editorial typographic pairing — serif display for titles/headlines, monospace for anything a machine touches (commands, files, outputs), letter-spaced small caps for labels (“WRITES”, “OUTPUTS”)
• Cream/off-white paper ground — near-black strokes, generous whitespace; the “engineering spec sheet” register, not the SaaS-landing-page gradient register
• One muted accent — brick red reserved for the semantic spine: command pills, feedback loops, the handle
• Side callouts — outputs/exceptions hang off the main flow on dashed connectors, so the spine stays readable and the detail stays attached
• Loops drawn as loops — rework/feedback as dashed arrows that visibly return (Review → Build); control flow is content, not decoration
• Severity via fill — black boxes with white text for the human-approval gate and GO/NO-GO; red/blue/pink tinted fills for stop-conditions and review patterns
• Footer = provenance — repo link left, author handle right, in the graphic itself

Why it works: the format argues — “agentic coding is a gated pipeline, not a chat session” is said by the arrows and gates before any text is read. Every style rule above encodes a claim.

Adjacent styles in the vault

• Infrastructure diagrams — the topology branch (OpenShip’s live canvas, diagram-as-code schools)
• xkcd’s stick-figure minimalism — concepts through narrative strips (xkcd captures)
• Sequence diagrams / statecharts (State machines — Harel’s original point: the diagram was the formalism)
• Hand-drawn / Excalidraw register — the informal twin of the spec-sheet style, lower authority cost, better for drafts

Making them

The reproducibility question: this style is achievable in diagram-as-code (D2, Mermaid with theme work) or HTML/CSS posters — the constraint set above (serif+mono pairing, cream ground, one accent, dashed callouts, drawn loops) is a checklist. KRZ lane: the viz.h artifacts pipeline (homelab HTML artifacts) can host generated spec-sheet posters; the visual-explainer Hermes tools draft them.

Related: Visualization (the umbrella) · Infrastructure diagrams

The substrate lane: @statelyai/graph (David KPiano, 2026-10-07)

DavidKPiano (“If you work with graph data structures — you should”) → graph (OSS) (57★ TypeScript, MIT; captured): the graph library built to power Stately’s visual tooling, now open. Why it lands in this note’s catalog: the diagrams this note catalogues are renderings — this is the data model + algorithm layer underneath: a graph is plain JSON { nodes, edges } (JSON.stringify-able, diffable, worker-sendable; indexed lookups transparently); the model natively carries what diagram tools need (mixed directed/undirected edges, nested nodes, named ports, positions/sizes); 14 format converters (Graphviz DOT, Mermaid, GraphML, D2, React Flow, Cytoscape…) and 8 layout engines (ELK, dagre, Graphviz…); algorithms tested against self-loops/parallel edges and iterative so deep graphs don’t overflow the stack; benchmark wins (100k-node build 9–15× faster than graphology). For the agent-viz lane: a typed, tree-shakable graph layer whose output feeds every rendering family above — the Visualization genre’s “structure → boxes and arrows” branch gets its engine.

K-Plex: the Obsidian-native explorer (2026-10-07)

K-Plex intro video by Zsolt (author’s-channel walkthrough, full transcript captured): an Obsidian plugin + sidecar app rendering the vault graph as an interactive 3D map — modular rendering, filtering, clustering, camera paths, saved views, timeline scrubbing, embeddings import, multiple graphs; the sidecar stores per-vault state so graph weight lives outside the notes themselves. Community excitement at release; roadmap driven by feature requests. For this note’s family (LLM-wiki knowledge bases, concept graphs): the consumer-grade lane — where statelyai/graph is the substrate and this vault’s Quartz publishing is the page, K-Plex is the exploration instrument for the source vault itself. Kin: the map-of-content convention (MoC as the manual index — vault pattern, no note), the understand toolfamily’s knowledge graphs (code-side sibling).

• Instrument sibling: Idea Compass (Zsolt’s ExcaliBrain walkthrough, 7rnsULzez-g) — the thinking discipline these visualization tools serve; directions = typed relations, rendered as a graph view.

oh-my-mermaid: codebases → architecture diagrams via the coding agent itself (2026-10-08)

tom_doerr → oh-my-mermaid (OSS) (2.3k★ TypeScript; tweet + README captured): “AI writes code in seconds. Humans understand it in hours. But skip understanding, the codebase becomes a black box — even to you. omm closes the gap — architecture docs, generated by AI, for humans.” Mechanism: a skill (/omm-scan) the coding agent runs against its own codebase → perspectives (structure, data flow, integrations — different lenses), each a Mermaid diagram + docs fields; nodes recursively analyzed into nested child diagrams (complex → subtree, simple → leaf); the .omm/ filesystem is the tree; omm view renders. For this note’s family: the understand toolfamily mines the graph — omm has the agent author its own map, consumable by the next agent session (the diagram is cached context, not a render). Kin: Meta harness? no — the right kin is the Agent knowledge systems compass-files pattern (generated docs as agent-legible context) and the ghuntley Kodak lesson’s other half: understanding tools for code humans no longer read.

Fluxie: the multi-agent pipeline DAG, praised for its aesthetics (2026-10-08)

Akanoa (2,007❤/216k views — “Je suis choqué comment ça rend bien :D”; 46-s video vision-transcribed into the clipping): Fluxie, a node-graph dashboard for an autonomous multi-agent coding pipeline — Ticket → Architect → Critic (revise loop, “approved in round 3”) → parallel Implementer/Tester packages (model badges: vibe, sonnet, q70b) → Integrate (unit/integration/e2e) → Review as hub-and-spoke (Alignment, Security, Architecture, Production, Testing, Correctness, Codex as second model, orange FIX loop) → Merge gates (PR ready, CI green) → Human avatar makes the final merge. Stage stepper, zoom, state-colored edges. No GitHub repo found — product, not OSS, at capture time. Why it belongs here: it’s this note’s whole family in one artifact — a Meta harness-class pipeline rendered with the Linear/Notion design language (near-black pills, semantic accent colors, thin curved connectors), and the strongest evidence yet that the pipeline DAG is the emerging genre for agent-work observability. USER VERDICT, verbatim: “Great visualization, I like the esthetics.” Kin: oh-my-mermaid (OSS) (code → architecture diagram), LLM evals (the Review hub is the grader families note, visualized), Software engineering in AI era (human-in-the-loop merge gate).

Flowfile: visual ETL that compiles to Polars (2026-10-08)

pycoders → Flowfile (OSS) (374★ Python, MIT; tweet + repo captured): “visual ETL that compiles to Polars” — the bidirectional premise is the design worth studying: code and canvas are two views of the same graph. Build on the canvas (49 node types, live data preview at every node) or write Polars-like Python and open_graph_in_editor() to get the editable flow — and the export lane runs the way this note’s family argues pipelines should: prototype visually, ship a plain script (standard transforms export as pure Polars, import polars as pl as the only import; flows saved as human-readable YAML so version control works). Around the canvas: Delta-backed catalog (versioned tables, time travel, virtual tables storing the query plan with filter pushdown through the flow boundary), SQL editor (Polars SQLContext + Graphic Walker), scheduler, BYO-key AI assistant that builds flows on-canvas (Ollama/local supported), sandboxed Python kernels, custom nodes via community registry (sha256-pinned), embeddable flowfile-editor Vue component, and Pyodide browser demo (Polars in-browser, no install). For the visualization-channel thesis: Flowfile is the data-pipeline genre entry — where oh-my-mermaid maps code and K-Plex maps notes, Flowfile maps dataflows, with the same two-way discipline (visual ↔ code, no lock-in either direction). Household relevance: the COT inventory ETL is Polars (inventory project) — Flowfile is the visual layer that lane never had, with a pure-Polars exit.

Excalidraw CLI: the sketch register gets an agent surface (2026-10-08)

excalidraw (455❤/14k views; thread + repo captured): the official Excalidraw CLI — “for humans and agents.” The pitch names the use case directly: “render Excalidraw diagrams to give better output feedback to your agents.” Shape: workspace management (login/whoami, collections, scenes — table or JSON) + render any .excalidraw file to PNG locally, no account needed; JSON output by default “so it works with jq, shell scripts and AI agents”; npx @excalidraw/cli, Node 22+. For this note’s register lane: the hand-drawn register (line 35 above) now has its CLIs-for-agents entry — the loop this vault keeps assembling closes again: agent emits diagram (Mermaid via oh-my-mermaid, plans via trq212-style HTML), renders it to PNG (excalidraw render, no key), the human looks at the picture and annotates (plannotator/Redline). Visual output feedback as a first-class CLI surface is also the Agent-accessible product pattern in miniature — JSON-default, local-first rendering, agents named in the tagline.

Merman: Mermaid without the browser (2026-10-08)

(USER pointer: mark CLI uses it as its alternative to browser-based mermaid rendering.) merman (OSS) (Latias94, 580★ Rust; captured) — “Mermaid.js, but headless, in Rust.” Parses Mermaid source into a typed semantic model, computes layout, renders SVG natively — “the native path does not start Node.js, Puppeteer, Chromium, or another JavaScript runtime.” Optional features add diagnostics, editor facts, ASCII/Unicode output, PNG/JPEG/PDF. The design stance is host-policy separation: “hosts provide explicit output, theme, viewport, and resource policy; Merman returns an artifact, metadata, or a typed error. Terminal detection, pager interaction, scheduling, caches… belong to the host.” Plus tree-sitter-mermaid as a tolerant grammar for editors. Used by Zed as its Rust Mermaid backend (merged PR 57644), tracking upstream Mermaid 12.1.0. For this note: the missing backend piece of the render loop — where Excalidraw CLI put a drawing format behind a keyless local CLI, merman frees the text-diagram lane from the Chromium tax (oh-my-mermaid’s browser dependency); ASCII output even lands diagrams in the terminal itself. mark (Confluence publishing) uses it as the alternative to browser rendering — the same dependency-shedding move mark (Confluence publishing) lane tooling makes.

crisp-diagrams: the agent skill for branded diagram generation (2026-10-10)

sandrinodm (34❤/8.8k views; tweet + full skill page captured, 48 KB, 200+ example SVGs): a skill — “generating clear and good looking diagrams, using your own brand” — with the reference-corpus method: +200 example diagrams your agent uses as reference. The design space it teaches, visible in the example grid: four themes (Quiet / Pastel / Gradient / Tinted zones) × diagram genres (Scene (flow/architecture), Anatomy (labeled parts), Annotated artifact (a real thing dissected — an OAuth URL with PKCE, a JWT, an HTTP header), Byte layout (UUIDv7/authenticator-flag bytes)) × icon treatment (none / hand-made / badges / cards). The brand mechanism is the keeper: “paste a screenshot of your website or dashboard (or your logo, or a slide) and ask for your colors — the skill picks the accent and group colors from the image, shows a preview, and saves them in a STYLE.md next to your diagrams. Every diagram after that follows it, in light and dark mode.”* No image? “Name a color (‘our brand color is 4b2bb3’) or a theme (‘use pastel from now on’).” The prompts are copy-adapt recipes with explicit constraints (“use these labels word for word”, “thin leader lines that never cross”, per-part color groups). For this note: the skill-packaged version of the vault’s whole render loop — where oh-my-mermaid/merman standardize the engine and Excalidraw CLI the hand-drawn register, crisp-diagrams standardizes the aesthetic contract (brand colors → STYLE.md → every diagram follows) — few-shot-by-example as the teaching method, exactly what Karwatka’s “second person can use it” test asks of an asset.