design-system

name	design-system
description	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).

Role	Size	Line Height	Weight	Use
Caption	12px	16px	400	Labels, annotations, footnotes
Small	14px	20px	400-500	Edge labels, secondary text
Base	16px	24px	400	Node text, body content
Large	18px	24px	600-700	Subgraph titles, emphasis
Heading	20px	28px	600-700	Diagram titles
Display	24px	32px	700	Hero headings, covers

Font stack: Inter, Helvetica, Arial, sans-serif

Weight rules: 400 (body), 500 (labels/emphasis), 600-700 (titles/headings)

Border and Stroke Scale

Borders do NOT follow the 8px grid -- they use their own low-pixel scale. Above 4px, borders transition into spacing territory.

Level	Value	Use
Hairline	1px	Subtle dividers, decorative borders
Default	1px	Standard node borders
Medium	2px	Selected/active states, emphasis, focus rings
Heavy	3px	Strong emphasis, primary nodes

Border radius: 0 (sharp), 2px (subtle), 4px (rounded), 8px (pill-like)

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