| name | doc-visual |
| description | Convert any markdown document into a diagram-enriched visual HTML report.
Use when asked to visualize, illustrate, or create a visual report from a document with diagrams. Single md file input.
Also trigger when: "make this document visual", "add diagrams to this doc", "turn this markdown into a report",
"visualize this README/ADR/spec", or any request to render a document with embedded diagrams.
|
| argument-hint | [md-file-path] [--format html|md] [--lang code] [--local (force a local file instead of publishing)] |
| allowed-tools | Read, Bash(node *), Bash(open *), Bash(rm -rf /tmp/doc-visual-*), Artifact, Skill(artifact-design), AskUserQuestion |
doc-visual
Read a markdown document and write a visual report with diagrams that match each section's meaning. Output is HTML (default) or markdown. You write the output directly — no templates, no intermediate JSON, no agent chains.
Why this matters
The previous version of this skill passed text through a pipeline of agents — each one only saw the output of the stage before it. By the time the report was assembled, the original content had been compressed into summaries of summaries. That's the failure mode you're replacing. You see the original document in full. That's the core advantage. If you find yourself writing "this section discusses X" instead of explaining X — that's compression, and it's the exact failure this redesign exists to fix.
Input
Argument = single markdown file path. Directories, URLs, stdin not supported.
- Validate file exists + markdown extension (
.md, .markdown, .txt)
- Missing/no permission → abort immediately
- Read the full file content
Format detection
| Flag | Values | Default |
|---|
--format | html / md | html |
--lang | ISO code | auto-detected from document |
--local | switch | off — capable HTML publishes to an Artifact by default |
--artifact | switch | retained no-op alias (already the default on capable HTML) |
The report language must match the source document's language.
Channel is decided by the shared contract, not re-derived here — read
${CLAUDE_PLUGIN_ROOT}/references/design-system/channel-decision.md (SSOT, restates ADR 0009) for the
(Format × capable) → channel table, flag semantics, and the optimistic-try-then-regenerate rule.
The short version: capable HTML publishes to a claude.ai Artifact by default; --local forces the
local design-system + Mermaid file; md and non-capable sessions stay local.
--local forces local (analytical charts, zoom/pan) and also triggers on natural-language equivalents
— "keep it local", "don't publish", "just the local file" — in whatever language the user writes.
--artifact is the retained alias for the now-default behavior and still triggers on "as an artifact",
"publish as a link", "share as a URL"; if --local and --artifact are both signalled, --local wins.
Config precedence. Explicit this-turn signal > config > default. Before falling back to the
default, check stored preferences once: node ${CLAUDE_PLUGIN_ROOT}/scripts/config.js get (prints the
config as JSON, or {}). A default_format value replaces the html default. For the channel: an
absent artifact key means artifact-first (the default), artifact: false is a persistent
force-local (the config twin of --local), and artifact: true is explicit artifact-first. Anything
the user actually says this turn — a literal flag or a natural-language equivalent — always overrides
config; config only fills in when the request is silent on format/channel.
When the target format is md, whether you ask before publishing depends on how the request arrived:
- Both flags typed literally (
--format md --artifact, exact tokens): that's a deliberate,
informed choice — publish the md file as-is, never ask. See "Markdown format — Artifact channel" below.
- Artifact intent expressed in natural language (no literal
--artifact token) while the target
format is md: check the md content for a ```mermaid fenced block first. None found → publish
as-is, same as the explicit path (nothing would be lost either way, so there's nothing to ask
about). Found one or more → the natural-language phrasing never committed to losing diagram
rendering, so ask once before publishing (see "Markdown format — Artifact channel").
Writing the report
You write the output yourself. No template files, no assembly scripts, no intermediate formats.
HTML channel routing (default = Artifact). For --format html the channel is decided by
${CLAUDE_PLUGIN_ROOT}/references/design-system/channel-decision.md: on a capable account the
default is the Artifact channel — go straight to "HTML format — Artifact channel" below. Write the
local design-system + Mermaid file (the section directly under this one) only when --local is in
play, or as the non-capable regenerate fallback after a publish attempt fails (see "Publish"). md
is unaffected — it stays local either way.
HTML format — local design-system channel (--local / non-capable fallback)
A self-contained single file — <!DOCTYPE html> to </html>:
- Inline
<style> block with all CSS
- Inline
<script> for Mermaid CDN import and initialization
- Semantic HTML structure: sections that follow the source document's structure
- Diagrams embedded as
<pre class="mermaid"> blocks
HTML format — Artifact channel (default on a capable account)
This is the default for --format html (ADR 0009). Same content decisions (modes,
section-to-diagram mapping, component menu, anti-slop-tells) as the local design-system format above
— only the page's shape and delivery mechanism change, because the page ships inside Claude Code's
official Artifacts feature instead of as a local file.
Before writing anything, load the built-in artifact-design skill (Skill tool, skill name
artifact-design). This is a tool contract MUST, not a suggestion — it's what conditions the model
for the CSP sandbox this page will run in, and skipping it is how a page ends up broken on publish.
Then write the page as a fragment, not a full document:
- No
<!DOCTYPE>, <html>, <head>, or <body> tags — content only, starting from your first real
element. The Artifact tool wraps the file in that skeleton at publish time.
- Set a concise
<title> directly in the content — it names the artifact in the browser tab. Keep
it stable across every republish of the same document in this session.
- Zero external requests — the Artifact viewer's CSP blocks all of them. No Mermaid CDN
<script>, no Google Fonts <link>, no hotlinked images. Diagrams that would normally be
<pre class="mermaid"> become inline SVG or HTML+CSS layouts instead (follow the artifact-design
skill's guidance on this) — same diagram-type decision from diagram-type-selection.md, different
rendering technique. mermaid-patterns.md's CDN setup and classDef rules don't apply here.
- Support both themes:
@media (prefers-color-scheme: dark) as the default signal, plus
:root[data-theme="dark"] / :root[data-theme="light"] overrides — the artifact viewer's theme
toggle stamps data-theme on the root and it must win in both directions.
Save the fragment to ${CLAUDE_PLUGIN_DATA}/reports/{doc-basename}-doc-visual.artifact.html — a
distinct filename from the default channel's output, so the two never collide or overwrite each
other for the same source document.
Re-running this skill on the same input within the same conversation reuses that same path.
Publishing to the same file_path again redeploys to the same URL instead of minting a new one, so
keep the <title> and favicon identical across those republishes (the tool reads a changed
favicon as a different page). If ${output-path}.artifact.json already exists from an earlier
publish this session, read it first and reuse its title/favicon verbatim rather than choosing
new ones.
Markdown format (--format md)
Insert directly into the response body, and save the same content to
${CLAUDE_PLUGIN_DATA}/reports/{doc-basename}-doc-visual.md — the chat text is the delivery, the
file is the record that lets report-manager list and refine this report later:
- Mermaid diagrams as fenced
```mermaid blocks
- Footer links to the source path
- No CSS, no
<script> — pure markdown
Markdown format — Artifact channel (--format md --artifact)
Write the same content as the default markdown path above — same structure, same fenced
```mermaid blocks, nothing rewritten for the channel. There's no CSS or script to break under
the Artifact viewer's CSP, so unlike the HTML channel this variant needs no fragment rewrite, no
built-in artifact-design skill load, and no content-only gate — the md content is already correct
by the same standard the default md path holds itself to.
The one channel-specific fact to act on: claude.ai's markdown renderer does not render Mermaid
(confirmed by a direct publish-and-view test, 2026-07-05) — a mermaid fence displays as a plain
monospace code block, not a diagram. Decide what to do about that using the branch from "Format
detection" above:
-
Explicit (--format md --artifact typed literally): publish as-is, never ask. If the content
has any Mermaid blocks, add one line next to the URL noting they'll show as code, with the
rendered-diagram alternative — e.g. "Diagrams appear as code on this channel — for rendered
diagrams, use --format html --artifact" (in whatever language you're already replying in).
-
Ambiguous (natural-language artifact intent, target format md) and no Mermaid present:
publish as-is, same as explicit — there's no diagram fidelity at stake, so nothing to ask about.
-
Ambiguous and Mermaid is present: ask once with AskUserQuestion before publishing anything:
- Regenerate as
--format html --artifact (diagrams render — recommended)
- Publish the md as-is (diagrams show as code)
- Keep it local (no publish)
Act on whichever the user picks. Don't ask again in the same conversation once they've answered.
Publish steps: save the md content to
${CLAUDE_PLUGIN_DATA}/reports/{doc-basename}-doc-visual.artifact.md (reuse the same path on a
same-session re-run, same as the HTML variant), then follow "Publish (Artifact channel — default for
HTML)" below — the Artifact tool call, sidecar write, and fallback behavior are identical regardless
of format.
Modes
Decide which mode fits the source document:
| Mode | When | Diagrams | Text depth |
|---|
| explainer | Tutorials, guides, narrative docs | Illustrate concepts | Full prose — preserve all substance |
| structural | ADRs, specs, API docs, config references | Map relationships | Structured — tables, definition lists, code blocks |
If the document mixes both (e.g., a spec with a narrative intro), use structural as the base and apply explainer treatment to narrative sections.
Section-to-diagram mapping
For each section in the source document, decide whether a diagram adds value. Not every section needs one — if a table or list says it better, use that.
Read ${CLAUDE_PLUGIN_ROOT}/references/design-system/diagram-type-selection.md to choose the right type from the 13-type menu. The mapping priority section tells you which keywords suggest which types.
When no diagram fits, skip it. A section with good prose and no diagram beats a section with a forced diagram.
Component menu
These are the building blocks. Mix them as the content demands:
| Component | When to use |
|---|
| Mermaid diagram | Relationships, flows, hierarchies — when connections are the point |
| Table | Comparisons, specs, 2-3 column data |
| Code block | Configs, commands, API examples |
| Prose paragraph | Narrative explanation, context, reasoning |
| Definition list | Term → meaning pairs |
| Callout box | Warnings, tips, important notes |
Diagram rules — local design-system channel
These govern Mermaid, which is a rendering technique rather than the diagram layer itself, so they
apply when you're writing the local design-system file (--local, or a non-capable fallback). On the
Artifact channel there is no Mermaid at all, and the built-in artifact-design skill owns density,
palette, and theming — the diagram type you chose in "Section-to-diagram mapping" carries over
unchanged, only the drawing technique differs (ADR 0009).
Read these reference files for implementation details — don't memorize them, read them each time:
${CLAUDE_PLUGIN_ROOT}/references/design-system/mermaid-patterns.md — Complete Mermaid syntax reference, theming, dark mode, zoom controls. This is the implementation bible — 13 type examples, classDef rules, CDN setup${CLAUDE_PLUGIN_ROOT}/references/design-system/semantic-tokens.md — Color/font roles and Mermaid themeVariables mapping${CLAUDE_PLUGIN_ROOT}/references/design-system/diagram-density-rules.md — Complexity budgets per type
Key rules for this channel (no need to look up):
- Density: Max 9 nodes, 12 arrows per diagram. Over budget → split into overview + detail
- Accent: 1-2 focal elements only. 4+ accents = redesign needed
- No rgba() in Mermaid classDef — parser breaks. Use 8-digit hex
#RRGGBBAA
- No
color: in classDef — breaks parser. Style text via themeVariables only
- Theme: Always
theme: 'base' with themeVariables from semantic-tokens
- Palette: No violet/fuchsia "AI purple" hexes (
#8b5cf6/#7c3aed/#a78bfa/#d946ef) — the gate fails on these
- Table vs diagram: If a 3-column table conveys it equally well, use the table
Either channel's gate fails on dead links, alt-less images, and leftover scaffolding: give every <a> a real href, every <img> an alt (alt="" if decorative), and leave no {{ }}/lorem/[STUB] placeholders — those are content checks, so --content-only runs them too. This channel's full gate additionally fails on background-clip: text (gradient-clipped text — decorative slop) and on any font-family without a generic fallback, so end every stack with a system family (…, sans-serif).
CSS essentials
You write your own CSS inline. These constraints matter:
- Font stacks: Always end every
font-family with a system fallback chain (e.g. Geist, system-ui, -apple-system, sans-serif) — the web fonts aren't bundled, so a bare family name silently drops to a browser default offline. See semantic-tokens.md for the per-role chains. Include a CJK font when the document might be Korean
- Dark mode: Support
prefers-color-scheme: dark via CSS custom properties. Map semantic roles (paper, ink, muted, accent) to both schemes
- Mermaid scaling: zoom by sizing the SVG to
viewBox × level (mermaid-patterns.md applyZoom()) — same vector sharpness as transform: scale(), but the diagram occupies the space it draws in, so the scroll container can reach all of it. Never the zoom property
- Overflow protection:
min-width: 0 on flex/grid children
- Code blocks:
white-space: pre; overflow-x: auto
- Status indicators: Colored dots via CSS, no emoji
- Animations: Respect
prefers-reduced-motion: reduce
Content integrity — the cardinal rule
The source document's substance must survive intact in the report. This means:
- Specific numbers, names, dates from the source → appear in the report
- Technical details (configs, commands, parameters) → preserved verbatim
- Reasoning and nuance → kept, not flattened to bullet points
- Code examples → reproduced in full
If you're writing "this section covers X" or "the document describes Y" — stop. That's a summary of the content, not the content. Include the actual content.
This cardinal rule (call it summary-leak) is one of seven authoring reflexes that pass every mechanical gate and still flatten the output. Read ${CLAUDE_PLUGIN_ROOT}/references/design-system/anti-slop-tells.md for the full catalogue — linear dump, forced diagram, generic label, uniform density, empty decoration, accent overuse. They're named defaults to break, not design rules: layout and taste stay yours, the catalogue just flags the habits worth resisting.
Short documents (<500 chars) get 1 section + 1 hero diagram. Long documents get proper sectioning but still preserve all substance.
Validation (HTML only)
Which gate you run follows the channel (see "HTML channel routing" above):
- Artifact channel (the default) → content-only gate. Jump to "content-only mode" below.
- Local design-system channel (
--local / non-capable fallback) → the full gate immediately
below.
For the local channel, after writing the HTML file run artifact-gate:
node ${CLAUDE_PLUGIN_ROOT}/scripts/artifact-gate.js <output-html-path>
It checks, in this order:
- Missing images — any
<img src="..."> pointing to nonexistent local files
- Raw markdown remnants —
##, **, ``` leaked into HTML body
- Mermaid density — diagrams exceeding complexity budgets
- Mermaid classDef colour traps —
rgb()/rgba() (parser break) or color: (dark-mode break) in a classDef
- Forbidden palette — violet/fuchsia "AI purple" hexes banned by semantic-tokens.md
- Anchor href integrity —
<a> with no/empty/# href (pure id/name jump targets are exempt)
- Image alt —
<img> missing an alt attribute (alt="" for decorative images is allowed)
- Placeholder leak — unfilled
{{ … }}, lorem ipsum, or bracketed stubs left in the body
If violations found: fix them inline (re-edit the HTML). Max 2 retry cycles. If still failing after 2 fixes, remove the offending element and log a warning.
On the Artifact channel (the default), run the gate in content-only mode instead:
node ${CLAUDE_PLUGIN_ROOT}/scripts/artifact-gate.js <output-html-path> --content-only
This runs only checks 1, 2, 6, 7, 8 above (missing images, raw markdown, anchor hrefs, image alt,
placeholders) — the facts that must survive regardless of who designed the page. Checks 3–5 (density,
classDef, palette) don't apply: the built-in artifact-design skill owns the design layer on this
channel (ADR 0007), and there's no Mermaid to check density on in the first place.
Visual self-audit (local HTML channel only)
Runs only for the local design-system channel (--local / non-capable fallback) — it's the local
Chrome render loop. On the Artifact channel (the default) skip it entirely: the rendered picture is
the built-in artifact-design skill's responsibility there, and there's no local file to render before
publishing.
The gate reads the HTML as text — it never sees the rendered picture. A diagram can pass the density check and still render as an unreadable tangle; a label can clip at the container edge; hierarchy that reads fine in source can collapse into a flat wall once styled. After the gate passes, render the report and look at it before delivering:
node ${CLAUDE_PLUGIN_ROOT}/scripts/render-report.js <output-html-path>
On success it prints a PNG path. Read that PNG (you read images multimodally) and scan it for what the text gate can't judge:
- Density — is any section a uniform grey wall, or a diagram past its budget and unreadable?
- Hierarchy — does anything draw the eye first, or is every section the same weight? (see uniform density / accent overuse in anti-slop-tells.md)
- Mermaid integrity — did a diagram render as raw
<pre> text or as crossing/overlapping edges?
- Overflow — does a diagram, table, or label run past its container or off the page?
Fix what you see and re-render. Cap at 2 audit passes — if something still looks off after the second, ship with a one-line note to the user rather than looping. This catches gross breakage, not pixel-perfection.
If Chrome is absent, render-report.js exits 1 (non-zero). Skip the audit and tell the user it was skipped (e.g. "rendered-image check skipped: Chrome not found — set CHROME_BIN or install Chrome"). The report already passed the gate; the visual pass is an enhancement and never blocks delivery.
Full procedure, limits (fixed-height clipping, downscaling, render cost), and the rationale for not mechanizing this with a measurement script live in ${CLAUDE_PLUGIN_ROOT}/references/design-system/visual-self-audit.md.
Output
- HTML (Artifact channel — the default): publish the fragment — see "Publish" below.
- HTML (local design-system channel —
--local / non-capable fallback): save to
${CLAUDE_PLUGIN_DATA}/reports/{doc-basename}-doc-visual.html and run open <output-path>.
- MD: Insert directly into the response body and save a copy to
${CLAUDE_PLUGIN_DATA}/reports/{doc-basename}-doc-visual.md. Footer links to the source path.
Publish (Artifact channel — default for HTML)
For --format html, do this after the content-only gate passes. For --format md, there's no gate
to wait on — go straight to publishing once the branch in "Markdown format — Artifact channel" above
resolved to "publish."
- Publish with the
Artifact tool: file_path = the file you saved (the html fragment or the md
file), favicon = one or two emoji fitting the document's topic (reused unchanged if a sidecar
from this session already set one — see above), description = one sentence on what the page is.
- Record the publish so a later refine (even across sessions, once that lands) can find this URL:
node ${CLAUDE_PLUGIN_ROOT}/scripts/write-artifact-sidecar.js --report <output-path> --url <artifact-url> --title <title> --favicon <favicon>
- Report the URL to the user with one line. This is the canonical publish notice — S2–S4 reuse
the same shape, only swapping the noun (report / dashboard / wiki), so keep it stable:
- html:
Published to claude.ai — design is delegated to Claude's built-in Artifact renderer, so it differs from the local report's look; run --local for the local design-system + Mermaid version. This one line does double duty: it discloses the publish (the deliverable is now a URL,
not a local file) and the design delegation. Phrase it in whatever language you're already
replying in — the structure (published · delegated-design · --local escape hatch) is what's
canonical, not the exact English words.
- md: only if the content has Mermaid blocks, note they show as code (see "Markdown format —
Artifact channel" above for the exact wording). No diagrams → no extra line needed.
Fallback — non-capable session (regenerate, don't just open). If the Artifact tool is
unavailable or the publish call fails, the session is non-capable. Don't guess at the specific cause
and don't ask before falling back:
- html: the fragment you authored is a Mermaid-less, skeleton-less page meant for the Artifact
viewer — do not
open it (that serves a broken, diagram-free page and breaks ADR 0009 §3's
promise of design-system + Mermaid on a non-capable session). Instead regenerate the full local
design-system + Mermaid report ("HTML format — local design-system channel" above), run its full
gate + visual self-audit, save to the …-doc-visual.html path, open it, and state the fallback in
one line (e.g. "Artifact publish unavailable — generated the local design-system report instead.").
Cost = one regeneration, only on a non-capable session.
- md: deliver the content the normal way instead — insert it directly into the response body (the
default
--format md path above) — and state the fallback in one generic line (e.g. "Artifact
publish unavailable — delivered as chat markdown instead.").
Error handling
| Failure | Action |
|---|
| File missing/no permission | Abort with message |
| Empty file | Abort — nothing to visualize |
| No headings (H1/H2/H3) | Treat as single section |
| html (default Artifact): Artifact tool unavailable or publish fails | Non-capable → regenerate the full local design-system + Mermaid report + open it + one-line reason, don't ask (never just open the fragment) |
| md + artifact intent: Artifact tool unavailable or publish fails | Fall back to chat-inserted markdown + one-line reason, don't ask |
| Mermaid syntax error after 2 fixes | Remove that diagram, keep section prose |
Reference files
Read these during report generation (not upfront — read the relevant one when you need it):
| File | When to read |
|---|
${CLAUDE_PLUGIN_ROOT}/references/design-system/mermaid-patterns.md | Before writing any Mermaid diagram |
${CLAUDE_PLUGIN_ROOT}/references/design-system/semantic-tokens.md | When setting up CSS custom properties and Mermaid theme |
${CLAUDE_PLUGIN_ROOT}/references/design-system/diagram-type-selection.md | When deciding diagram type for a section |
${CLAUDE_PLUGIN_ROOT}/references/design-system/diagram-density-rules.md | When a diagram feels complex |
${CLAUDE_PLUGIN_ROOT}/references/design-system/anti-slop-tells.md | While shaping content — to check you're not falling into a behavioral-slop reflex |
${CLAUDE_PLUGIN_ROOT}/references/design-system/visual-self-audit.md | After the gate passes — the render-and-look loop (full procedure) |
