ring:visualizing

What this skill does

# 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 diff review, plan review, project recap, or dashboard visualization

## Skip when
- User needs a lightweight, shareable mermaid.live URL (visualize generates self-contained HTML, not mermaid.live links)
- 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, 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.

## 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 diagram-specific template:
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) | `./templates/mermaid-flowchart.html` | `./references/libraries.md`, `./references/css-patterns.md`, `./references/components.md` |
| Data tables / comparisons | `./templates/data-table.html` | `./references/css-patterns.md`, `./references/components.md` |
| Code diffs / reviews | `./templates/code-diff.html` | `./references/css-patterns.md`, `./references/libraries.md`, `./references/responsive-nav.md`, `./references/components.md` |
| Any page with 4+ sections | - | `./references/responsive-nav.md` |
| Any page using CDN libraries | - | `./references/libraries.md` (NEVER use CDN URLs from memory) |

### 3. Diagram types reference

| Type | Rendering approach |
|---|---|
| Architecture (connections matter) | **Mermaid** `graph TD/LR` with `themeVariables` |
| Architecture (rich card content) | CSS Grid cards + flow arrows |
| Flowchart / pipeline | **Mermaid** `graph TD/LR` |
| Sequence diagram | **Mermaid** `sequenceDiagram` |
| ER / schema | **Mermaid** `erDiagram` |
| State machine | **Mermaid** `stateDiagram-v2` (simple labels) or `flowchart LR` (special chars) |
| Mind map | **Mermaid** `mindmap` |
| Data table / comparison | HTML `<table>` (semantic, accessible, copy-paste) |
| Timeline / roadmap | CSS central line + cards |
| Dashboard / metrics | CSS Grid + Chart.js (CDN from libraries.md) |
| Code diff / change review | `@pierre/diffs` (MANDATORY - no hand-rolled CSS diff panels) |

**Mermaid:** Always use `theme: 'base'` with custom `themeVariables` matching the Lerian palette. Add zoom controls (+/-/reset + Ctrl+scroll) to every `.mermaid-wrap`. Copy pattern from `./references/css-patterns.md`.

**Code diffs:** MUST use `@pierre/diffs` from `./references/libraries.md`. HTML strings embedded in `<script>` blocks: escape `</script>` as `<\/script>`.

**Comparison diagrams:** Default to semantic HTML tables, matrices, quadrants, or axis layouts. Generic card grids are banned unless each card encodes materially different, source-backed attributes that cannot be compared more clearly in a table, matrix, quadrant, or axis.

### 4. Mermaid readability gate

- 1-12 nodes: one Mermaid diagram is usually fine.
- 13-20 nodes: use subgraphs, semantic classes, a legend, and explicit critical-path styling.
- 21+ nodes: split into multiple diagrams or a high-level overview plus focused detail diagrams. Zoom is not a readability excuse.
- Node count means real source entities or concepts, not rendered boxes. Do not collapse multiple concepts into overloaded labels to bypass the threshold.
- Use `subgraph` blocks for real domains, layers, ownership, phases, or execution boundaries.
- Use `classDef` and `class` to distinguish semantic roles such as source, decision, risk, critical path, external dependency, datastore, or output.
- Mark the critical path visually and explain it in nearby copy.
- Include a legend when color or stroke means something.
- Keep node labels short. Put explanation in adjacent evidence blocks, not inside giant nodes.

### 5. Style (applied on top of standard template foundation)

- Body font: ALWAYS Inter. MAY add secondary display font for headings only.
- Colors: Use standard template CSS custom properties (`--bg`, `--surface`, `--accent`, etc.). Prefer OKLCH for new raw colors. Do not introduce pure black or pure white hex tokens.
- Backgrounds: choose a physical-scene treatment tied to the content. Restrained product surfaces are the default; richer color must be earned by the data.
- Depth: 3+