| name | design-system |
| description | Shared design principles for all diagram formats -- color theory, composition, typography, accessibility, and quality standards. Referenced by format-specific skills (svg, mermaid, excalidraw, d2). Use when generating any visual diagram to ensure professional quality. |
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:
| Concept | Color | Light Theme Hex | Use For |
|---|
| Platform / Core | Blue | #2563EB | Primary system components, APIs, services |
| Data / Storage | Blue (darker) | #1E40AF | Databases, data stores, caches |
| Success / Healthy | Green | #16A34A | Active states, successful flows, admin |
| Security / Error | Red | #DC2626 | Threats, errors, denied paths, trust boundaries |
| Warning / Caution | Amber | #D97706 | Deprecations, risks, attention needed |
| Compute / Processing | Purple | #7C3AED | Processing nodes, AI/ML, observability |
| External / Third-Party | Teal | #0891B2 | External systems, integrations, users |
| Inactive / Deprecated | Gray | #6B7280 | Disabled, archived, low-priority |
| Infrastructure | Slate | #475569 | Foundational platform, network |
Color-Blind Safe Palette
8% of males have color vision deficiency. Always follow these rules:
- Never rely on color alone -- pair with shape, pattern, label, or icon
- Avoid red-green adjacency without additional differentiation
- 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.
| Element | Light Theme | Dark Theme |
|---|
| Background | #FFFFFF or #F8FAFC | #0F172A or #1E293B |
| Primary text | #1E293B | #F1F5F9 |
| Secondary text | #64748B | #94A3B8 |
| Node fill | Light pastels | Muted darks |
| Node stroke | Medium tones | Slightly brighter |
| Connectors | #94A3B8 | #475569 |
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
| Element | Spacing |
|---|
| Between peer nodes | 40-60px |
| Padding inside nodes | 12-16px |
| Padding inside groups/containers | 20-30px |
| Gap between node and connector label | 8px |
| Edge routing clearance from unconnected nodes | >= 10px |
| Diagram margins | 40px+ |
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
| Elements | Action |
|---|
| 3-6 | Generate directly, compact canvas |
| 7-15 | Standard canvas, clear grouping |
| 16-20 | Consider splitting; ask user if unclear |
| 20+ | Must split into overview + detail diagrams |
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:
- Overview diagram: top-level components, max 7-10 nodes
- Detail diagrams: one per major component
- Consistent styling across overview and detail for cross-referencing
Typography
Size Hierarchy
| Element | Size | Weight |
|---|
| Diagram title | 20-24px | Bold (700) |
| Group/boundary label | 14-16px | Semi-bold (600) |
| Node label | 12-14px | Medium/Semi-bold (500-600) |
| Edge/connector label | 10-12px | Regular (400) |
| Annotation/note | 10-11px | Regular/Italic |
| Legend text | 10-12px | Regular (400) |
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"
- Grid alignment -- consistent x/y positioning
- Visual hierarchy -- size, color, and weight variation between element types
- Minimal edge crossings -- reroute or restructure
- Consistent spacing -- equal gaps between peer elements
- Breathing room -- generous whitespace, especially at margins
- Title and legend -- titled diagrams look finished; legends when color carries meaning
Consistency Rules (Non-Negotiable)
- Same type = same style: All databases look identical, all services look identical
- Same level = same size: Peer components at the same level have the same dimensions
- Same relationship = same line style: All "calls" arrows look the same
- Same semantic = same color: Blue means "data" everywhere, not just in one area
- Alignment: Nodes snap to a grid
- Spacing: Equal gaps between peer elements, predictable padding
Anti-Patterns to Avoid
- Rainbow soup: Too many unrelated colors with no semantic meaning
- Hairball: Too many crossing connections -- split the diagram
- Giant node: One node 3x larger without semantic reason
- Floating labels: Text near but not clearly associated with any element
- Inconsistent arrows: Mixing styles without defined meaning
- Tiny text on large canvas: Zoomed out too far to read
- 3D effects: Perspective, 3D boxes -- adds noise without information
- Color without meaning: Using color decoratively rather than semantically
- Text overflow: Labels that extend beyond their container boundaries
Effects: When They Help vs Hurt
| Effect | Use When | Avoid When |
|---|
| Gradient | Subtle on primary elements for depth | Applied uniformly to everything |
| Drop shadow | Lifting 1-2 key elements above the plane | Applied to every node |
| Border/stroke | Defining boundaries, showing containment | Thick borders on everything |
| Border radius | 4-8px for modern look | Fully circular for non-circular concepts |
| Opacity | Fading background/inactive elements (0.3-0.5) | Fading important elements |
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:
| User Intent | Best Diagram Type |
|---|
| "How does the system work overall?" | Architecture (layered) or C4 Context |
| "How do these services communicate?" | Sequence diagram |
| "Walk me through this process" | Flowchart |
| "Who handles each step?" | Swimlane |
| "What states can this be in?" | State machine |
| "Show the database schema" | ER diagram |
| "What depends on what?" | Dependency graph |
| "Compare these options" | Comparison (side-by-side) or table |
| "Show the project timeline" | Gantt / timeline |
| "What's the security boundary?" | Threat model / DFD |
| "Brainstorm / map this topic" | Mind map |
| "Show traffic distribution" | Sankey diagram |
| "What overlaps between these?" | Venn diagram |
| "What's the decision logic?" | Decision tree |
| "Central service with consumers" | Hub and spoke |
| "How is it deployed?" | Deployment diagram |
| "Org structure / hierarchy" | Tree / org chart |
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:
