excalidraw-flowchart

Excalidraw Flowchart Skill

Create professional flowcharts and diagrams as Excalidraw files that can be opened in Excalidraw.

When to Use This Skill

• User asks to create a flowchart or diagram
• User wants to visualize a process or workflow
• User needs an architecture diagram
• User mentions "excalidraw" or "flow diagram"
• User wants to document decision trees

Prerequisites

The @swiftlysingh/excalidraw-cli tool must be installed:

npm install -g @swiftlysingh/excalidraw-cli

Or use via npx (no installation needed):

npx @swiftlysingh/excalidraw-cli create --inline "DSL" -o output.excalidraw

How to Create a Flowchart

Step 1: Analyze the Request

Identify from the user's description:

• What are the main steps/nodes?
• What are the decision points?
• What is the flow direction?
• Are there any loops or branches?

Step 2: Write the DSL

Use this DSL syntax to describe the flowchart:

Syntax	Element	Use For
[Label]	Rectangle	Process steps, actions
{Label?}	Diamond	Decisions, conditionals
(Label)	Ellipse	Start/End points
[[Label]]	Database	Data storage
![path]	Image	Inline images
	Sized Image	Images with explicit dimensions
->	Arrow	Connections
-> "text" ->	Labeled Arrow	Connections with labels
-->	Dashed Arrow	Optional/alternative paths

DSL Directives

Directive	Description	Example
@direction	Set flow direction	@direction LR
@spacing	Set node spacing	@spacing 60
@image	Position image	@image logo.png at 100,50
@decorate	Attach decoration to node	@decorate icon.png top-right
@sticker	Add sticker from library	@sticker checkmark at 200,100
@library	Set sticker library path	@library ./assets/stickers
@scatter	Scatter images on canvas	@scatter star.png count:5

Step 3: Generate the File

Run the CLI to create the .excalidraw file:

npx @swiftlysingh/excalidraw-cli create --inline "YOUR_DSL_HERE" -o flowchart.excalidraw

Or for multi-line DSL, use a heredoc:

npx @swiftlysingh/excalidraw-cli create --inline "$(cat <<'EOF'
(Start) -> [Step 1] -> {Decision?}
{Decision?} -> "yes" -> [Step 2] -> (End)
{Decision?} -> "no" -> [Step 3] -> [Step 1]
EOF
)" -o flowchart.excalidraw

Step 4: Inform the User

Tell the user:

1. The file was created at the specified path
2. They can open it in Excalidraw (https://excalidraw.com) via File > Open
3. They can edit it further in Excalidraw if needed

DSL Examples

Simple Linear Flow

(Start) -> [Initialize] -> [Process Data] -> [Save Results] -> (End)

Decision Tree

(Start) -> [Receive Request] -> {Authenticated?}
{Authenticated?} -> "yes" -> [Process Request] -> (Success)
{Authenticated?} -> "no" -> [Return 401] -> (End)

Loop/Retry Pattern

(Start) -> [Attempt Operation] -> {Success?}
{Success?} -> "yes" -> [Continue] -> (End)
{Success?} -> "no" -> {Retry Count < 3?}
{Retry Count < 3?} -> "yes" -> [Increment Counter] -> [Attempt Operation]
{Retry Count < 3?} -> "no" -> [Log Failure] -> (Error)

Multi-Branch Flow

(User Input) -> {Input Type?}
{Input Type?} -> "text" -> [Parse Text] -> [Process]
{Input Type?} -> "file" -> [Read File] -> [Process]
{Input Type?} -> "url" -> [Fetch URL] -> [Process]
[Process] -> [Output Result] -> (Done)

With Database

[API Request] -> {Cache Hit?}
{Cache Hit?} -> "yes" -> [[Read Cache]] -> [Return Data]
{Cache Hit?} -> "no" -> [[Query Database]] -> [[Update Cache]] -> [Return Data]

CLI Options

• -o, --output <file> - Output file path (default: flowchart.excalidraw)
• -f, --format <type> - Input format: dsl, json, dot (default: auto-detected)
• -d, --direction <TB|BT|LR|RL> - Flow direction (default: TB = top to bottom)
• -s, --spacing <number> - Node spacing in pixels (default: 50)
• --inline <dsl> - Inline DSL/DOT string
• --stdin - Read input from stdin
• --verbose - Verbose output

Example with options:

npx @swiftlysingh/excalidraw-cli create --inline "[A] -> [B] -> [C]" --direction LR --spacing 80 -o horizontal-flow.excalidraw

DOT/Graphviz Format (New in v1.1.0)

The CLI now supports DOT/Graphviz format for creating diagrams. This is useful when working with existing DOT files or when you prefer the DOT syntax.

DOT Syntax

digraph {
    rankdir=LR

    start [shape=ellipse label="Start"]
    process [shape=box label="Process Data"]
    decision [shape=diamond label="Valid?"]
    end [shape=ellipse label="End"]

    start -> process
    process -> decision
    decision -> end [label="yes"]
    decision -> process [label="no" style=dashed]
}

Supported DOT Features

Feature	DOT Syntax	Maps To
Rectangle	shape=box or shape=rect	[Label]
Diamond	shape=diamond	{Label}
Ellipse	shape=ellipse or shape=circle	(Label)
Database	shape=cylinder	[[Label]]
Direction	rankdir=TB|BT|LR|RL	@direction
Edge labels	[label="text"]	-> "text" ->
Dashed edges	[style=dashed]	-->
Colors	[fillcolor="..." color="..."]	Node styling

Using DOT Files

# From file (auto-detected by .dot or .gv extension)
npx @swiftlysingh/excalidraw-cli create diagram.dot -o output.excalidraw

# Inline DOT
npx @swiftlysingh/excalidraw-cli create --format dot --inline "digraph { A -> B -> C }" -o output.excalidraw

Images and Decorations (New in v1.1.0)

Image Nodes

Include images as flow elements:

(Start) -> ![logo.png](100x50) -> [Process] -> (End)

Positioned Images

Place images at specific positions:

@image background.png at 0,0
@image logo.png near (Start) top-right

(Start) -> [Process] -> (End)

Node Decorations

Attach small icons/badges to nodes:

[Deploy to Production]
@decorate checkmark.png top-right

[Review Required]
@decorate warning.png top-left

Decoration anchors: top, bottom, left, right, top-left, top-right, bottom-left, bottom-right

Sticker Library

Use a library of reusable stickers:

@library ./assets/stickers
@sticker success at 100,100
@sticker warning near (Error) top-right

Scatter Images

Distribute images randomly across the canvas:

@scatter confetti.png count:10
@scatter star.png count:5 width:20 height:20

Common Patterns

API Request Flow

[Client Request] -> [API Gateway] -> {Auth Valid?}
{Auth Valid?} -> "yes" -> [Route to Service] -> [[Database]] -> [Response]
{Auth Valid?} -> "no" -> [401 Unauthorized]

CI/CD Pipeline

(Push) -> [Build] -> [Test] -> {Tests Pass?}
{Tests Pass?} -> "yes" -> [Deploy Staging] -> {Manual Approval?}
{Manual Approval?} -> "yes" -> [Deploy Production] -> (Done)
{Manual Approval?} -> "no" -> (Cancelled)
{Tests Pass?} -> "no" -> [Notify Team] -> (Failed)

User Registration

(Start) -> [Enter Details] -> {Email Valid?}
{Email Valid?} -> "no" -> [Show Error] -> [Enter Details]
{Email Valid?} -> "yes" -> {Password Strong?}
{Password Strong?} -> "no" -> [Show Password Requirements] -> [Enter Details]
{Password Strong?} -> "yes" -> [[Save to Database]] -> [Send Verification Email] -> (Success)

Tips

1. Keep labels concise - Use short, action-oriented text
2. End decisions with ? - Makes it clear it's a conditional
3. Use consistent naming - Helps with node deduplication
4. Start with (Start) - Makes the entry point clear
5. Test complex flows - Break into smaller parts if needed