/visualizing

name: ring:visualizing
description: "Generating self-contained, Lerian-branded HTML artifacts — D2 diagrams, comparison tables/matrices, code diffs, dashboards, slide decks, and plan/diff/recap reviews — from mandatory templates, then opening them in the browser. Use for architecture overviews, any table with 4+ rows or 3+ columns, slide presentations, or visual diff/plan/review output. Skip for simple tables that fit the terminal or text-only answers."

Visual explainer

When to use

• User asks for a visual explanation, architecture overview, or comparison table
• About to render a complex ASCII table (4+ rows or 3+ columns) in the terminal
• Need a branded, self-contained HTML visualization with Lerian styling
• User asks for a slide deck or presentation
• User asks for diff review, plan review, project recap, or dashboard visualization

Skip when

• Output is a simple table (fewer than 4 rows and 3 columns) that fits well in terminal
• User explicitly requests plain text or markdown output
• The answer is better as ordinary markdown prose than as a durable artifact

Do not use the markdown/prose skip when the user explicitly asks for visual, diagram, artifact, topology, comparison, map, matrix, quadrant, slides, or axis output. In those cases, generate the visual artifact unless they also explicitly ask for text-only output.

Generate self-contained HTML files for technical diagrams, visualizations, and data tables. Always open the result in the browser. Never fall back to ASCII art when this skill is loaded.

**Proactive table rendering:** If the table has 4+ rows or 3+ columns, use an HTML page. Don't wait for the user to ask.

Diagram engine: D2 (not Mermaid)

Topology/connection diagrams are rendered by the **D2 CLI** to a static inline SVG, then embedded in the page. D2 (ELK/dagre layout) produces clean, deterministic layouts; the SVG is static, so there is no render flicker, no foreignObject breakage, and no theme-refresh bug. Dark/light is baked INTO the SVG by D2.

**Prerequisite — the `d2` binary:**

command -v d2 || brew install d2     # or: curl -fsSL https://d2lang.com/install.sh | sh

If `d2` is not installed and cannot be installed, fall back to CSS-grid card layouts (architecture.html) for structure — never to ASCII art.

**Generation flow:** 1. Write `diagram.d2`, starting with the **Lerian D2 preamble** (in `./templates/diagram.html` and `./references/libraries.md`). 2. `d2 --theme=0 --dark-theme=200 --layout=elk diagram.d2 diagram.svg` 3. Strip the leading `<?xml ...?>` declaration; paste the `<svg>...</svg>` into `.diagram-canvas`. 4. The pan/zoom engine in `diagram.html` is SVG-agnostic — it reads `viewBox` and works as-is.

Standard template (mandatory)

**MUST Read `./templates/standard.html` before generating any HTML.** Copy verbatim: 1. Complete `<style>` block (above "DO NOT MODIFY" marker) 2. `<header class="lerian-header">` with inline Lerian logo SVG 3. `<footer class="lerian-footer">` with logo, company name, "Generated with Ring" 4. Date auto-fill `<script>`

**Fixed (cannot change):** Inter font, Lerian color palette (sunglow accent, zinc neutrals), logo, footer, dark mode. **Variable (customize per diagram):** Layout, secondary display font, background atmosphere, accent emphasis, animations.

Template adaptation rules

• `./templates/standard.html` is the only copy foundation. Start every artifact from its foundation, header, footer, and date script.
• Diagram-specific templates are pattern references only. Borrow structural ideas, not their demo content.
• Never reuse sample titles, entities, metrics, file names, services, flows, status labels, or domain examples unless they are present in the user request or source data.
• Replace every demo label before delivery. If a title or metric would still make sense in an unrelated company, it is probably leaked demo content.
• Do not invent missing facts to make the visual feel complete. Empty space is better than fabricated certainty.

Workflow

1. Build the artifact brief before style

• Audience: who is looking and what decision must they make?
• Physical scene: choose a surface metaphor tied to the work, such as incident war room, ledger workbench, release control room, architecture map table, review desk, or operations console.
• Source facts: list the facts explicitly present in the prompt, files, diff, logs, or source material.
• Entities: name the real systems, files, teams, actors, services, stages, or concepts.
• Relationships: define real dependencies, sequence, ownership, risk, contrast, or causality.
• Hierarchy: identify what deserves visual priority and what should recede.
• One-sentence message: state what the viewer should understand after 10 seconds.
• Non-invention boundary: name what cannot be inferred and must not appear.
• HTML evidence comment: write the artifact brief, visual thesis, and 3+ source-tied design choices into a top-level HTML comment near the top of the generated file, immediately after the template/source comment and before external fonts or styles. Use explicit labels such as `<!-- Artifact brief: ... -->`, `<!-- Visual thesis: ... -->`, and `<!-- Design choices: ... -->`.

2. Structure (must read before writing)

1. Read `./templates/standard.html` (ALWAYS first) 2. Read the diagram-specific template for the selected row below 3. Read `./references/components.md` when the selected diagram row lists it or when composing reusable primitives such as summaries, legends, callouts, findings, comparison matrices, rails, source excerpts, or evidence blocks. Very simple single-diagram artifacts that use no component primitives may skip it only when their selected row does not list it.

| Diagram type | Template to read | Required references | |---|---|---| | Architecture (text-heavy, CSS cards) | `./templates/architecture.html` | `./references/css-patterns.md`, `./references/components.md` | | Architecture / flowchart / topology (D2)