visualizing-with-mermaid
$
npx mdskill add rileyhilliard/claude-essentials/visualizing-with-mermaidGenerate 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
- architecting-systemsGuides 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-claudeBest 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-testsDiagnose 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-errorsPrevents 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-databasesGuides 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-pipelinesGuides 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-codeSafe code migrations with backward compatibility and reversibility. Use when upgrading dependencies, changing database schemas, API versioning, or transitioning between technologies.
- optimizing-performanceMeasure-first performance optimization that balances gains against complexity. Use when addressing slow code, profiling issues, or evaluating optimization trade-offs.
- planning-productsDefines 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-checksDetect and run project linters, formatters, and type checkers before committing or claiming completion. Auto-detects tools from project config files.