🦾 SVG

Executive Summary

Scalable Vector Graphics (SVG) provide durable, resolution-independent visuals for our documentation and UI. While Mermaid handles structural diagrams and Canvas handles spatial maps, SVG is our tool of choice for custom iconography, precise structural overlays, and minimal bespoke illustrations. This skill outlines how to write, style, and maintain SVGs specifically for the Funday and Quartz environments.

When to use / When NOT to use

Use When:

• Creating custom icons, logos, or UI elements.
• Building precise, highly stylized vector graphics that Mermaid cannot support.
• Needing animations or interactive hover states within a single graphic.

When NOT to use:

• Standard flowcharts or sequence diagrams (use Mermaid for easier maintenance).
• Large, multi-node architecture maps (use JSON Canvas).
• Complex, screenshot-like art or raster conversions (use WebP/PNG).

Rules

1. Semantic Theming

SVGs must be dark-mode and light-mode compatible. Do not hardcode absolute colors like #000000 for strokes. Instead, use currentColor or reference Quartz CSS variables (e.g., var(--light), var(--dark), var(--tertiary)) when embedded inline.

2. Minimal Text

Keep text within SVGs minimal. SVG text styling can be inconsistent across browsers and often ignores the host document’s font stack unless explicitly defined. If heavy text is required, consider if the visual should be an HTML/CSS component or a Canvas map instead.

3. Path Simplicity

Prefer simple paths, geometric primitives (<rect>, <circle>, <polygon>), and clean code. Avoid dumping raw exports from tools like Illustrator or Figma without running them through an optimizer like SVGO to remove cruft and proprietary metadata.

4. Responsiveness

Always define viewBox rather than hardcoding width and height to absolute pixel values, ensuring the SVG scales cleanly within its container.

Examples

Clean, Theme-Aware SVG Icon

<svg 
  xmlns="http://www.w3.org/2000/svg" 
  viewBox="0 0 24 24" 
  fill="none" 
  stroke="currentColor" 
  stroke-width="2" 
  stroke-linecap="round" 
  stroke-linejoin="round"
  class="funday-icon"
>
  <circle cx="12" cy="12" r="10"/>
  <path d="M12 8v4l3 3"/>
</svg>

Using CSS Variables (Inline)

<svg viewBox="0 0 100 100" xmlns="http://www.w3.org/2000/svg">
  <style>
    .bg { fill: var(--light, #ffffff); }
    .outline { stroke: var(--dark, #000000); stroke-width: 4; }
  </style>
  <rect x="10" y="10" width="80" height="80" class="bg outline" rx="8" />
</svg>

Failure Modes / Checks

1. Dark Mode Invisibility: Black strokes on a transparent background disappear entirely when Quartz switches to dark mode. Always use currentColor or theme variables.
2. Fixed Dimensions: An SVG with width="500px" will blow out mobile layouts. Use viewBox and CSS max-width: 100%.
3. Bloated File Size: Unoptimized SVGs with thousands of decimal places for path coordinates hurt performance.
4. Missing XMLNS: SVGs used as <img> sources or background images will fail to render without the xmlns attribute.

Related Links

• MDN SVG Tutorial
• Mermaid Guru