diagramming
Technical diagram creation with visual design principles: format selection, layout, readability, and aesthetics. Invoke whenever task involves any interaction with diagrams — creating, reviewing, or improving visual representations of systems, processes, data flows, or relationsh
Install
npx skills add https://github.com/xobotyi/cc-foundry/tree/master/plugins/the-blueprint/skills/diagramming
claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install xobotyi-cc-foundry@llmmart
git clone https://github.com/xobotyi/cc-foundry.git
The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole xobotyi/cc-foundry collection as a plugin from our marketplace. Git is the plain clone.
Skill manifest
Diagramming
Understandable first, beautiful second. Every diagram exists to communicate — if it fails to communicate, aesthetics are irrelevant. When both are achievable, pursue both.
References
- Visual design principles — [
${CLAUDE_SKILL_DIR}/references/design-principles.md] Gestalt principles, grid system, spacing rules, color palette, typography, complexity budgets, anti-patterns, Tufte's data-ink principle - Excalidraw format — [
${CLAUDE_SKILL_DIR}/references/excalidraw.md] JSON schema, element types, styling properties, arrow binding, layout templates (linear, grid, radial, tiered, decision tree), diagram type conventions - Mermaid syntax — [
${CLAUDE_SKILL_DIR}/references/mermaid.md] Flowchart, sequence, class, state, ER diagram syntax, theming, per-node styling, subgraphs
Format Selection
Choose the format that matches the delivery context:
Core Design Rules
These rules apply to every diagram regardless of format. They are non-negotiable.
- Consistent shapes — same concept type uses the same shape everywhere in the diagram. All services are rectangles. All databases are cylinders. All decisions are diamonds. Never vary shapes for the same concept.
- Consistent flow direction — pick one direction (top-to-bottom or left-to-right) and maintain it for all relationships of the same type within the diagram.
- Semantic color — color encodes meaning (tier, status, domain), never decoration. Maximum 2–3 accent colors per diagram. Use the semantic palette from the design-principles reference.
- Label everything that isn't obvious — every arrow in a complex diagram gets a label. Every color gets a legend entry. If a reader has to guess what something means, the diagram has failed.
- Whitespace is structure — group related elements tightly, separate groups with 2x the intra-group gap. When in doubt, add more space.
- Complexity budget — if a diagram exceeds 20 elements, split it. Create a high-level overview + detail diagrams. No exceptions.
Spatial Reasoning Strategy
LLMs cannot reliably reason about spatial coordinates from scratch. Compensate with these strategies:
Diagram Type Guidance
Flowcharts / Process Diagrams
- Start and end with terminal shapes (ellipse in Excalidraw,
([text])in Mermaid) - Decisions get diamond shapes with labeled outgoing edges ("Yes"/"No")
- Keep to a single flow direction — avoid loops that create visual spaghetti
- 3–10 steps is the sweet spot; 15 is the hard maximum per diagram
Architecture / System Diagrams
- Group related services using frames (Excalidraw) or subgraphs (Mermaid)
- Use color to distinguish tiers: frontend (blue), backend (yellow), data (green), external (purple)
- Label connections with protocols and data formats (HTTP, gRPC, SQL, JSON)
- Include a legend when using 3+ colors or shape conventions
- Show system boundaries explicitly — what's inside vs. outside the system
Sequence Diagrams
- Participants ordered left-to-right by first interaction
- Name participants with short aliases; use full names in the participant declaration
- Number messages when order matters
- Use activation boxes to show processing duration
- Keep to 3–6 participants and 10–15 messages per diagram
Entity Relationship Diagrams
- Include primary keys (PK) and foreign keys (FK) in entity definitions
- Label relationships with both the verb and cardinality
- Use grid layout — entities at regular intervals, relationships as straight-line connections
- Group related entities spatially (user-domain entities together, product-domain together)
Mind Maps
- Central topic at the center, main branches radiating outward
- 4–6 main branches maximum
- Use radial layout template (Excalidraw) — even angular distribution
- Color-code branches by theme
- Sub-topics attach to their branch, not to the center
Excalidraw Defaults
When generating Excalidraw JSON, use these defaults unless the context demands otherwise:
roughness: 0— clean lines for professional outputfillStyle: "solid"— solid fills, not hachurestrokeWidth: 2— normal weightfontFamily: 5— Excalifont (current Excalidraw default)fontSize: 20— box labels; 28 for titles; 16 for descriptionsroundness: { "type": 3 }— rounded rectangle corners- Background:
#ffffff
Output Conventions
After generating a diagram:
- Save with a descriptive filename —
user-auth-flow.excalidrawor include Mermaid inline in the document - State what the diagram shows — one sentence summarizing scope and element count
- Provide viewing instructions for Excalidraw files:
- Drag-and-drop at excalidraw.com
- Open with VS Code Excalidraw extension
- Open with Obsidian Excalidraw plugin
- Offer to split if the diagram is complex — "This has 18 elements. Want me to split into overview + detail?"
Worked Example
Integration with Blueprint Skills
Diagrams are a design-phase artifact. They compose naturally with the blueprint pipeline:
- During
alignment— create diagrams to illustrate the problem space, compare solution options visually - During
frame— create architecture diagrams showing component relationships, data flow, deployment topology - Standalone — create diagrams on request outside the pipeline context
Quality Gate
Before delivering any diagram, verify:
- All elements have unique IDs (Excalidraw)
- No elements overlap — coordinates verified against element sizes
- Text is readable — minimum 14px, labels fit within their containers
- Colors follow semantic palette — no decorative rainbow
- Arrows are labeled when the relationship isn't obvious
- Flow direction is consistent throughout
- Element count is within budget (≤20, or split proposed)
- Legend present if using color/shape coding with 3+ categories
Files (cc-foundry)
-
.dev
-
reference-inventory.json 1.2 KB
Loading…
-
-
references
-
design-principles.md 7.8 KB
Loading… -
excalidraw.md 19.2 KB
Loading… -
mermaid.md 19.6 KB
Loading…
-
-
SKILL.md 9.6 KB
--- name: diagramming description: >- Technical diagram creation with visual design principles: format selection, layout, readability, and aesthetics. Invoke whenever task involves any interaction with diagrams — creating, reviewing, or improving visual representations of systems, processes, data flows, or relationships using Excalidraw or Mermaid. --- # Diagramming Understandable first, beautiful second. Every diagram exists to communicate — if it fails to communicate, aesthetics are irrelevant. When both are achievable, pursue both. ## References - **Visual design principles** — [`${CLAUDE_SKILL_DIR}/references/design-principles.md`] Gestalt principles, grid system, spacing rules, color palette, typography, complexity budgets, anti-patterns, Tufte's data-ink principle - **Excalidraw format** — [`${CLAUDE_SKILL_DIR}/references/excalidraw.md`] JSON schema, element types, styling properties, arrow binding, layout templates (linear, grid, radial, tiered, decision tree), diagram type conventions - **Mermaid syntax** — [`${CLAUDE_SKILL_DIR}/references/mermaid.md`] Flowchart, sequence, class, state, ER diagram syntax, theming, per-node styling, subgraphs ## Format Selection Choose the format that matches the delivery context: <format-decision> **Use Mermaid when:** - The diagram lives in markdown (README, design doc, PR description, wiki) - Auto-layout is acceptable — precise element positioning is not required - The diagram type maps to a Mermaid-supported type - Version-control readability matters (text diffs) - Quick iteration speed matters more than visual refinement **Use Excalidraw when:** - Precise spatial layout is needed (architecture diagrams with specific grouping) - The diagram needs freeform elements that don't fit a standard type - Visual polish matters — color coding, consistent spacing, professional appearance - The diagram will be used in presentations, external documentation, or design reviews - The diagram needs to be manually editable after generation </format-decision> ## Core Design Rules These rules apply to every diagram regardless of format. They are non-negotiable. - **Consistent shapes** — same concept type uses the same shape everywhere in the diagram. All services are rectangles. All databases are cylinders. All decisions are diamonds. Never vary shapes for the same concept. - **Consistent flow direction** — pick one direction (top-to-bottom or left-to-right) and maintain it for all relationships of the same type within the diagram. - **Semantic color** — color encodes meaning (tier, status, domain), never decoration. Maximum 2–3 accent colors per diagram. Use the semantic palette from the design-principles reference. - **Label everything that isn't obvious** — every arrow in a complex diagram gets a label. Every color gets a legend entry. If a reader has to guess what something means, the diagram has failed. - **Whitespace is structure** — group related elements tightly, separate groups with 2x the intra-group gap. When in doubt, add more space. - **Complexity budget** — if a diagram exceeds 20 elements, split it. Create a high-level overview + detail diagrams. No exceptions. ## Spatial Reasoning Strategy LLMs cannot reliably reason about spatial coordinates from scratch. Compensate with these strategies: <spatial-strategy> **For Excalidraw:** 1. **Start from a layout template.** Never invent coordinates from scratch. Pick the template that matches the diagram's topology (linear flow, grid, hub-and-spoke, tiered architecture, decision tree) from the Excalidraw reference. 2. **Use the grid.** All coordinates should be multiples of 50. Standard horizontal gap: 250px between elements. Standard vertical gap: 150px between rows. 3. **Calculate before placing.** Count elements first, determine grid dimensions, then assign coordinates systematically. Do not place elements one at a time hoping they'll line up. 4. **Work outward from anchor points.** Place the most important element first (center or top-left), then position everything else relative to it using consistent offsets. 5. **Verify mentally.** After computing all coordinates, check: do any elements overlap? Is the spacing consistent? Are arrows routing cleanly (no diagonal spaghetti)? **For Mermaid:** 1. **Let the engine handle layout.** Do not fight the auto-layout — work with it. 2. **Use subgraphs for grouping.** The engine treats subgraph contents as a unit, producing cleaner layouts. 3. **Keep labels short.** Long labels break auto-layout. Use aliases for participants/nodes when labels exceed 3 words. 4. **Choose the right direction.** `LR` for processes, `TD` for hierarchies. Match direction to the conceptual flow. 5. **Never use lowercase `end` as a node ID** — it terminates blocks. See Mermaid reference for the full pitfall list. </spatial-strategy> ## Diagram Type Guidance ### Flowcharts / Process Diagrams - Start and end with terminal shapes (ellipse in Excalidraw, `([text])` in Mermaid) - Decisions get diamond shapes with labeled outgoing edges ("Yes"/"No") - Keep to a single flow direction — avoid loops that create visual spaghetti - 3–10 steps is the sweet spot; 15 is the hard maximum per diagram ### Architecture / System Diagrams - Group related services using frames (Excalidraw) or subgraphs (Mermaid) - Use color to distinguish tiers: frontend (blue), backend (yellow), data (green), external (purple) - Label connections with protocols and data formats (HTTP, gRPC, SQL, JSON) - Include a legend when using 3+ colors or shape conventions - Show system boundaries explicitly — what's inside vs. outside the system ### Sequence Diagrams - Participants ordered left-to-right by first interaction - Name participants with short aliases; use full names in the participant declaration - Number messages when order matters - Use activation boxes to show processing duration - Keep to 3–6 participants and 10–15 messages per diagram ### Entity Relationship Diagrams - Include primary keys (PK) and foreign keys (FK) in entity definitions - Label relationships with both the verb and cardinality - Use grid layout — entities at regular intervals, relationships as straight-line connections - Group related entities spatially (user-domain entities together, product-domain together) ### Mind Maps - Central topic at the center, main branches radiating outward - 4–6 main branches maximum - Use radial layout template (Excalidraw) — even angular distribution - Color-code branches by theme - Sub-topics attach to their branch, not to the center ## Excalidraw Defaults When generating Excalidraw JSON, use these defaults unless the context demands otherwise: - `roughness: 0` — clean lines for professional output - `fillStyle: "solid"` — solid fills, not hachure - `strokeWidth: 2` — normal weight - `fontFamily: 5` — Excalifont (current Excalidraw default) - `fontSize: 20` — box labels; 28 for titles; 16 for descriptions - `roundness: { "type": 3 }` — rounded rectangle corners - Background: `#ffffff` ## Output Conventions After generating a diagram: 1. **Save with a descriptive filename** — `user-auth-flow.excalidraw` or include Mermaid inline in the document 2. **State what the diagram shows** — one sentence summarizing scope and element count 3. **Provide viewing instructions** for Excalidraw files: - Drag-and-drop at excalidraw.com - Open with VS Code Excalidraw extension - Open with Obsidian Excalidraw plugin 4. **Offer to split** if the diagram is complex — "This has 18 elements. Want me to split into overview + detail?" ## Worked Example <examples> **Request:** "Create a diagram showing the user authentication flow" **Format decision:** This is a process flow for a design doc → Mermaid (markdown-embedded, auto-layout sufficient). **Output:** ```mermaid %%{init: {'theme': 'neutral'}}%% flowchart TD A([Start]) --> B[Enter Credentials] B --> C{Valid?} C -->|Yes| D[Generate JWT] C -->|No| E[Show Error] E --> B D --> F[Redirect to Dashboard] F --> G([End]) ``` Created: authentication flow diagram (7 nodes, 7 edges). Embedded inline in the design document. --- **Request:** "Create an architecture diagram of our API gateway setup" **Format decision:** Architecture diagram needing spatial grouping and color-coded tiers → Excalidraw. **Agent approach:** 1. Count components: API Gateway, Auth Service, User Service, Product Service, PostgreSQL, Redis — 6 elements 2. Select template: Tiered Architecture (3 tiers: gateway, services, data) 3. Assign coordinates from template, semantic colors per tier 4. Generate `.excalidraw` JSON with bound arrows and labels 5. Save as `api-gateway-architecture.excalidraw` </examples> ## Integration with Blueprint Skills Diagrams are a design-phase artifact. They compose naturally with the blueprint pipeline: - During `alignment` — create diagrams to illustrate the problem space, compare solution options visually - During `frame` — create architecture diagrams showing component relationships, data flow, deployment topology - Standalone — create diagrams on request outside the pipeline context ## Quality Gate Before delivering any diagram, verify: - [ ] All elements have unique IDs (Excalidraw) - [ ] No elements overlap — coordinates verified against element sizes - [ ] Text is readable — minimum 14px, labels fit within their containers - [ ] Colors follow semantic palette — no decorative rainbow - [ ] Arrows are labeled when the relationship isn't obvious - [ ] Flow direction is consistent throughout - [ ] Element count is within budget (≤20, or split proposed) - [ ] Legend present if using color/shape coding with 3+ categories
Comments (0)
Sign in to join the conversation.
Reviews (0)
No reviews yet.
No comments yet.