Docs SVG Kit

Docs SVG Kit

A snippet library for drawing SVG figures embedded in Grida docs. Canvas user docs are the kit's first consumer; the same primitives and conventions are meant to carry over to any product's docs as they adopt SVG figures.

First consumer / companion: docs-canvas. Use that skill for the prose, this one for the visuals embedded inside it.

Why SVG, not a screenshot

Screenshots are easy to capture but expensive over time:

• Stale by default. UI shifts; the screenshot keeps showing the old state until someone re-captures it. There is no diff, no warning, no test that fails.
• Repo weight. Every re-capture is a new binary blob in git history. WebP at 960 × 960 is ~30–80 KB each; PNG is multiples of that. Across years of captures it compounds, and old blobs never leave history.
• Frozen in time. A screenshot shows one moment of one configuration. A diagram explains the rule across configurations.

So: when SVG can carry the meaning, prefer SVG. SVGs are text — diff-able, hand-editable, version-controlled like code. Reserve screenshots for cases where the actual rendered chrome (real fonts, real pixels) is the point.

When to draw an SVG figure

Reach for a custom SVG when a screenshot can't carry the story alone:

• A gesture (the clickable target isn't visible at rest — double-click, drag, hover).
• A before / after that needs the two states side-by-side.
• A rule that hinges on an invisible anchor or pivot (alignment, snapping, hit-testing).

If a single screenshot of the editor would communicate the whole point, use a screenshot. Don't redraw real UI in SVG when you don't have to.

Hard constraints

These are baked into the kit. Don't fight them.

• Inline <style> only. Never reference an external stylesheet. Docusaurus serves docs SVGs via <img src>, which sandboxes the SVG: external CSS, scripts, and cross-file <use href> are all blocked.
• No cross-file <use>. Every reused fragment must physically live inside the SVG's own <defs>. Copy from snippets/, don't import.
• Self-contained = SEO-safe. Inline-styled SVGs are indexed as images. Inline React components in MDX are not — they become HTML.
• Output size: 960 × 960. The viewport for all figures, matching docs/AGENTS.md screenshot conventions. Use viewBox="0 0 960 960" width="960" height="960".
• Watermark every kit-produced SVG (see below).
• No emojis. No marketing voice. Same neutral tone as the prose.

Watermark every kit-produced SVG

So we can enumerate, audit, and migrate kit assets later without reading each file, every SVG produced via this kit must carry two markers:

1. A top-level XML comment immediately before the root <svg> (grep-friendly):

   <!-- @generated-by: docs-svg-kit v1 -->

2. A <metadata> element as the first child of <svg> (SVG-spec-native, survives minification and SVGO passes that strip comments):

   <metadata>docs-svg-kit/v1</metadata>

Both markers are present in snippets/template.svg, so they propagate automatically when you copy from the template. If you start a figure from scratch, paste both before composing anything else.

Versioning. Bump v1 → v2 only on a breaking change to tokens or primitives (e.g. selection blue changes hex, or anchor pin geometry changes). Same-version figures are guaranteed visually consistent.

Enumerate kit assets:

grep -rl "docs-svg-kit" docs/editor/

When the kit changes, walk the grep output and update each file.

Workflow

1. Start from the template. Copy snippets/template.svg — it has the canvas, fonts, all <defs>, all class tokens, and shadow filters wired up.
2. Browse snippets/primitives.svg for the bird's-eye catalog of every primitive. For deeper inspection of a specific family, open the focused chunk file (see Snippet files below).
3. Compose your figure inside the marked region of the template, using the existing classes. Don't reinvent stroke widths, colors, or fonts — that's how visuals drift.
4. Crib structure from examples/. Two finished figures live there:
   • text-node-auto-size-edges.svg — two-column before/after with hot edges, ripples, cursors, size badges, and a legend card.
   • text-node-auto-size-alignment.svg — three-column comparison with anchor pins and ghost outlines.
5. Save to docs/editor/resources/. Name: <feature>-<description>.svg, kebab-case.
6. Embed via Markdown. ![alt text](../resources/your-figure.svg) from a doc under docs/editor/features/. The alt should describe what the figure shows, not name the file.

Snippet files

snippets/ is structured as one overview catalog plus focused per-family files:

When to look in which:

• Quick scan of "what exists" → primitives.svg.
• Picking a specific cursor / badge variant / handle / keycap → the per-family file. They show variants, sizes, hotspots, and source references that the index can only hint at.

Note on canvas size. Snippet files exceed the 960 × 960 figure mandate (e.g. cursors.svg is 960 × 720, primitives.svg is 960 × 1400). That mandate applies to doc figures — kit reference catalogs are not embedded in docs and may be tall.

What's in the kit

Primitives (in snippets/template.svg defs)

Color tokens

Slight drift, intentional. The kit's selection (#0D99FF) is Figma blue; the product's canonical WorkbenchColors.sky is #00a6f4. Same for hot (#FF3B30) vs WorkbenchColors.red (#f44336). The new measurement token uses the canonical product red. A future kit pass may harmonise these — for now, the difference is visually negligible (~3% off) and keeps existing figures stable.

Typography tokens

Font stack: -apple-system, BlinkMacSystemFont, 'SF Pro Text', 'Helvetica Neue', Helvetica, Arial, sans-serif for prose; 'SF Mono', Menlo, Consolas, monospace for code/badges.

Ground truth in the editor

The kit's primitives are stylised — close to the product but not pixel-clones. When a primitive is unclear or you need to match the actual UI more carefully, go to source:

Rule of thumb: if you find yourself inventing a primitive that maps to a real product UI element, check the source first — the names and tokens above are usually nearby.