Claude Skill

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

LLM Mart · 0 points · 0 views 0 listing impressions 0 install-command copies
Download xobotyi-cc-foundry-plugins_the-blueprint_skills_diagramming-278c16c.zip · 24 KB

Install

skills CLI npx skills add https://github.com/xobotyi/cc-foundry/tree/master/plugins/the-blueprint/skills/diagramming
Claude Code claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install xobotyi-cc-foundry@llmmart
Git 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 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

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.

No comments yet.

Reviews (0)

No reviews yet.