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:

```bash
npm install -g @swiftlysingh/excalidraw-cli
```

Or use via npx (no installation needed):

```bash
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 |
| `![path](WxH)` | 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:

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

Or for multi-line DSL, use a heredoc:

```bash
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:

```bash
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

```dot
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

```bash
# 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