Visualcave

VisualCave

Output a single self-contained .html file. No markdown wrapper unless the user asks for it.

Before You Draw

1. Identify the critical path. Every good diagram has one story — the single flow or relationship the viewer must understand immediately. Name it before writing any Mermaid code. Let it govern which nodes exist and how subgraphs are grouped. Nodes that don't serve the story get cut.

2. Pick scope ruthlessly. Aim for 8–15 nodes. Beyond 20 the diagram becomes unreadable. Group related details into a single labeled node rather than expanding every sub-step.

3. Choose labels like a senior engineer preparing a conference slide — not an autogenerated dump. Node labels: 2–4 words. Edge labels: 1–3 words. Subgraph titles: a noun phrase, not a sentence.

Style rules:

• Thick strokes (2px), 4px drop shadow, rounded nodes.
• Warm/cool subgraph alternation: yellow → blue → green → purple → teal → orange.
• Inter font for UI; JetBrains Mono for code/math labels.
• Pick the right Mermaid keyword — see references/diagram-types.md.

HTML Template

Read references/template.html verbatim. Replace:

• [Diagram Title] and [Subtitle] in the header
• The placeholder Mermaid source inside <div class="mermaid" id="diagram-source"> with the actual diagram

Do not alter the CSS, THEMES object, or script block unless a specific feature requires it.

Colors

classDef works in graph, classDiagram, stateDiagram-v2. For other types use themeVariables.

Class	Fill	Use for
:::yellow	#FFFDE7	Users, browsers, entry points
:::blue	#E3F2FD	Services, APIs, compute
:::green	#E8F5E9	Databases, storage, success
:::purple	#F3E5F5	Auth, AI models, security
:::teal	#E0F7FA	Caching, CDN, external APIs
:::orange	#FFF3E0	Queues, events, pipelines
:::note	#FFF9C4	Annotations, callouts

Interactive Features

Theme selector — built into the template. Five themes: default, minimal, pastel, print, sketch (hand-drawn). Persisted via localStorage key vc-style. No changes needed.

Step-through (sequential reveal): copy setupSteps() pattern from examples/transformer-ultra.html.

Hover highlight: add data-node / data-connects attributes post-render, include <script src="hover.js"></script>.

Export (in-page): every diagram has SVG, PNG, and PDF download buttons in the controls bar — no server or Node.js needed. SVG serializes the inline SVG with white background; PNG renders at 2x; PDF uses window.print() with controls hidden.

Export (CLI): node capture.js file.html [--format=png|svg|pdf|og] — for animated GIF, OG images, and headless batch export.

Brand theming: see references/theming.md.

Animated diagrams: see references/animated.md.

Animation Mode — on "animated", "living diagram", "canvas", "particles", "flowing edges": ask whether the user wants CSS flow (flowing edges + node glow on any Mermaid diagram, zero deps — references/animated.md) or Canvas (custom particles/physics showpiece, no Mermaid — references/canvas-animation.md).

Astro Component Mode (varkart.dev site)

Triggers: "for the blog/site/article", "embed this", "Astro component", "MDX component"
Output a .astro file at src/components/mdx/ComponentName.astro (site: github.com/varkart/personal-site) instead of a standalone HTML file.
For React/Next.js ("React component", "TSX component"): output .tsx with inline SVG instead.
See references/astro-component.md for token tables, component template, badge palettes, dark-first CSS rule, Mermaid config, and React/TSX output.

Quality Pass

After writing the Mermaid source, review before outputting the file:

• Node count ≤ 20 (ideally ≤ 15). Merge or drop anything peripheral.
• Every node label ≤ 5 words. Abbreviate where meaning is preserved.
• No orphan nodes — every node connects to at least one edge.
• Subgraph nesting ≤ 3 levels deep.
• Color assignment is meaningful — same semantic color = same role category.
• The critical path is visually obvious top-to-bottom (or left-to-right).
• No redundant edges — if A→B→C and A→C both exist, the direct edge likely adds nothing.