1# Excalidraw Library Tools
2 
3This directory contains scripts for working with Excalidraw libraries.
4 
5## split-excalidraw-library.py
6 
7Splits an Excalidraw library file (`*.excalidrawlib`) into individual icon JSON files for efficient token usage by AI assistants.
8 
9### Prerequisites
10 
11- Python 3.6 or higher
12- No additional dependencies required (uses only standard library)
13 
14### Usage
15 
16```bash
17python split-excalidraw-library.py <path-to-library-directory>
18```
19 
20### Step-by-Step Workflow
21 
221. **Create library directory**:
23   ```bash
24   mkdir -p skills/excalidraw-diagram-generator/libraries/aws-architecture-icons
25   ```
26 
272. **Download and place library file**:
28   - Visit: https://libraries.excalidraw.com/
29   - Search for "AWS Architecture Icons" and download the `.excalidrawlib` file
30   - Rename it to match the directory name: `aws-architecture-icons.excalidrawlib`
31   - Place it in the directory created in step 1
32 
333. **Run the script**:
34   ```bash
35   python skills/excalidraw-diagram-generator/scripts/split-excalidraw-library.py skills/excalidraw-diagram-generator/libraries/aws-architecture-icons/
36   ```
37 
38### Output Structure
39 
40The script creates the following structure in the library directory:
41 
42```
43skills/excalidraw-diagram-generator/libraries/aws-architecture-icons/
44  aws-architecture-icons.excalidrawlib  # Original file (kept)
45  reference.md                          # Generated: Quick reference table
46  icons/                                # Generated: Individual icon files
47    API-Gateway.json
48    CloudFront.json
49    EC2.json
50    S3.json
51    ...
52```
53 
54### What the Script Does
55 
561. **Reads** the `.excalidrawlib` file
572. **Extracts** each icon from the `libraryItems` array
583. **Sanitizes** icon names to create valid filenames (spaces → hyphens, removes special characters)
594. **Saves** each icon as a separate JSON file in the `icons/` directory
605. **Generates** a `reference.md` file with a table mapping icon names to filenames
61 
62### Benefits
63 
64- **Token Efficiency**: AI can first read the lightweight `reference.md` to find relevant icons, then load only the specific icon files needed
65- **Organization**: Icons are organized in a clear directory structure
66- **Extensibility**: Users can add multiple library sets side-by-side
67 
68### Recommended Workflow
69 
701. Download desired Excalidraw libraries from https://libraries.excalidraw.com/
712. Run this script on each library file
723. Move the generated folders to `../libraries/`
734. The AI assistant will use `reference.md` files to locate and use icons efficiently
74 
75### Library Sources (Examples — verify availability)
76 
77- Examples found on https://libraries.excalidraw.com/ may include cloud/service icon sets.
78- Availability changes over time; verify the exact library names on the site before use.
79- This script works with any valid `.excalidrawlib` file you provide.
80 
81### Troubleshooting
82 
83**Error: File not found**
84- Check that the file path is correct
85- Make sure the file has a `.excalidrawlib` extension
86 
87**Error: Invalid library file format**
88- Ensure the file is a valid Excalidraw library file
89- Check that it contains a `libraryItems` array
90 
91### License Considerations
92 
93When using third-party icon libraries:
94- **AWS Architecture Icons**: Subject to AWS Content License
95- **GCP Icons**: Subject to Google's terms
96- **Other libraries**: Check each library's license
97 
98This script is for personal/organizational use. Redistribution of split icon files should comply with the original library's license terms.
99 
100## add-icon-to-diagram.py
101 
102Adds a specific icon from a split Excalidraw library into an existing `.excalidraw` diagram. The script handles coordinate translation and ID collision avoidance, and can optionally add a label under the icon.
103 
104### Prerequisites
105 
106- Python 3.6 or higher
107- A diagram file (`.excalidraw`)
108- A split icon library directory (created by `split-excalidraw-library.py`)
109 
110### Usage
111 
112```bash
113python add-icon-to-diagram.py <diagram-path> <icon-name> <x> <y> [OPTIONS]
114```
115 
116**Options**
117- `--library-path PATH` : Path to the icon library directory (default: `aws-architecture-icons`)
118- `--label TEXT` : Add a text label below the icon
119-- `--use-edit-suffix` : Edit via `.excalidraw.edit` to avoid editor overwrite issues (enabled by default; pass `--no-use-edit-suffix` to disable)
120 
121### Examples
122 
123```bash
124# Add EC2 icon at position (400, 300)
125python add-icon-to-diagram.py diagram.excalidraw EC2 400 300
126 
127# Add VPC icon with label
128python add-icon-to-diagram.py diagram.excalidraw VPC 200 150 --label "VPC"
129 
130# Safe edit mode is enabled by default (avoids editor overwrite issues)
131# Use `--no-use-edit-suffix` to disable
132python add-icon-to-diagram.py diagram.excalidraw EC2 500 300
133 
134# Add icon from another library
135python add-icon-to-diagram.py diagram.excalidraw Compute-Engine 500 200 \
136   --library-path libraries/gcp-icons --label "API Server"
137```
138 
139### What the Script Does
140 
1411. **Loads** the icon JSON from the library’s `icons/` directory
1422. **Calculates** the icon’s bounding box
1433. **Offsets** all coordinates to the target position
1444. **Generates** unique IDs for all elements and groups
1455. **Appends** the transformed elements to the diagram
1466. **(Optional)** Adds a label beneath the icon
147 
148---
149 
150## add-arrow.py
151 
152Adds a straight arrow between two points in an existing `.excalidraw` diagram. Supports optional labels and line styles.
153 
154### Prerequisites
155 
156- Python 3.6 or higher
157- A diagram file (`.excalidraw`)
158 
159### Usage
160 
161```bash
162python add-arrow.py <diagram-path> <from-x> <from-y> <to-x> <to-y> [OPTIONS]
163```
164 
165**Options**
166- `--style {solid|dashed|dotted}` : Line style (default: `solid`)
167- `--color HEX` : Arrow color (default: `#1e1e1e`)
168- `--label TEXT` : Add a text label on the arrow
169-- `--use-edit-suffix` : Edit via `.excalidraw.edit` to avoid editor overwrite issues (enabled by default; pass `--no-use-edit-suffix` to disable)
170 
171### Examples
172 
173```bash
174# Simple arrow
175python add-arrow.py diagram.excalidraw 300 200 500 300
176 
177# Arrow with label
178python add-arrow.py diagram.excalidraw 300 200 500 300 --label "HTTPS"
179 
180# Dashed arrow with custom color
181python add-arrow.py diagram.excalidraw 400 350 600 400 --style dashed --color "#7950f2"
182 
183# Safe edit mode is enabled by default (avoids editor overwrite issues)
184# Use `--no-use-edit-suffix` to disable
185python add-arrow.py diagram.excalidraw 300 200 500 300
186```
187 
188### What the Script Does
189 
1901. **Creates** an arrow element from the given coordinates
1912. **(Optional)** Adds a label near the arrow midpoint
1923. **Appends** elements to the diagram
1934. **Saves** the updated file
194