Excalidraw Diagram Generator

Overview

This skill enables you to generate complete, valid .excalidraw files that users can directly open at excalidraw.com. You act as a professional diagram generation expert, creating beautiful, well-structured diagrams from user descriptions with automatic layout calculation and saving them as ready-to-use files.

Supports two visual styles:

• •专业模式 (Professional Mode): Clean, polished diagrams for technical documentation (default)
• •手绘模式 (Hand-drawn Mode): Sketch-style diagrams for brainstorming and informal use

Core Capabilities

You can generate these diagram types:

1. •Flowcharts - Process flows, decision trees, workflows
2. •Architecture Diagrams - System architectures, network topologies, component diagrams
3. •UML Diagrams - Class diagrams, sequence diagrams, use case diagrams
4. •Mind Maps - Hierarchical concept maps, brainstorming diagrams

Quick Start

When a user requests a diagram:

1. •Understand the request - Identify the diagram type and key content
2. •Choose style - Use 专业模式 (Professional Mode) by default; switch to hand-drawn mode only if user requests it
3. •Choose a template - Start from the relevant template in assets/
4. •Modify elements - Adjust text, positions, colors based on requirements
5. •Calculate layout - Use spacing guidelines from references/excalidraw-format.md
6. •Save to file - Write the complete JSON to a .excalidraw file

Workflow

Step 1: Identify Diagram Type

Match the user's request to a diagram type:

• •Flowchart: Process flows, algorithms, decision trees, workflows
• •Architecture: System designs, microservices, cloud infrastructure, databases
• •UML Class: Object-oriented design, class hierarchies, relationships
• •Mind Map: Brainstorming, concept hierarchies, topic exploration

Step 2: Use Templates as Foundation

Templates are located in assets/ directory:

• •flowchart-template.json - Start → Process → Decision flow
• •architecture-template.json - Frontend → Backend → Database architecture
• •uml-class-template.json - Class with attributes and methods
• •mindmap-template.json - Central topic with three branches

Template usage:

1. •Read the appropriate template file
2. •Modify element IDs, text, positions, and colors
3. •Add or remove elements as needed
4. •Ensure all IDs are unique

Step 3: Generate Elements

For detailed element specifications, consult references/excalidraw-format.md.

Key element types:

• •rectangle - Boxes, containers, processes
• •ellipse - Start/end nodes, databases, emphasis
• •diamond - Decisions, conditional branches
• •arrow / line - Connections, flows, relationships
• •text - Labels, descriptions

Essential properties all elements need:

{
  "id": "unique-id",
  "type": "rectangle|ellipse|diamond|arrow|text",
  "x": 100,
  "y": 100,
  "width": 150,
  "height": 80,
  "strokeColor": "#1e1e1e",
  "backgroundColor": "#a5d8ff",
  "fillStyle": "solid",
  "strokeWidth": 2,
  "strokeStyle": "solid",
  "roughness": 1,
  "opacity": 100,
  "angle": 0,
  "groupIds": [],
  "frameId": null,
  "roundness": { "type": 3 },
  "boundElements": [],
  "updated": 1705276800000,
  "link": null,
  "locked": false,
  "versionNonce": 123456789,
  "isDeleted": false,
  "seed": 987654321
}

Step 4: Calculate Layout Automatically

Spacing guidelines:

• •Minimum spacing between elements: 80-100px
• •Vertical flow gap (parent → child): 120px
• •Horizontal spacing (siblings): 150px
• •Arrow padding from element edge: 10-20px

Standard sizes:

• •Small boxes: 120×60
• •Medium boxes: 150×80
• •Large boxes: 200×100

Text height calculation (CRITICAL):

textHeight = fontSize × lineHeight × numberOfLines
           = fontSize × 1.25 × numberOfLines

Example:
- 1 line, fontSize 20: height = 20 × 1.25 × 1 = 25px
- 3 lines, fontSize 14: height = 14 × 1.25 × 3 = 52.5px ≈ 53px
- 12 lines, fontSize 15: height = 15 × 1.25 × 12 = 225px

UML Class Diagram container height calculation:

containerHeight = headerHeight + dividerHeight + attributesHeight + dividerHeight + methodsHeight + padding

Where:
- headerHeight = classNameTextHeight + topPadding (typically 15px + 15px = 30px)
- dividerHeight = 0 (line element, but reserve ~10px visual space after)
- attributesHeight = fontSize × 1.25 × numberOfAttributes + 10px (bottom padding)
- methodsHeight = fontSize × 1.25 × numberOfMethods + 10px (bottom padding)
- topPadding: 15px above class name
- bottomPadding: 10px below each section

Example for a class with 12 attributes and 10 methods (fontSize 15):
- headerHeight: 20 + 15 = 35px
- attributesHeight: 15 × 1.25 × 12 + 10 = 225 + 10 = 235px
- methodsHeight: 15 × 1.25 × 10 + 10 = 187.5 + 10 ≈ 198px
- Total: 35 + 10 + 235 + 10 + 198 = 488px (round to 500px for safety)

Layout strategies:

• •Flowcharts: Top-to-bottom, centered alignment
• •Architecture: Left-to-right for flow, grouped by layer
• •UML Class: Use calculation formula above; ensure text doesn't overflow container
• •Mind Maps: Radial from center, balanced branches

Step 5: Style and Polish

Choose a diagram style based on context:

专业模式 (Professional Mode) - 推荐用于技术文档

适用场景： 架构图、UML 图、技术文档、正式演示

样式参数：

• •roughness: 0 - 完全平滑，无手绘效果
• •fillStyle: "solid" - 纯色填充，文字更易读
• •strokeWidth: 2 - 标准线宽
• •fontFamily: 2 - 正常字体（非手绘）
• •颜色使用淡色背景 以提高可读性：
  • •Primary: #e7f5ff (浅蓝)
  • •Success: #ebfbee (浅绿)
  • •Warning: #fff9db (浅黄)
  • •Accent: #f3f0ff (浅紫)
  • •Secondary: #fff4e6 (浅橙)

何时使用： 默认模式，除非用户明确要求手绘风格

手绘模式 (Hand-drawn Mode)

适用场景： 创意头脑风暴、快速草图、非正式分享

样式参数：

• •roughness: 1 - 手绘风格效果
• •fillStyle: "hachure" - 斜线纹理填充
• •strokeWidth: 2 - 标准线宽
• •fontFamily: 1 - 手绘字体
• •颜色使用中等饱和度：
  • •Primary: #a5d8ff (蓝)
  • •Success: #b2f2bb (绿)
  • •Warning: #ffec99 (黄)
  • •Error: #ffc9c9 (红)
  • •Accent: #d0bfff (紫)
  • •Secondary: #ffd8a8 (橙)

何时使用： 用户明确要求"手绘风格"、"sketch"、"casual" 时

通用样式建议：

• •Stroke color: #1e1e1e (深灰，比纯黑柔和)
• •箭头标签使用对比色，确保可读性
• •保持组件间距一致（80-100px）

Step 6: Save to File

Always save the diagram directly as a .excalidraw file instead of showing JSON in a code block.

1. •Use the Write tool to save the complete JSON to a file
2. •Name the file descriptively (e.g., user-login-flow.excalidraw, system-architecture.excalidraw)
3. •Save to the current working directory unless user specifies otherwise

After saving the file, provide:

1. •Confirmation message with the file path
2. •Brief description of the diagram structure
3. •Instructions: "Open the file at excalidraw.com using 'Open' → 'Open from your computer', or drag and drop the file into the browser"
4. •Any customization suggestions

Common Patterns

Pattern 1: Sequential Flow

For processes with steps A → B → C:

1. •Place elements vertically with 120px gaps
2. •Use rectangles for processes, ellipses for start/end
3. •Connect with arrows (type: "arrow", endArrowhead: "arrow")
4. •Center-align all elements

Pattern 2: Decision Tree

For conditional branches:

1. •Use diamond for decision nodes
2. •Branch arrows left/right or up/down
3. •Add text labels on arrows ("Yes", "No", "Success", "Fail")
4. •Rejoin paths when appropriate

Pattern 3: Hierarchical Structure

For layered architectures:

1. •Group elements by layer (horizontal rows)
2. •Use different colors per layer
3. •Vertical arrows show dependencies
4. •Maintain consistent element sizes within layers

Pattern 4: Radial Mind Map

For concept exploration:

1. •Central node (ellipse) in the middle
2. •Branch lines (type: "line") radiate outward
3. •Use different colors for each main branch
4. •Rectangles for sub-topics

Tips for Quality Diagrams

1. •Unique IDs: Generate random 8-16 character IDs for each element
2. •Consistent spacing: Follow the spacing guidelines strictly
3. •Color harmony: Use the recommended color palette
4. •Text sizing: Match text width to container width with padding
5. •Arrow connections: Position arrow start/end points precisely
6. •Version numbers: Use random integers for versionNonce and seed

Handling Complex Requests

For large or complex diagrams:

1. •Start simple: Create core structure first
2. •Iterate: Add details progressively
3. •Group logically: Use visual grouping (colors, spacing)
4. •Limit complexity: Suggest breaking into multiple diagrams if needed
5. •Maintain readability: Ensure text doesn't overlap, adequate spacing

Reference Material

• •Complete format specification: See references/excalidraw-format.md
  • •Full element property reference
  • •All element types and their specific properties
  • •Color palette recommendations
  • •Detailed layout guidelines

Resources

assets/

Contains starter templates for common diagram types:

• •flowchart-template.json - Basic flowchart structure
• •architecture-template.json - System architecture pattern
• •uml-class-template.json - UML class diagram format
• •mindmap-template.json - Mind map layout

references/

• •excalidraw-format.md - Complete Excalidraw JSON format specification, element types, properties, and examples