Agent skill
design-system
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.
Install this agent skill to your Project
npx add-skill https://github.com/nathanvale/side-quest-marketplace/tree/main/plugins/cortex-engineering/skills/design-system
SKILL.md
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
Recommended Agent Skills
Expand your agent's capabilities with these related and highly-rated skills.
nathanvale/side-quest-marketplace
cli-mcp-decision
Decide whether a workflow should use CLI skills, MCP, or a hybrid approach. Use when planning agentic tooling, writing ADRs, or evaluating migrations between CLI and MCP.
nathanvale/side-quest-marketplace
agent-cli
Patterns for building CLIs that serve both humans and AI agents. Covers tri-modal output (JSON/JSONL/human), typed exit codes, structured error contracts, zero-dependency arg parsing, topic-based help, service discovery, field projection, and auto agent-mode detection. Reference implementation: @side-quest/observability CLI. Use when: building a CLI, adding a command, CLI output format, agent-friendly CLI, machine-readable output, JSON CLI contract, exit codes, --json flag, NDJSON streaming, how should my CLI work with agents, CLI design patterns.
nathanvale/side-quest-marketplace
explain-codebase
Generate an engaging, deep-dive explanation document (FOR_[NAME].md) that explains a codebase or domain in plain language with analogies, lessons learned, and practical wisdom.
nathanvale/side-quest-marketplace
vscode-bookmarks
Create and manage VS Code Bookmarks extension labeled bookmarks in .vscode/bookmarks.json. Use when the user wants to add navigation bookmarks to a codebase, trace data flows through code, mark important code locations, or set up labeled waypoints for code walkthroughs. Also use when user says "bookmark", "label this code", "mark this flow", or "add waypoints".
nathanvale/side-quest-marketplace
manage-plugins
Add or remove inline plugins from the ccdev function in dotfiles .zshrc
nathanvale/side-quest-marketplace
observability
Start, stop, or check status of the Side Quest observability event server. Use when asked to start the server, stop the server, check server status, or manage the observability dashboard lifecycle.
Didn't find tool you were looking for?