| name | wiki-visualize |
| description | Add a diagram, chart, or infographic to a wiki page when it genuinely makes an idea faster to understand. Use when Floris says "add a diagram", "visualize this", "draw this", "make an infographic", "can you chart this", or when a new/updated page has structure, flow, comparison, or stats that a picture would clarify. Picks the right Quartz-native technique (Mermaid, inline HTML/CSS, or inline SVG), styles it to the site palette, verifies it renders, and keeps Floris as the approver.
|
Wiki visualize
Turn a page's structure, flow, or numbers into a clear visual — without adding slop.
Read .github/DIAGRAMS.md first; it is the visual quality bar and
the schema this skill follows. Then pull the actual recipe from
PATTERNS.md — a library of verified, copy-paste, dark-mode-checked
snippets. Pick the closest pattern and customize it; don't free-hand layout. Floris
approves every embed.
Hard rules
- A visual must earn its place — and so does a wall of flat text. Add a visual when it
makes something faster to understand or when it paces a long stretch of prose better
than another paragraph would. Don't add one that just restates the text, and don't add
one you can't justify in a sentence. (See
DIAGRAMS.md §1.)
- Start from a verified recipe. Reach for the closest pattern in
PATTERNS.md
and adapt it. Free-handing HTML is how the code-block trap and dark-mode bugs creep in.
- Quartz-native only. Use Mermaid, inline HTML/CSS, or inline SVG — no new plugins,
no
<script>, no external CSS frameworks.
- Site palette, dark-mode safe. Colours come from the CSS variables / two brand
accents in
DIAGRAMS.md §3–5. Never hardcode colours that only
work on one background.
- Don't invent facts. A diagram is a claim. Everything in it must trace to the page's
sources, just like prose. No invented boxes, arrows, or numbers.
- Never push to
main. Work on a branch; Floris merges.
- Ask before embedding. Propose the visual (type + what it clarifies), get a yes,
then embed.
Steps
- Decide if it's worth it. Look at the page. Is there a flow, structure, hierarchy,
chronology, comparison, or set of stats that prose handles awkwardly — or a long grey
stretch a timeline / stepper / stat strip would pace better? If genuinely nothing fits,
say so; recommending no visual is a valid outcome. But on a long page, actively hunt
for the one or two spots where a visual would do real work.
- Pick the technique and type. Use the decision table in
DIAGRAMS.md
§2 and the index in PATTERNS.md: relational → Mermaid; quantitative or
editorial layout → HTML; bespoke → SVG. Name the specific pattern (stat cards, vertical
timeline, swimlane, flowchart, …) and why. Steer chronology → HTML timeline and
hierarchy → flowchart TD (Mermaid timeline/mindmap render low-contrast here).
- Propose it to Floris. One line: the technique, the type, and the single thing it
clarifies. Wait for a yes before writing it into the page.
- Draft it from a recipe. Copy the closest
PATTERNS.md snippet and
swap in the page's real content. Keep node counts sane (≤ ~8), label edges in 1–3 words,
group with subgraphs before things sprawl. Add accTitle/accDescr (Mermaid) or
<title>/<desc> + <figcaption> (SVG/HTML). For HTML, keep the block gap-free with
≤2-space indentation — a blank line or 4-space indent turns it into a grey code block.
- Style to the palette. Let Mermaid inherit the site theme; use
classDef only to
accent key nodes with sage/amber. For SVG/HTML use style="…:var(--…)" (never bare
fill="var(--…)") and responsive sizing (viewBox+width:100%, reflowing grids).
- Self-check syntax. Run the failure-mode checklist in
DIAGRAMS.md
§6 (declared nodes, quoted labels, classDef before use, --> vs ->, etc.).
- Verify it renders. When practical: , open the
page, confirm the visual renders in and reflows on a narrow
width. Mermaid syntax errors fail silently — don't skip this for non-trivial diagrams.
When to hand off
- To gate a figure brief before building it: the
figure-spec-checker agent. Hand it
only the instruction (no page, no context) and it cold-reads whether the figure is
interpretable (CLEAR), missing specific facts (MISSING INFO), or too vague to draw (VAGUE).
Useful at step 1–3 when the brief is non-trivial or you're unsure you've understood it.
- To shape the surrounding prose into Floris's voice: the
style-editor agent.
- To gate the page (prose and whether the visual earns its place): the
slop-verifier agent.
- To file a whole new source into pages first: the
wiki-ingest skill (which calls
this skill at its "consider a visual" step).
