creating-docs-diagrams

Creating Docs Diagrams

Create literal, responsive raw SVG that fits Rivet's self-hosted perimeter aesthetic.

Scope

• Apply raw SVG conversion only to documentation pages under website/src/content/docs/**/*.mdx.
• Keep every diagram under website/src/content/cookbook/** as Mermaid. Do not convert cookbook Mermaid to raw SVG, including during a repository-wide diagram cleanup.
• Treat posts, changelog entries, and other content trees as out of scope unless the user explicitly names them.

Workflow

1. Inventory Mermaid before editing with rg -n '```mermaid' website/src/content/docs and record every node, boundary, edge direction, edge label, and line break. Do not broaden this search into cookbooks or posts for conversion work.
2. Choose an architecture pattern for topology and nested deployment boundaries, or a sequence pattern for time-ordered messages between participants.
3. Replace each block with literal inline <svg>...</svg>. Do not use Mermaid, scripts, imported components, external SVGs, or image assets.
4. Preserve every semantic detail. Keep <--> bidirectional with markers at both ends, --> directional, nested boundaries intact, and explicit <text> lines for labels that used <br/>.
5. Give every SVG role="img" and a concise but complete aria-label. Give marker IDs unique, descriptive names per page and SVG.
6. Start the website preview and screenshot every changed diagram at a desktop viewport and at 390 CSS pixels. In Playwright, pass viewport, not viewportSize, and assert window.innerWidth before trusting a mobile capture. Activate every tab so hidden diagrams are also captured.
7. Keep sticky site chrome out of element screenshots by scrolling the target below it or hiding the chrome only for the capture. For a horizontally scrollable diagram, capture the full diagram at desktop plus its left and right scroll extents at 390px; record clientWidth and scrollWidth to confirm the screenshots exercise real overflow.
8. Inspect screenshot pixels, not only DOM bounds. Reject excessive dead space, unnecessarily long arrows, text touching a line, paths crossing unrelated nodes, clipped labels, or inconsistent node styling. Fix and recapture until every diagram passes.
9. Run rg -n '```mermaid|foreignObject|<style' <changed-pages> as appropriate, then run Astro or the website build validation.