Design System

Diagram Design System

Universal design principles for professional-quality diagrams. These rules apply regardless of output format (SVG, Mermaid, Excalidraw, D2). Format-specific skills handle syntax; this skill handles aesthetics and composition.

Color

Palette Size

Use 3-5 colors plus grays per diagram. Maximum 7 distinct colors. Beyond that, humans cannot distinguish and remember meanings. If you need more categories, use shade variations within a hue family rather than adding new hues.

Semantic Color Conventions

Use color to convey meaning, not decoration. These associations are widely understood in software engineering:

Color-Blind Safe Palette

8% of males have color vision deficiency. Always follow these rules:

1. Never rely on color alone -- pair with shape, pattern, label, or icon
2. Avoid red-green adjacency without additional differentiation
3. Preferred safe palettes:
   • IBM: #648FFF, #785EF0, #DC267F, #FE6100, #FFB000
   • Wong: #E69F00, #56B4E9, #009E73, #F0E442, #0072B2, #D55E00, #CC79A7

Contrast (WCAG AA)

• Normal text on backgrounds: contrast ratio >= 4.5:1
• Large text (18px+ or 14px bold): >= 3:1
• Non-text elements (borders, icons, chart segments): >= 3:1 against adjacent colors
• White text on gradient fills (#0052CC, #006644, #5243AA) meets AA
• Never place mid-tone text on mid-tone backgrounds

Light vs Dark Theme

Design for light theme by default (white/light gray background). Most documentation, presentations, and print uses light backgrounds.

Layout & Composition

Flow Direction

• Left-to-right (LTR): Data flow, process pipelines, request lifecycles
• Top-to-bottom (TTB): Architecture layers (user at top, infrastructure at bottom), hierarchies
• Never mix directions in the same diagram without explicit visual cues
• Arrow direction must match flow direction

Spacing

Rule: All gaps of the same semantic type must be identical. If two peer nodes are 50px apart, all peer nodes at that level must be 50px apart.

Alignment

Nodes should snap to an implicit grid. Consistent x/y positioning signals intentional design. Center-align or left-align text consistently within a diagram -- never mix alignment styles for the same element type.

Grouping and Containment

• Bounding boxes (rounded rectangles with light fill) for logical groupings
• Group labels: top-left corner, inside the boundary
• Maximum 3 levels of nesting -- beyond that, split into separate diagrams
• Dashed borders for logical/virtual groupings; solid borders for concrete/physical boundaries
• Group fill color should be lighter/more transparent than contained node fills

Complexity Management

Additional split signals:

• More than 3 nesting levels
• Edge crossings exceed ~30% of total connections
• Diagram answers two different questions (make two diagrams)

Splitting strategy:

1. Overview diagram: top-level components, max 7-10 nodes
2. Detail diagrams: one per major component
3. Consistent styling across overview and detail for cross-referencing

Typography

Size Hierarchy

Rules:

• Maintain >= 2px size difference between hierarchy levels
• Never go below 10px -- it becomes illegible
• Title should be 1.5-2x the size of node labels

Font Usage

• Sans-serif (primary): -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Helvetica, Arial, sans-serif
• Monospace (code/technical): 'SF Mono', 'Cascadia Code', Consolas, 'Liberation Mono', Menlo, 'Courier New', monospace
• Bold: Node names, group titles, key terms (scannability)
• Italic: Annotations, optional metadata (signals "supplementary")
• Monospace: Code identifiers, ports, API paths, config values

Text in Nodes

• Maximum ~20 characters per node label; prefer meaningful abbreviation over truncation
• Maximum 2-3 lines inside a node
• If more text needed, use annotation/tooltip outside the node

Visual Quality Markers

What Makes a Diagram Look "Designed"

1. Grid alignment -- consistent x/y positioning
2. Visual hierarchy -- size, color, and weight variation between element types
3. Minimal edge crossings -- reroute or restructure
4. Consistent spacing -- equal gaps between peer elements
5. Breathing room -- generous whitespace, especially at margins
6. Title and legend -- titled diagrams look finished; legends when color carries meaning

Consistency Rules (Non-Negotiable)

1. Same type = same style: All databases look identical, all services look identical
2. Same level = same size: Peer components at the same level have the same dimensions
3. Same relationship = same line style: All "calls" arrows look the same
4. Same semantic = same color: Blue means "data" everywhere, not just in one area
5. Alignment: Nodes snap to a grid
6. Spacing: Equal gaps between peer elements, predictable padding

Anti-Patterns to Avoid

1. Rainbow soup: Too many unrelated colors with no semantic meaning
2. Hairball: Too many crossing connections -- split the diagram
3. Giant node: One node 3x larger without semantic reason
4. Floating labels: Text near but not clearly associated with any element
5. Inconsistent arrows: Mixing styles without defined meaning
6. Tiny text on large canvas: Zoomed out too far to read
7. 3D effects: Perspective, 3D boxes -- adds noise without information
8. Color without meaning: Using color decoratively rather than semantically
9. Text overflow: Labels that extend beyond their container boundaries

Effects: When They Help vs Hurt

Diagram Type Selection

When the user describes what they want but does not specify a diagram type, select based on the primary relationship they need to communicate:

If the content could work as multiple types, choose the one that highlights the primary relationship the reader needs to understand. When genuinely ambiguous, ask the user.

Quality Checklist

Before presenting any diagram, verify:

• Title present and descriptive
• Legend present if 3+ colors carry meaning
• Text readable (no truncation, no overlap, minimum 10px)
• Consistent spacing between peer elements
• Consistent styling for same-type elements
• Color used semantically (not decoratively)
• Maximum element count not exceeded for the diagram type
• Flow direction is consistent throughout
• Accessibility: color is not the sole differentiator