Design system foundations for visual artifacts -- 8px grid spacing, typography scales, color contrast, border weights, vertical rhythm, and colorblind-safe palettes. Use when creating or styling any visual artifact -- diagrams, charts, presentations, documents, or exports. Provides concrete token values that snap to an 8px baseline grid.
Design system foundations for visual artifacts -- 8px grid spacing, typography scales, color contrast, border weights, vertical rhythm, and colorblind-safe palettes. Use when creating or styling any visual artifact -- diagrams, charts, presentations, documents, or exports. Provides concrete token values that snap to an 8px baseline grid.
user-invocable
false
Design System
Foundational design tokens and rules for visual artifacts -- diagrams, charts, presentations, and print exports. Every spacing, typography, and sizing value snaps to an 8px baseline grid (with 4px half-steps for fine adjustments).
Core Principles
The 8px Grid
All spatial values are multiples of 8. Use 4px only for sub-component adjustments (icon gaps, type alignment). This creates visual rhythm, reduces decision fatigue, and ensures pixel-perfect rendering on 1x, 1.5x, 2x, and 3x displays.
4 -- 8 -- 16 -- 24 -- 32 -- 48 -- 64 -- 80 -- 96
Contrast First
Every color pairing must meet WCAG AA minimum: 4.5:1 for text, 3:1 for borders and graphical objects. Use the Okabe-Ito palette for colorblind safety.
Borders Are Not Spacing
Stroke widths use their own 1-3px scale. The 8px grid applies to layout spacing only.
Spacing Scale
Token
px
Use
xs
8
Icon-to-text gaps, tight internal spacing
sm
16
Node padding, compact element spacing
md
24
Comfortable padding, sub-section spacing
lg
32
Diagram margins, section separation
xl
48
Node spacing (compact layouts)
2xl
64
Node spacing (standard layouts)
3xl
80
Node/rank spacing (spacious layouts)
4xl
96
Page-level spacing
When to use 4px: Only for within-component micro-adjustments -- never for layout spacing between elements.
Typography Scale
Font sizes can be any value -- only line heights and outer spacing must snap to the grid. Line heights use a 4px sub-grid (like Material Design 3).
Icon stroke: 2px standard (Material Design convention). Use 1.5px for tight spaces as optical correction.
Color Contrast Requirements
WCAG compliance for diagram elements:
Element
Against
Minimum (AA)
Recommended (AAA)
Text on colored node fill
Fill color
4.5:1
7:1
Large text (>=18px bold) on fill
Fill color
3:1
4.5:1
Node border on background
Background
3:1
4.5:1
Adjacent colored regions
Each other
3:1
4.5:1
Lines/edges
Background
3:1
4.5:1
Colorblind-Safe Palette (Okabe-Ito)
The gold standard for categorical color -- works for protanopia, deuteranopia, AND tritanopia. Each color has distinct luminance, so the palette works in grayscale too.
Name
Hex
Use
Blue
#0072B2
Primary nodes, main flow
Sky Blue
#56B4E9
Info, secondary nodes
Bluish Green
#009E73
Success, completed states
Orange
#E69F00
Warning, caution states
Yellow
#F0E442
Highlight, attention
Vermillion
#D55E00
Error, danger
Reddish Purple
#CC79A7
Accent, special emphasis
Black
#000000
Text, borders
Max colors per diagram: 6 categorical colors. Beyond 8, use shapes/patterns/labels instead.
Safest pairs: Blue + Orange, Blue + Yellow, Purple + Yellow.
Avoid: Red + Green, Green + Brown, Blue + Purple.
Quality Checklist
When applying the design system, verify:
All spacing values are multiples of 8 (or 4 for micro-adjustments)
Line heights snap to the 4px sub-grid (16, 20, 24, 28, 32)
Text on colored fills meets 4.5:1 contrast (AA)
Borders and graphical objects meet 3:1 contrast (AA)
No more than 6 categorical colors per diagram
No red+green, green+brown, or blue+purple color pairs
Stroke widths use 1px (default), 2px (emphasis), or 3px (heavy) -- not 8px grid values
Font weights follow hierarchy: 400 body, 500 labels, 600-700 titles
References
color-contrast.md -- Full color system: semantic roles, M3 color architecture, IBM Carbon data viz palette, palette construction rules
mermaid-tokens.md -- Mapping design tokens to Mermaid config properties with concrete preset examples
research-sources.md -- Full research data with sources from Material Design, IBM Carbon, Atlassian, GitLab Pajamas, USWDS, and academic references
