visualizing-with-mermaid

Name: visualizing-with-mermaid
Author: rileyhilliard/claude-essentials

$npx mdskill add rileyhilliard/claude-essentials/visualizing-with-mermaid

Generate professional Mermaid diagrams with semantic styling and visual hierarchy.

Converts process flows, API sequences, and system architectures into clear visual representations.
Selects diagram types based on the specific concept being illustrated.
Applies visual hierarchy and semantic color to guide user attention effectively.
Delivers diagrams adhering to cognitive limits with 7-12 nodes maximum.

SKILL.md

.github/skills/visualizing-with-mermaidView on GitHub ↗

---
name: visualizing-with-mermaid
description: Creates professional Mermaid diagrams with semantic styling and visual hierarchy. Use when creating flowcharts, sequence diagrams, state machines, class diagrams, or architecture visualizations.
---

# Mermaid Diagrams

**Default: Dark mode colors** from [references/color-palettes.md](references/color-palettes.md).

## Choosing Diagram Type

| Concept | Diagram Type |
|---------|--------------|
| Process flows, decisions | Flowchart (TB direction) |
| API calls, message passing | Sequence diagram |
| Lifecycle states | State diagram |
| Data models, relationships | Class diagram or ERD |
| System architecture | Flowchart with subgraphs (LR direction) |

## Core Principles

1. **Visual hierarchy over decoration** - Color/size guide the eye to what matters
2. **Semantic color** - Colors have meaning (grouping, state, criticality)
3. **Simplicity over completeness** - 80% clearly beats 100% confusingly
4. **7-12 nodes max** - Human working memory limit; break larger systems into drill-downs

## Quick Styling Guide

**Do:**
- Use fills to group related components
- Highlight critical paths with stroke width
- Different shapes = different component types (cylinders for DBs, diamonds for decisions)
- Keep labels to 1-4 words; use `<br/>` for longer

**Don't:**
- Pure black (`#000000`) - too harsh, use dark gray
- Saturated background colors - tire the eyes
- More than 5 colors per diagram
- Low-contrast combinations

## Shape Semantics

- **Rectangles**: Services, processes
- **Rounded rectangles**: APIs, interfaces
- **Circles**: Start/end points, external systems
- **Diamonds**: Decision points
- **Cylinders**: Databases
- **Hexagons**: Queues, message brokers

## Layout

**LR (left-to-right)**: Pipelines, architecture diagrams
**TB (top-to-bottom)**: Hierarchies, decision flows

Use **subgraphs** for: deployment boundaries, logical layers, team ownership, trust boundaries.

## Resources

- **Color palettes**: See [references/color-palettes.md](references/color-palettes.md)
- **Pattern examples**: See [references/examples.md](references/examples.md) for architecture, state machines, data flows, ERDs

## Workflow

1. **Purpose** - What decision/understanding should this enable?
2. **Type** - Choose based on what you're showing
3. **Structure** - Identify components, relationships, groupings
4. **Style** - Apply semantic colors, highlight critical paths
5. **Review** - Can someone understand it in 10 seconds?

More from rileyhilliard/claude-essentials

Skill	Description
architecting-systems	Guides clean, scalable system architecture during the build phase. Use when designing modules, defining boundaries, structuring projects, managing dependencies, or preventing tight coupling and brittleness as systems grow.
configuring-claude	Best practices for writing Claude Code skills, rules, and CLAUDE.md instructions. Use when creating SKILL.md files, authoring .claude/rules, writing CLAUDE.md project or user instructions, or configuring Claude behavior for a project or team.
fixing-flaky-tests	Diagnose and fix tests that pass in isolation but fail when run concurrently. Covers shared state isolation and resource conflicts. References condition-based-waiting for timing issues.
handling-errors	Prevents silent failures and context loss in error handling. Use when writing try-catch blocks, designing error propagation, reviewing catch blocks, or implementing Result patterns.
managing-databases	Guides database architecture decisions for PostgreSQL, DuckDB, Parquet, PGVector, and Neo4j. Use when designing schemas, choosing storage strategies, optimizing queries, tuning maintenance, configuring vector search, modeling graph data, or diagnosing performance issues across OLTP, OLAP, similarity search, and graph workloads.
managing-pipelines	Guides CI/CD pipeline architecture, security hardening, and deployment strategies for GitHub Actions. Use when designing workflows, securing supply chains, optimizing build performance, configuring deployments, managing infrastructure as code pipelines, or setting up pipeline observability.
migrating-code	Safe code migrations with backward compatibility and reversibility. Use when upgrading dependencies, changing database schemas, API versioning, or transitioning between technologies.
optimizing-performance	Measure-first performance optimization that balances gains against complexity. Use when addressing slow code, profiling issues, or evaluating optimization trade-offs.
planning-products	Defines product features from a PM perspective before technical planning begins. Use when scoping new features, writing product specs, defining user problems, choosing what to build, researching existing patterns, or bridging the gap between strategy and implementation. Covers JTBD analysis, competitive research, UX/DX experience definition, and scope negotiation for consumer, B2B, and developer tool products.
preflight-checks	Detect and run project linters, formatters, and type checkers before committing or claiming completion. Auto-detects tools from project config files.