/artifact-diagram

Use hand-placed <svg viewBox="0 0 680 H" width="100%"> for all diagrams (except database schemas with many columns, which use <script src="lib:mermaid"> with erDiagram).

---

1. Route on the verb first

Prompt intent	Diagram style	Key rule
"How does X work?"	Illustrative (default, most ambitious)	Draw the spatial/physical metaphor (buffers filling, wave/packet moving, memory slots, tree splitting), not just named boxes. If the system has a knob or threshold, add a slider!
"Architecture of X"	Structural	Outer <rect rx="12" stroke-dasharray="4 3"> container holding 2–4 inner <g class="node c-..."> boxes. Max 2–3 nesting levels.
"Steps / trace / flow"	Flowchart / sequence	3–5 nodes per diagram, left-to-right or top-to-bottom, with concrete payload values (POST /run {id: 7}) on the connectors or subtitles.
"Cycle / state loop"	HTML stepper (never a ring)	Never draw a circular ring of arrows — build an HTML stepper (Prev / Next buttons + step indicator) where each step swaps or highlights the active stage on the SVG.
"Database schema / ERD"	Mermaid erDiagram	Use <script src="lib:mermaid"></script> and mermaid.render(...).

---

2. SVG canvas & Geist width calibration

• Fixed coordinate width: Always <svg width="100%" viewBox="0 0 680 H"> where H is the lowest element's bottom edge + 24..36.
• Safe area: Keep all boxes and text inside x = 40..640, y >= 20. Never use negative coordinates.
• Geist font width calibration: Measure every label before choosing width so text never clips or overflows its <rect> (the artifact tool runs an automatic layout linter and will report overflows!):
  • .th / .t (14px Geist): ~8px per character (width >= text.length * 8 + 28).
  • .ts (12px Geist): ~6.8px per character (width >= text.length * 6.8 + 24).
  • Single-line node height: 44px.
  • Two-line node height (title .th + subtitle .ts): 56px (place title at y + 22, subtitle at y + 40, centered at x + width / 2 with text-anchor="middle" and dominant-baseline="central").
  • Keep subtitles to 5 words or fewer.

---

3. Node & connector template

<svg width="100%" viewBox="0 0 680 180">
  <!-- Node 1: clickable to open a workspace file -->
  <g class="node c-purple" onclick="openFile('packages/harness/src/session/runner.ts', 42)">
    <rect x="40" y="52" width="160" height="56" rx="8" />
    <text class="th" x="120" y="72" text-anchor="middle" dominant-baseline="central">Session runner</text>
    <text class="ts" x="120" y="92" text-anchor="middle" dominant-baseline="central">runner.ts:42</text>
  </g>

  <!-- Connector: stops at box edges (200 -> 260), never crosses inside a box -->
  <line x1="200" y1="80" x2="258" y2="80" class="arr" marker-end="url(#arrow)" />
  <text class="ts" x="229" y="70" text-anchor="middle">tool call</text>

  <!-- Node 2 -->
  <g class="node c-teal" onclick="openFile('packages/harness/src/tool/artifact.ts', 1)">
    <rect x="260" y="52" width="160" height="56" rx="8" />
    <text class="th" x="340" y="72" text-anchor="middle" dominant-baseline="central">Artifact tool</text>
    <text class="ts" x="340" y="92" text-anchor="middle" dominant-baseline="central">validates + lints</text>
  </g>

  <line x1="420" y1="80" x2="478" y2="80" class="arr" marker-end="url(#arrow)" />

  <!-- Node 3 -->
  <g class="node c-blue">
    <rect x="480" y="52" width="160" height="56" rx="8" />
    <text class="th" x="560" y="72" text-anchor="middle" dominant-baseline="central">Sandboxed tab</text>
    <text class="ts" x="560" y="92" text-anchor="middle" dominant-baseline="central">null-origin iframe</text>
  </g>
</svg>

---

4. Connector & color rules (checked by the host linter)

1. Every <path> or <polyline> connector must set fill="none" (or class="arr"), otherwise SVG fills the bend with a black triangle.
2. Lines stop at box edges (x1 = boxA.x + boxA.width, x2 = boxB.x - 2). Never route a straight <line> through an unrelated <rect>; use an L-bend <path d="M x1 y1 L x1 yMid L x2 yMid L x2 y2" class="arr" marker-end="url(#arrow)" fill="none" />.
3. Never nest a <g class="c-*"> inside another <g class="c-*"> — CSS descendant selectors will overwrite the inner ramp's text/fill colors. Keep all nodes as sibling <g> elements.
4. Color assignment:
   • Prefer c-purple, c-teal, c-coral, c-pink for categorical grouping (stages, components, actors).
   • Reserve c-blue (info/focus), c-green (success/healthy), c-amber (warning/queued), c-red (error/rejected) for semantic meaning.
   • Use c-gray or .box for supporting/idle nodes so the active path stands out.
5. No rotated text (transform="rotate(...)" on <text>) — keep every label horizontal.