Diagram Standard

Use D2 for diagrams that explain ownership, boundaries, event flows, architecture layers, or federation paths. The local D2 skill lives at .agents/skills/d2-diagramming.

When to use a diagram

Use a diagram when prose forces the reader to hold more than three relationships in working memory.

Good fits:

• bounded contexts and their relationships;
• Holochain application (hApp), zome, and bridge boundaries;
• event flows such as proposal to resolution to agreement;
• lifecycle transitions from informal group to fiscal host to incorporated entity;
• federation paths between organizations.

Weak fits:

• lists of terms;
• simple sequences with fewer than four steps;
• anything that needs precise quantitative comparison;
• diagrams that only decorate a page.

Source and rendered assets

Keep D2 source in diagrams/. Render web assets to public/diagrams/ as SVG. Prefer SVG for docs because it scales, stays readable, and can preserve links and tooltips when embedded correctly.

The current architecture diagram source is diagrams/solidarity-commons-architecture.d2. Its rendered asset is public/diagrams/solidarity-commons-architecture.svg.

Review rules

• Start with components, boundaries, and relationships before styling.
• Keep labels short. Put secondary detail in page prose.
• Split large diagrams instead of forcing every context into one canvas.
• Validate with d2 fmt and render the SVG before committing.
• If the diagram is architecture-critical, make sure the adjacent page explains the tradeoff the diagram is carrying.