🎨 SvgGuru

Hand-authored, theme-aware vector art that scales crisply and respects dark/light. For relationship diagrams, reach for 🧜 MermaidGuru first.

1. 🎯 When

Pick SVG	Pick Mermaid
Precise custom shapes, icons, badges	Auto-laid flow / sequence / state
Exact pixel control / brand marks	”Just show the relationship”
Annotated diagrams, gauges, legends	Graph that changes often
Non-graph illustration	ER / mindmap structure

Rule of thumb: if a layout engine should place the boxes, use 🧜 MermaidGuru. If you place every point, use SVG.

2. 📐 viewBox

viewBox defines the coordinate space; width/height (or CSS) define the rendered size. Use viewBox for resolution independence — never bake in pixel width/height alone.

<svg viewBox="0 0 100 100" role="img" aria-labelledby="t d">
  <title id="t">Status badge</title>
  <desc id="d">Green check inside a ring</desc>
  <circle cx="50" cy="50" r="44" fill="none" stroke="currentColor" stroke-width="6" />
  <path
    d="M30 52 L45 67 L72 36"
    fill="none"
    stroke="currentColor"
    stroke-width="8"
    stroke-linecap="round"
    stroke-linejoin="round"
  />
</svg>

3. 🌗 Theme

The site is theme-adaptive — make SVG follow suit instead of freezing colors (same spirit as 📜 SSOT Bible §4 for Mermaid).

• 🎨 fill="currentColor" / stroke="currentColor" inherits the surrounding text color, so the art flips with the theme automatically.
• 🧪 For accents, reference site CSS variables: fill="var(--secondary)", stroke="var(--tertiary)". Provide a sane literal fallback only where a var may be absent.
• 🚫 Avoid hardcoded #fff/#000 — they break in one of the two themes.

4. ♿ A11y

• 🏷️ Add role="img" + <title> (and <desc> for detail), wired via aria-labelledby="t d".
• 🙈 Purely decorative SVG → aria-hidden="true" and drop the title.
• 🔤 Keep real labels as <text> (selectable, themeable) rather than outlined paths.

5. 🩹 Fixes

• Invisible in light mode → hardcoded dark fill; switch to currentColor/var().
• Blurry when scaled → missing viewBox; add it, drop fixed pixel sizing.
• Clipped edges → content exceeds viewBox; widen the box, not the element.
• No screen-reader text → add role="img" + <title>.

Need flow, not freehand? → 🧜 MermaidGuru. Spatial maps → 🗺️ CanvasGuru.