# Layout Math

SVG has no auto-layout. Every coordinate, width, and height is hand-computed. Most diagram failures trace back to text overflowing its container or elements landing outside the viewBox. This file is the arithmetic you run *before* writing any `<rect>`.

## The coordinate system

- **viewBox**: `0 0 680 H`. Width is always 680. Compute H from content.
- **Safe area**: `x ∈ [40, 640]`, `y ∈ [40, H - 40]`. Leave 40px of breathing room on every edge.
- **Usable width**: 600 px (640 − 40).
- **Pixel units are 1:1.** The `width="100%"` with `viewBox="0 0 680 H"` means the browser scales the whole coordinate space to fit the container. A 14px font is really 14px. Character widths below assume this 1:1 ratio.

## Text width estimation

SVG `<text>` never auto-wraps. If you put more characters in a box than it can hold, they overflow visibly. Use these character-to-pixel multipliers, calibrated on Anthropic Sans:

| Case                                     | Approx. width per character |
|------------------------------------------|-----------------------------|
| 14px latin, weight 500 (`th`, titles)    | ~8 px                        |
| 14px latin, weight 400 (`t`, body)       | ~8 px                        |
| 12px latin, weight 400 (`ts`, subtitles) | ~7 px                        |
| 14px CJK (Chinese, Japanese, Korean)     | ~15 px (~2× Latin)           |
| 12px CJK                                 | ~13 px (~1.9× Latin)         |

**Special characters:** chemical formulas (C₆H₁₂O₆), math symbols (∑ ∫ √), subscripts, superscripts all take the same horizontal space as normal characters — don't assume subscripts are narrower. For labels that mix Latin and formulas, add 30–50% padding to your width estimate.

### Empirical calibration samples

Real measurements of Anthropic Sans at the sizes this skill uses. The multipliers above are the safe ceilings derived from these samples — not the averages. Letter composition matters: narrow letters like `l`/`i`/`f` push the per-char average down, tall letters like `B`/`J`/`P`/`Q` push it up.

| Text                                    | Chars | Weight | Size  | Measured width | Per-char |
|-----------------------------------------|-------|--------|-------|----------------|----------|
| `Authentication Service`                | 22    | 500    | 14 px | 167 px         | ~7.6     |
| `Background Job Processor`              | 24    | 500    | 14 px | 201 px         | ~8.4     |
| `Detects and validates incoming tokens` | 37    | 400    | 14 px | 279 px         | ~7.5     |
| `forwards request to`                   | 19    | 400    | 12 px | 123 px         | ~6.5     |
| `データベースサーバー接続`               | 12    | 400    | 14 px | 181 px         | ~15.1    |

The formula uses **8** for 14px Latin and **7** for 12px Latin because those are the safe ceilings, not the average. A label like "Background Job Processor" at 8.4 px/char would overflow a box sized from a 7.6 px/char average — always round up, never down.

**Worked sanity check**: `"Detects and validates incoming tokens"` (37 chars, `ts` class at 12px) → formula gives `37 × 7 + 24 = 283 px`. Measured 279 px + 24 px padding = 303 px. The formula is ~7% conservative, which is the correct direction for rect sizing — bias toward extra padding, never toward clipping.

### Rect sizing formula

For a two-line node (title + subtitle) the width must fit whichever line is longer:

```
width_needed = max(title_chars × 8, subtitle_chars × 7) + 24
```

The `+ 24` is 12px of horizontal padding on each side. If the text is centered, that's 12px of clear air between the text edge and the rect stroke — looks balanced.

For a single-line node:

```
width_needed = title_chars × 8 + 24
```

For CJK content, replace the 8 with 15 and the 7 with 13.

**Round up to the nearest 10px** for cleaner coordinates. A box that "needs" 167px becomes 170px.

### Worked examples

- `"JWT authentication"` (18 chars, title) → `18 × 8 + 24 = 168` → round to **170**
- `"Validates user credentials"` (26 chars, subtitle) in a two-line box with title `"Login service"` (13 chars, 8-wide) → `max(13 × 8, 26 × 7) + 24 = max(104, 182) + 24 = 206` → round to **210**
- `"微服务架构"` (5 CJK chars, title) → `5 × 15 + 24 = 99` → round to **100**
- `"发送 HTTP 请求 forwards request"` (mixed, treat CJK chars as 15px and Latin as 8px) → `3×15 + 4×8 + 13×8 = 45 + 32 + 104 = 181 + spaces + 24 ≈ 220`

**Rule of thumb**: if you find yourself adding characters to a label, recheck the width. It's easy to write "Authentication" once, size the box to fit, then expand it to "Authentication service" and forget to resize.

## viewBox height calculation

After placing every element, compute max_y:

1. For every `<rect>`, compute `y + height`.
2. For every `<text>`, the bottom is `y + 4` (roughly — 4px descent below the baseline).
3. For every `<circle>`, it's `cy + r`.
4. `max_y` is the maximum across all of these.
5. `H = max_y + 20`

**Don't guess.** A 20px buffer below the last element keeps things tight without clipping descenders.

**Don't leave huge empty space at the bottom.** If the diagram ends at y=280, H should be 300 — not 560. Excess whitespace below the content feels like a rendering bug.

## Tier packing (horizontal rows)

When placing N boxes in a horizontal row, check total width before you start writing coordinates:

```
total = N × box_width + (N - 1) × gap
```

- `box_width`: chosen to fit the longest label in that row
- `gap`: 20px minimum between adjacent boxes

Required: `total ≤ 600` (the usable width). If not, one of three things must give:

1. **Shrink box_width** — cut subtitles, shorten titles
2. **Wrap to 2 rows**
3. **Split into an overview diagram + detail diagrams** (one per sub-flow)

### Worked example — four consumer boxes

- 4 boxes, each containing `"Consumer N"` (10 chars title) and `"Processes events"` (16 chars subtitle)
- Needed width per box: `max(10×8, 16×7) + 24 = max(80, 112) + 24 = 136` → round to **140**
- 4 boxes × 140 + 3 gaps × 20 = 560 + 60 = **620** → **overflows** by 20
- Fix: shrink to **130** each (check: `max(10×8, 16×7) + 24 = 136`, so 130 is tight — cut subtitle to 14 chars or drop it entirely)
- Or: drop to 3 boxes per row, stack the fourth below
- Or: 4 × 130 + 3 × 20 = 580, centered at `x = 40 + (600-580)/2 = 50` → boxes at x = 50, 200, 350, 500

## Swim-lane (sequence) layout

Sequence diagrams have their own coordinate system — actor columns ("lanes") along the top, dashed lifelines running down, numbered horizontal messages between them. The numbers below are fixed conventions so every sequence diagram in the skill feels consistent.

### Lane widths and centers

N = number of actors. Lane width `lane_w`, header rect width `header_w = lane_w − 20`, lifeline x = lane center. Gap between lanes = 20.

| N | lane_w | header_w | First offset | Lane centers (x)               |
|---|--------|----------|--------------|--------------------------------|
| 2 | 290    | 270      | 40           | 185, 495                       |
| 3 | 186    | 166      | 40           | 133, 340, 547                  |
| 4 | 140    | 120      | 30           | 100, 260, 420, 580             |
| 5 | 112    |  92      | 26           | 82, 214, 346, 478, 610         |
| 6 | 100    |  80      | 30           | 80, 190, 300, 410, 520, 630    |

Hard cap: **4 actors** (comfortable), **6 actors** (maximum). 5 is allowed only when every actor title is ≤12 characters and has no subtitle. 6 requires every title ≤9 characters (`9 × 8 + 24 = 96`, just inside `header_w=100`) and no subtitle. N=6 also collapses the intra-lane gap (the 20px padding between `lane_w` and `header_w` becomes 0 — the headers pack shoulder-to-shoulder) and borrows 10px of left-edge margin and all of the right-edge margin: the rightmost header rect sits flush against x=680. Use N=6 only when every actor is genuinely essential — otherwise merge actors or split the diagram. More than 6 doesn't fit 680px legibly.

### Vertical geometry (fixed for all sequence diagrams)

```
actor header box    y = 40..88       (height 48, rx 8)
title (th)          y = 60           (dominant-baseline="central")
role subtitle (ts)  y = 78           (optional, one line, ≤16 chars)
lifeline start      y = 92
first message row   arrow_y[0] = 120
message row pitch   44 px            → arrow_y[k] = 120 + 44 · k
lifeline tail       y = last_arrow_y + 24
```

### viewBox height

```
header_bottom    = 88
first_arrow_y    = 120
last_arrow_y     = 120 + 44 × (M − 1)          # M = number of messages
lifeline_bottom  = last_arrow_y + 24
note_bottom      = lifeline_bottom + 16 + 48   # only if side note is at the bottom
H                = max(lifeline_bottom, note_bottom) + 20
```

### Message arrows

Each message is a horizontal `<line>` at `y = arrow_y[k]`, running from the sender lifeline x to the receiver lifeline x with a 6px offset so the arrowhead doesn't touch the dashes:

- Left-to-right: `x1 = sender_x + 6`, `x2 = receiver_x − 6`
- Right-to-left: `x1 = sender_x − 6`, `x2 = receiver_x + 6`

Use `class="arr-{ramp}"` where `{ramp}` matches the sender's actor ramp. Always set `marker-end="url(#arrow)"`.

### Message labels

Label sits **above** the arrow at `y = arrow_y − 10` with `text-anchor="middle"`, `class="ts"`, and the number prefix baked into the text (`"1. Click login"`, not separate tspans). Label x is the midpoint of sender and receiver: `(sender_x + receiver_x) / 2`.

Max characters that fit in a label between two adjacent lanes (e.g. lanes 1↔2 for N=4):

```
label_chars_max ≈ (|sender_x − receiver_x| − 8) / 7
```

For N=4 adjacent lanes (|Δx|=160): ~21 chars. For the longest cross-diagram leap (lane 1↔4, |Δx|=480): ~67 chars. In practice, aim for ≤30 chars — short messages read faster, even when there's room.

### Self-messages

A self-message is a 16×24 `<rect>` using the actor's `c-{ramp}` class, horizontally centered on the lifeline: `rect_x = lifeline_x − 8`, `rect_y = arrow_y − 12`. The label sits **to the left** of the rect (so it stays inside the diagram for the rightmost lane) at `x = rect_x − 8` with `text-anchor="end"`, `class="ts"`, `dominant-baseline="central"`, and the same numbered format.

### Side note

A `class="box"` rect with a `th` title and optional `ts` subtitle. Default size 240×48, `rx="10"`. Placement depends on N:

- **N ≤ 3**: top-left at `(40, 40)` — tucks beside the first actor header, no overlap because `first_offset ≥ 40`.
- **N ≥ 4**: bottom-left at `(40, lifeline_bottom + 16)` — the top is packed tight against the leftmost header, so use the bottom margin.

### Worked example — OAuth 2.0 (N=4, M=10)

```
lane centers     100, 260, 420, 580     (lane_w=140, header_w=120)
header_bottom    88
first_arrow_y    120
last_arrow_y     120 + 44×9 = 516       (10 messages)
lifeline_bottom  540
note_bottom      540 + 16 + 48 = 604    (note at bottom)
H                604 + 20 = 624
viewBox          "0 0 680 624"
```

Label budgets: adjacent lanes (|Δx|=160) fit ~21 chars; "Redirect with client_id, scope" at 30 chars needs `|Δx| ≥ 218`, so it must span at least 2 lanes — put it between Client app (260) and Auth server (420), |Δx|=160 — **too tight**. Shorten to "Redirect (client_id + scope)" (28 chars, still over). Shorten further to "Redirect + client_id" (20 chars). Always verify every label against its span before finalizing.

## Centering inside the safe area

For N boxes of width `w` with gap `g`:

```
total = N × w + (N - 1) × g
offset = 40 + (600 - total) / 2
box[i].x = offset + i × (w + g)
```

Centered content feels deliberate. Left-aligned content feels incomplete.

## Sibling subsystem containers (2-up)

The structural subsystem-architecture pattern (see `structural.md` → "Subsystem architecture pattern") places **two sibling dashed-border containers** side by side, each holding a short internal flow. The 2-up layout sacrifices the default 40px horizontal safe margin in exchange for a usable container interior wide enough to hold 3–4 flowchart nodes.

Standard 2-up geometry at viewBox width 680:

```
container_w      = 315               # each sibling
container_gap    =  10                # space between siblings
left_margin      =  20                # leaner than the usual 40
container_A.x    =  20
container_B.x    = 345               # left_margin + container_w + container_gap
rightmost edge   = 345 + 315 = 660   # leaves 20px to x=680
interior_w       = 315 − 40 = 275    # after 20px padding on each side
interior_A.x     =  40
interior_B.x     = 365
```

Inside each 275-wide interior, node widths follow the normal text-width formula but should cap at ~235 so the L-bend connectors have clear vertical channels on both sides. Typical nodes are 180 wide centered, or 150 wide for a 2-column row.

A **labeled cross-system arrow** bridges the 10px container gap:

```
from B_right_node.right_edge  → to A_left_node.left_edge
arrow_x1 = interior_B.rightmost_node.x + 10
arrow_x2 = interior_A.leftmost_node.x  − 10
arrow_y  = matching row y                 # both nodes on the same tier
label at (x_mid, arrow_y − 6), class="ts", text-anchor="middle"
```

The cross-system arrow label is the one place where a flowchart-style connector *must* have a label — the reader cannot infer the relationship from the container titles alone. Keep the label to ≤3 words.

Dashed container borders use **inline `stroke-dasharray="4 4"`** on the `<rect>` rather than a CSS class — dashed is a one-off container-styling concern, not a reusable shape property, so the template's class list stays stable.

### Worked example — Pi session + Background analyzer

Two siblings, each with 3 internal nodes stacked vertically:

```
container A "Pi session"           container B "Background analyzer"
x=20, y=40, w=315, h=260            x=345, y=40, w=315, h=260
rx=20, stroke-dasharray="4 4"       same styling

Inside A (x_center = 177):           Inside B (x_center = 502):
  [ User input     ] y=96           [ Analyze patterns ] y=96
  [ Pi responds    ] y=170          [ Write summary    ] y=170
  [ (session ends) ] y=244          [ Update memory    ] y=244

Cross-system arrow: B top row → A top row at y=118
  x1 = 347 (container B left edge + 2)? No — from interior node B₁ left edge
  Actually: from B₁.x − 10 (headed right-to-left pointing at A₁)

Details below in structural.md's worked example.
```

viewBox H for 3 stacked rows: last node bottom y = 244 + 44 = 288; container bottom 40 + 260 = 300; H = 300 + 20 = **320**.

## Sub-pattern coordinate tables

Fixed coordinate tables for the sub-patterns introduced in `structural.md`, `illustrative.md`, and `sequence.md`. Use these values verbatim — they're tuned so each sub-pattern respects the 680 viewBox and the 40 safe margin.

### Bus topology geometry

For `structural.md` → "Bus topology sub-pattern". A central horizontal bar bridges N agents above it and N agents below it.

| Element                    | Coordinates                              |
|----------------------------|------------------------------------------|
| Bus bar                    | `x=40 y=280 w=600 h=40 rx=20`            |
| Bus label baseline         | `y=304`, `text-anchor="middle"` at x=340 |
| Top agent row (box top)    | `y=80`, `h=60`                           |
| Bottom agent row (box top) | `y=400`, `h=60`                          |
| Default viewBox H          | 500                                      |

Agent centers by row count:

| Agents per row | Box width | Centers (x)                                |
|----------------|-----------|--------------------------------------------|
| 2              | 180       | 180, 500                                   |
| 3              | 140       | 170, 340, 510                              |
| 4              | 110       | 120, 260, 420, 560                         |

Publish/subscribe arrow pair: two vertical lines per agent, offset by 8px horizontally (one at `agent_cx − 8`, one at `agent_cx + 8`). Publish goes down from agent to bar; Subscribe goes up from bar to agent. Labels sit at the channel midpoint y, `text-anchor="end"` (Publish on left) and `text-anchor="start"` (Subscribe on right).

### Radial star geometry (3 / 4 / 5 / 6 satellites)

For `structural.md` → "Radial star topology sub-pattern". A central hub surrounded by N peripheral satellites, each bidirectionally connected.

**Hub (always fixed):**

| Element       | Coordinates                |
|---------------|----------------------------|
| Hub rect      | `x=260 y=280 w=160 h=80 rx=10` |
| Hub center    | `(340, 320)`               |
| viewBox H     | 560                        |

**Satellite positions:**

| N | Satellites (box top-left → w=160 h=60)                                           |
|---|-----------------------------------------------------------------------------------|
| 3 | `(60, 120)`, `(460, 120)`, `(260, 460)`                                           |
| 4 | `(60, 120)`, `(460, 120)`, `(60, 460)`, `(460, 460)`                              |
| 5 | `(260, 60)`, `(60, 200)`, `(460, 200)`, `(60, 460)`, `(460, 460)`                 |
| 6 | `(20, 120)`, `(260, 60)`, `(500, 120)`, `(20, 460)`, `(260, 520)`, `(500, 460)`   |

Satellite centers: add `(80, 30)` to the box top-left to get `(cx, cy)`.

**Arrow pairs:** each satellite connects to the hub with two single-headed arrows offset by 8 px perpendicular to the arrow direction. For a satellite at `(sx, sy)` and hub center `(340, 320)`, compute the direction vector, normalize to unit length, then offset each line by `(+4dy, −4dx)` and `(−4dy, +4dx)` respectively (where `(dx, dy)` is the unit direction).

For straightforward placement, use these pre-computed endpoint offsets for N=4:

| Satellite center | Outbound start (satellite → hub) | Outbound end |
|------------------|----------------------------------|--------------|
| TL `(140, 150)`  | `(224, 176)`                     | `(264, 276)` |
| TR `(540, 150)`  | `(456, 176)`                     | `(416, 276)` |
| BL `(140, 490)`  | `(224, 464)`                     | `(264, 364)` |
| BR `(540, 490)`  | `(456, 464)`                     | `(416, 364)` |

Inbound (hub → satellite) is the reverse of each outbound, offset perpendicular by 8.

### Spectrum geometry

For `illustrative.md` → "Spectrum / continuum". A 1-D axis with end labels, tick points, option boxes, and italic captions.

**Fixed vertical positions:**

| Element                   | Coordinates                                |
|---------------------------|--------------------------------------------|
| Eyebrow (optional)        | `y=50`, `text-anchor="middle"` at x=340    |
| End labels (L / R)        | `y=120`, at `x=80` (start) / `x=600` (end) |
| Axis line                 | `x1=80 y1=140 x2=600 y2=140`               |
| Tick circles              | `cy=140`, `r=6`                            |
| Option box top            | `y=200`, `h=60`                            |
| Caption line 1            | `y=292`, italic `ts`                       |
| Caption line 2            | `y=308`, italic `ts`                       |
| Default viewBox H         | 332                                        |

**Tick and option-box x positions by tick count:**

| Ticks | Tick centers (x)            | Option box x (w=120)        |
|-------|-----------------------------|-----------------------------|
| 2     | 200, 480                    | 140, 420                    |
| 3     | 160, 340, 520               | 100, 280, 460               |
| 4     | 140, 280, 420, 560          | 80, 220, 360, 500           |
| 5     | 120, 240, 360, 480, 600 (w=100) | 70, 190, 310, 430, 550      |

Axis uses `marker-start` **and** `marker-end` (both ends arrowed to signal no natural direction). Axis stroke class is `arr` (neutral gray) — never a color ramp.

Sweet-spot tick and its option box use `c-green` or `c-amber`; all other ticks and boxes stay `c-gray`. Captions cap at 24 characters per line, 2 lines per option.

### Parallel rounds geometry

For `sequence.md` → "Parallel independent rounds". Stacked independent call/response rounds without shared lifelines.

**Stacked rounds variant (full-width):**

| Element              | Coordinates                            |
|----------------------|----------------------------------------|
| Source actor         | `x=60  y=120 w=120 h=60`               |
| Round k action box   | `x=340 y=100 + (k-1)×80 w=160 h=48`    |
| Round k call arrow   | `y = 124 + (k-1)×80`                   |
| Round k response     | `y = 134 + (k-1)×80`                   |
| Call label           | `y = 115 + (k-1)×80`                   |
| Response label       | `y = 145 + (k-1)×80`                   |
| Row pitch            | 80                                     |

Arrow x endpoints: `x1 = source_right_edge + 6 = 186`, `x2 = action_left_edge − 6 = 334` (going right); reverse for the return arrow.

**Script-wrapper variant:**

| Element              | Coordinates                            |
|----------------------|----------------------------------------|
| Source actor         | `x=60  y=120 w=120 h=60`               |
| Script wrapper       | `x=240 y=100 w=140 h=260 rx=6`         |
| `{ }` label          | `(310, 124)`, class `th`               |
| Divider line         | `x1=256 y1=140 x2=364 y2=140`          |
| Wrapped band k       | `x=252 y=152 + (k-1)×60 w=116 h=48`    |
| External action box  | `x=440 y=200 w=160 h=48` (optional)    |
| Default viewBox H    | 380                                    |

Up to 3 wrapped bands inside the script wrapper (with `script_h = 260`). Grow `script_h` by 60 for each additional band.

**Inside a 315-wide subsystem container** (half-width), scale the coordinates:

| Element            | Container A (x=20)              |
|--------------------|---------------------------------|
| Source actor       | `x=40 y=120 w=100 h=50`         |
| Round k action     | `x=200 y=104 + (k-1)×64 w=120 h=40` |
| Row pitch          | 64                              |

### Multi-line box body line heights

For `structural.md` → "Multi-line box body". A three-line box used for advisor-role labels: title + italic role + meta.

| Line       | y-offset from `rect_y`   | Class         |
|------------|--------------------------|---------------|
| Title      | `+22`                    | `th`          |
| Role       | `+42`                    | `ts` + italic |
| Meta       | `+62`                    | `ts` muted    |
| Min h      | 80                       |               |

Row pitch is 20. For a box at y=140, lines sit at `162, 182, 202`. Box height never drops below 80 — if the role or meta line is absent, use a standard 56-tall two-line box instead, don't shrink a three-line box.

### Annotation circle on connector geometry

For `illustrative.md` → "Annotation circle on connector". A labeled circle sitting above a pair of bidirectional arrows between two subjects.

| Element               | Coordinates                                  |
|-----------------------|----------------------------------------------|
| Subject A box         | `x=80  y=160 w=180 h=56`                     |
| Subject B box         | `x=440 y=160 w=180 h=56`                     |
| A → B arrow           | `(266, 184) → (434, 184)`, `arr`             |
| B → A arrow           | `(434, 204) → (266, 204)`, `arr`             |
| Arrow pair y midpoint | 194                                          |
| Annotation circle     | outer `c="box"` r=30 at `(cx, cy) = (350, 150)` |
| Inner pill            | `x=cx−28 y=cy+12 w=56 h=20 rx=10` (uses ramp)|
| Connector line        | `(cx, cy+30) → (cx, 194)`, `arr` (no marker) |

Label goes inside the pill at `(cx, cy+26)`, `th`, centered. Subject A/B labels use `th` at `(subject_cx, subject_cy)`.

### Container loop geometry (simple flowchart)

For `flowchart.md` → "Loop container". An outer rounded rect framing a simple flowchart.

| Element            | Coordinates                                |
|--------------------|--------------------------------------------|
| Container rect     | `x=20 y=40 w=640 h=H−60 rx=20`, class `box`|
| Title              | `(340, 72)`, class `th`                    |
| Subtitle           | `(340, 92)`, class `ts`                    |
| First inner box y  | ≥ 116                                      |
| Inner safe area    | `x ∈ [40, 620]`                            |
| Bottom padding     | 20px                                       |

After placing the inner flow, compute `inner_bottom = max y of any inner element`, then `H = inner_bottom + 40` and `container_h = H − 60`.

## Arrow routing

Every arrow has a start point (source box edge) and an end point (target box edge), with an optional bend in between.

**Direct arrow** — when source and target are aligned on an axis (same x for vertical, same y for horizontal):

```svg
<line x1="200" y1="76" x2="200" y2="120" class="arr" marker-end="url(#arrow)"/>
```

Leave **10px** between the arrow's endpoint and the target box's top edge so the arrowhead doesn't touch the border.

**L-bend arrow** — when the direct line would cross another box:

```svg
<path d="M x1 y1 L x1 ymid L x2 ymid L x2 y2" class="arr" fill="none" marker-end="url(#arrow)"/>
```

- `ymid` is a horizontal "channel" chosen to thread cleanly between the two levels
- Always include `fill="none"` on `<path>` used as a connector — SVG defaults to black fill

**Collision check.** Before finalizing every arrow, trace its path against every rect you've already placed:

```
for each rect R in the diagram:
  if rect R is not the source or target of this arrow:
    does the arrow's line segment intersect the interior of R?
    if yes: use an L-bend to route around R
```

This is the #1 diagram failure mode. Arrows slashing through unrelated boxes.

**Connection-point convention.** Every arrow anchors to the midpoint of a box edge (top, bottom, left, or right), never to a corner. With `rx="6"` or `rx="12"` rounded corners, the actual corner curve occupies the first ~6–12px of each edge — so stay **≥20px from any corner** when picking a connection point. An arrow that enters a box 4px from its corner reads as "touching the rounded curve" instead of "attached to the edge", and the arrowhead looks smeared. For a 180-wide rect, valid top-edge connection points sit at `x ∈ [rect_x + 20, rect_x + 160]`; the outer 20px on each side belong to the corner radius.

**Multi-arrow stagger.** When two or more arrows terminate on the same edge of the same box from different sources (three fan-in arrows hitting a single aggregator; two feedback lines returning to a start node), stagger their arrival points by **≥12px** along the target edge. Example: three arrows fanning into the top edge of a 180-wide box sit at `target_x − 24`, `target_x`, `target_x + 24`. Same rule applies to horizontal arrows converging on a left/right edge (stagger the y by ≥12px). Without the stagger, the arrowheads stack on top of each other and the reader can't tell how many incoming edges there are — a 3-to-1 fan-in reads as a single thick arrow.

## text-anchor safety

`text-anchor` controls which point of the text aligns to the `x` coordinate:

- `"start"` — x is the left edge. Text extends right.
- `"middle"` — x is the horizontal center. Text extends both ways.
- `"end"` — x is the right edge. Text extends left.

**Danger**: `text-anchor="end"` at low x values. If `x=50` and the label is 200px wide, the text starts at `x = -150` — outside the viewBox. Check: `label_chars × 8 < x` must hold for `text-anchor="end"` labels.

**Default to `text-anchor="start"` on the left side and `"middle"` in the center.** Use `"end"` only when you've verified the x coordinate is high enough.

## Vertical text centering inside a rect

Every `<text>` inside a rect needs `dominant-baseline="central"`. Without it, SVG treats `y` as the baseline — the glyph body sits ~4px above where you think and descenders hit the next line.

```svg
<rect x="100" y="20" width="180" height="44" rx="6" class="c-blue"/>
<text class="th" x="190" y="42" text-anchor="middle" dominant-baseline="central">Login</text>
```

For a rect at `(x, y, w, h)`:
- Single line centered: `text_x = x + w/2`, `text_y = y + h/2`, `dominant-baseline="central"`
- Two lines (44 + 14 layout inside a 56-tall box):
  - Title: `text_y = y + 20` (center of top 40px)
  - Subtitle: `text_y = y + 40` (center of bottom 16px)
  - Both use `dominant-baseline="central"`

## Quick-reference sizes

Standard dimensions that work well and keep the diagram rhythm consistent:

| Element                     | Size                 |
|-----------------------------|----------------------|
| Single-line node height     | 44 px                |
| Two-line node height        | 56 px                |
| Default node width          | 180 px (adjust up)   |
| Minimum gap between nodes   | 20 px horizontal, 60 px vertical |
| Container padding           | 20 px                |
| Rect corner radius          | `rx="6"` (subtle), `rx="12"` (container), `rx="20"` (outer container) |
| Connector stroke width      | 1.5 px (set by `.arr`) |
| Diagram border stroke       | 0.5 px                |
| Viewport safe margin        | 40 px on each edge    |

Stick to these unless you have a concrete reason to deviate.