excalidraw-architecture

# Excalidraw Architecture Create diagrams that explain a decision or route, not decorated inventories. ## Deliverables Unless the user narrows the request, deliver: 1. editable `.excalidraw`; 2. reviewable `.svg` and `.png`; 3. a one-paragraph reading guide; 4. the final scene opened in Excalidraw when browser delivery is useful. Use solid strokes for V1/current scope and dashed strokes for later scope. Add a visible legend. Do not reuse dashed strokes for uncertainty in the same architecture diagram. ## Workflow 1. **Read before drawing.** Inspect the source notes, repository, existing architecture, and audience. Write down the one question the diagram answers. 2. **Freeze semantics.** Separate current, later, external, derived, and authoritative components. Identify the main route, feedback route, trust boundary, and forbidden shortcuts. 3. **Choose one composition.** - Product story: left to right, 3-5 stages, outcome loop below. - System architecture: top to bottom layers, primary runtime left to right. - Lifecycle: circular only when the final state truly feeds the first. - Topology: hub and spoke only when one authority actually coordinates peers. 4. **Sketch hierarchy.** Use 5-9 primary groups. Give the primary route the shortest visual path. Put details inside labeled bands, not nested cards. 5. **Build the scene.** Follow [visual-system.md](references/visual-system.md) and [json-contract.md](references/json-contract.md). Mark scope-bearing elements with `customData.phase: "v1"` or `"later"`. 6. **Render and validate.** ```bash node ~/.codex/skills/excalidraw-architecture/scripts/render-excalidraw.mjs \ path/to/diagram.excalidraw --png path/to/diagram.png node ~/.codex/skills/excalidraw-architecture/scripts/validate-excalidraw.mjs \ path/to/diagram.excalidraw --png path/to/diagram.png ``` 7. **View the full-resolution PNG.** Fix clipping, collisions, weak hierarchy, bad wrapping, crowded arrows, excess whitespace, and route ambiguity. Render again after every meaningful edit. 8. **Audit the meaning.** Trace every important arrow. Confirm that readers cannot mistake a derived view for a source of truth or a proposal for an executed action. ## Drawing Rules - Prefer one strong visual argument over a grid of equal boxes. - Show overview, section boundaries, and concrete nodes at distinct zoom levels. - Keep connector labels short; put explanations beside the route, not on it. - Route connectors behind nodes and into edges. Avoid crossing text or entering arbitrary box corners. - Reserve accent color for one decision, write boundary, or critical transition. - Default to `roughness: 1`; use `0` only for dense technical regions and `2` only for a deliberately rough annotation. - Default text to Excalifont (`fontFamily: 5`), which uses Xiaolai as the current Excalidraw CJK hand-drawn fallback. Use Nunito (`6`) when dense technical copy needs a quieter voice. - Use font sizes `36 / 28 / 20 / 16 / 14`; never finish with body text below 14. - Keep titles to one line and bodies to three short lines where possible. - Use color plus labels and stroke style; never rely on color alone. - Add icons only when they identify a real platform or service faster than text. - Do not use gradients, shadows, decorative blobs, or ornamental arrows. ## Completion Gate Finish only when: - the audience and diagram question are obvious on first scan; - V1 and later scope are distinguishable without color; - every important route has a direction and valid endpoints; - no text is clipped, overlapping, or too small at export size; - contrast is at least 4.5:1 for normal text; - all nodes, bindings, IDs, and phase styles pass the validator; - the PNG has been visually inspected, not merely generated; - the editable source and rendered outputs describe the same frozen scene.