Build a diagram compiler, not a template library.

How to use this guide

Start with the decision register when selecting an architecture. Use the middle sections as implementation contracts. Use the quality gates and red-team findings as release criteria.

Problem framing

Diagram-as-code systems often collapse modeling, styling, layout, rendering, and interaction into one syntax. That works for small diagrams. It fails for distributed systems, ontology, lineage, trust boundaries, runtime state, mobile navigation, and multi-audience communication.

Tool landscape

The major tools operate at different layers. They should be composed rather than compared as if they solve the same problem.

Diagram question taxonomy

A diagram should be selected by the question it must answer. One diagram should have one primary communication question.

Canonical model and view compiler

The system should model the system once, then compile only the view needed to answer the current question.

interface DiagramModel {
  id: string;
  version: string;
  generatedAt: string;
  entities: Entity[];
  relationships: Relationship[];
  groups: Group[];
  vocabularies: Vocabulary[];
  evidence: EvidenceRecord[];
  sourceRegistry: SourceRecord[];
}

interface DiagramView {
  id: string;
  title: string;
  question: string;
  audience: string[];
  perspective:
    | "architecture"
    | "runtime"
    | "deployment"
    | "lineage"
    | "ontology"
    | "security"
    | "ownership"
    | "temporal";
  rootIds: string[];
  include: ViewPredicate[];
  exclude: ViewPredicate[];
  depth: number;
  relationshipKinds: string[];
  layoutPolicy: LayoutPolicy;
  visualPolicy: VisualPolicy;
  interactionPolicy: InteractionPolicy;
  responsivePolicies: ResponsiveViewPolicy[];
}

Layout system

Layout selection must be question-driven. Different algorithms express different semantic relationships.

Layout router

function selectLayout(ctx: LayoutContext): LayoutFamily {
  if (ctx.hasTimeAxis) return "timeline";
  if (ctx.hasGeography) return "geographic";
  if (ctx.hasFixedPositions || ctx.hasSemanticLanes) return "constraint";
  if (ctx.isRootedTree && !ctx.hasContainment) return "tree";
  if (ctx.isDirectedAcyclic || ctx.dominantDirectionRatio >= 0.7) {
    return ctx.hasContainment ? "compound" : "layered";
  }
  if (ctx.highDegreeNodeCount > 0 && ctx.purpose === "explain") {
    return "radial";
  }
  if (ctx.purpose === "explore") return "force";
  return "constraint";
}

Visual language

Each visual channel should have one dominant meaning. The same color, border, or line type must not encode unrelated dimensions.

Relationship grammar

Settings architecture

The system should separate environment, reusable design decisions, semantic recipes, matching rules, and deliberate exceptions.

Semantic cascade

The system should use an ordered, property-by-property cascade. It should not reproduce CSS specificity.

Channel ownership

Tokens, named styles, rules, and expressions

Token layers

1. Primitive tokens
   Literal colors, dimensions, timing values, and font families.
2. Semantic tokens
   Meaning-bearing aliases such as color.node.service.fill.
3. Context modifiers
   Light, dark, high contrast, screen, print, mobile, desktop, compact, reduced motion.
4. Resolved map
   Concrete values for the active context before element rules are applied.

Named style example

styles:
  node.service:
    appliesTo: node
    facet: kind
    properties:
      shape: rounded-rectangle
      fill: "{color.node.service.fill}"
      borderColor: "{color.node.service.border}"
      icon: "{icon.node.service}"
      paddingInline: "{space.node.padding.inline}"
      paddingBlock: "{space.node.padding.block}"
    legend:
      group: Elements
      label: Service
      description: Independently deployable software service

Rule example

rules:
  - id: services
    layer: kind
    select:
      kind: service
    use:
      - node.service

  - id: deprecated-elements
    layer: facet
    select:
      tags:
        contains: deprecated
    use:
      - lifecycle.deprecated

Restricted expression example

{
  "$expr": [
    "step",
    ["zoom"],
    "hidden",
    0.65,
    "title-only",
    1.0,
    "title-and-technology",
    1.4,
    "full"
  ]
}

Legend system

The legend must be generated from the same semantic style definitions that render the diagram.

1. Resolve the current view.
2. Resolve computed styles for visible elements.
3. Record semantic styles that contributed visible meaning.
4. Deduplicate and order legend entries.
5. Render swatches using the same resolved tokens.
6. Add continuous scales for quantitative mappings.
7. Exclude interaction-only states unless an interaction guide is requested.

Payment API
──────────────────────────────────
fill
  Result: #315DA8
  Token: color.node.service.fill
  Context: dark / standard contrast
  Applied by: style node.service
  Rule: kind = service

borderStyle
  Result: dotted
  Applied by: style lifecycle.deprecated
  Rule: tag contains deprecated

size
  Result: large
  Applied by: element override
  Reason: Primary subject of decision view

Text, node sizing, and alignment

Layout must use measured node dimensions after the final font and content are available.

1. Load the actual font.
2. Normalize title and metadata content.
3. Measure text runs and semantic wrap points.
4. Calculate width, height, icon rail, badges, and ports.
5. Run layout and route edges.
6. Measure edge labels and detect collisions.
7. Repair spacing, scope, or orientation.

Alignment rules

• Use a fixed icon or number rail.
• Top-align leading icons, badges, or numbers with the title stack.
• Do not vertically center them against title-plus-description height.
• Reset heading margins inside nodes.
• Use a shared spacing scale for padding, labels, ports, and lane gutters.
• Validate optical centering of SVG glyphs inside wrappers.
• Never shrink text below the readability floor simply to fit the full graph.

Mobile and viewport behavior

A mobile diagram is a different projection of the same model, not a desktop screenshot scaled down.

Semantic zoom

Input and accessibility

Provide pinch zoom, wheel and trackpad zoom, pan, keyboard traversal, search, breadcrumbs, a synchronized node list, non-drag alternatives, focus visibility, screen-reader summaries, and reduced-motion behavior.

Quality gates

Complexity repair order

1. Remove unrelated relationships.
2. Aggregate repeated nodes.
3. Collapse lower-level groups.
4. Replace repeated edges with aggregate edges.
5. Move metadata into details.
6. Split temporal and structural concerns.
7. Generate coordinated views.
8. Introduce semantic zoom and neighborhood isolation.

Skill and memory design

The future diagram-architect skill should retain durable decision logic, renderer limitations, battle scars, validation rules, and accepted fixtures.

diagram-architect/
├── SKILL.md
├── CHANGELOG.md
├── references/
│   ├── diagram-question-taxonomy.md
│   ├── visual-language.md
│   ├── layout-router.md
│   ├── style-system.md
│   ├── token-resolution.md
│   ├── legend-generation.md
│   ├── responsive-diagrams.md
│   └── evaluation-framework.md
├── profiles/
│   ├── c4-architecture.md
│   ├── topology.md
│   ├── ontology.md
│   ├── lineage.md
│   ├── state-machine.md
│   ├── process-swimlane.md
│   └── timeline-gantt.md
├── battle-scars/
│   ├── connector-border-collision.md
│   ├── layout-before-measurement.md
│   ├── unreadable-fit-view.md
│   ├── mobile-desktop-shrink.md
│   ├── css-specificity-war.md
│   ├── legend-drift.md
│   ├── one-off-color-language.md
│   └── raw-literal-proliferation.md
└── evals/
    ├── routing.json
    ├── geometry.json
    ├── responsive.json
    ├── accessibility.json
    └── comprehension.json

Retrieval workflow

1. Classify the diagram question.
2. Retrieve one primary diagram profile.
3. Retrieve one renderer profile.
4. Retrieve five to nine relevant battle scars.
5. Select one primary layout technique.
6. Compile, audit, repair, and record reusable findings.

Recommended system decisions

These decisions form the initial architecture baseline. Each remains reversible until production fixtures and performance evidence justify commitment.

Implementation roadmap

Repository shape

diagram-system/
├── packages/
│   ├── model/
│   ├── ingestion/
│   ├── view-compiler/
│   ├── visual-language/
│   ├── layout/
│   ├── renderers/
│   ├── exporters/
│   └── evaluation/
├── skills/
│   └── diagram-architect/
├── fixtures/
│   ├── topology/
│   ├── ontology/
│   ├── lineage/
│   ├── sequence/
│   ├── state/
│   └── mobile/
└── apps/
    ├── diagram-studio/
    └── static-artifact-builder/

Material risks and controls

Primary sources

This guide consolidates the prior research and design synthesis. The following primary references informed the conclusions.

Evidence map

1. LikeC4 documentation
2. Structurizr documentation
3. Mermaid diagram syntax and examples
4. Mermaid theming and configuration
5. React Flow API reference
6. React Flow layout guidance
7. React Flow accessibility guidance
8. Cytoscape.js documentation
9. Cytoscape.js layout guidance
10. Sigma.js documentation
11. AntV G6 layout overview
12. AntV X6 overview
13. ELK Layered reference
14. Graphviz layout engines
15. Kroki diagram rendering gateway
16. yFiles for HTML
17. GoJS documentation
18. D2 classes
19. Vega-Lite configuration
20. Mapbox style expressions
21. Design Tokens Community Group format
22. Material Color Utilities
23. D3 chromatic scales
24. WCAG 2.2
25. WCAG animation guidance
26. OpenLineage object model
27. Physics of Notations

Methodology

The research was organized by problem layer: modeling, view selection, visual language, style resolution, layout, rendering, interaction, accessibility, and validation. Tool capabilities were treated as complementary. Recommendations were then red-teamed against portability, mobile use, semantic clarity, renderer limitations, and long-term maintainability.