Excalidraw Diagrams
Excalidraw lets you draw architecture diagrams, flowcharts, and sketches directly inside your SPECLAN specs - and they live in your repo as real files, versioned with everything else.
This guide shows you how to set it up and use it. Prefer to watch? The video below walks through the whole flow end to end.
Can't see the video? Watch on YouTube.
Why diagrams in specs
A wall of text is hard to reason about. A diagram makes structure obvious at a glance - how components talk to each other, how a flow branches, where the boundaries are.
SPECLAN treats Excalidraw diagrams as first-class artifacts. They are not screenshots pasted into a doc that rot the moment something changes. They are editable source files that sit next to your spec, travel with your repo, and render inline while you read.
What you need: the Excalidraw extension, side by side with SPECLAN
This is the one setup step, and it matters: viewing diagrams works out of the box, but creating and editing them requires a companion VS Code extension installed alongside SPECLAN.
The companion is Excalidraw by pomdtr (extension id pomdtr.excalidraw-editor), available on the VS Code Marketplace:
Excalidraw editor on the VS Code Marketplace
SPECLAN and the Excalidraw extension run side by side, each owning its own job:
- SPECLAN owns the specification and renders the diagram inline as you read.
- The Excalidraw extension owns the drawing canvas where you create and edit.
Install it once - from the Extensions view (search "Excalidraw pomdtr") or from the Marketplace page above - and SPECLAN detects it automatically. If you try to create or edit a diagram before it is installed, SPECLAN prompts you with a one-click link to install it.
Creating your first diagram
There are two easy ways in.
From the editor toolbar
While editing a spec in the SPECLAN editor, click the Excalidraw button in the toolbar. Give your diagram a name, and SPECLAN creates the file and opens the canvas.
From the artifacts section
Every spec has an Artifacts section at the bottom. Use the add control there and choose to create a new Excalidraw diagram. Same result - a new diagram, ready to draw.
Either way, SPECLAN drops a new .excalidraw.png file into the spec's artifacts/ folder and opens it in the Excalidraw canvas.
Drawing
The canvas is the full Excalidraw experience: shapes, arrows, text, freehand, libraries, the lot. Draw whatever your spec needs - a box-and-arrow architecture sketch, a sequence of steps, a state machine.
When you are done, just save. The diagram is written straight back into the .excalidraw.png file in your spec's artifacts folder.
Seeing it in your spec
Back in the SPECLAN editor, your diagram shows up inline, rendered right where it belongs. No export step, no copy-paste. The picture you see in the spec is the file on disk.
Because the file is a real PNG with the drawing baked in, it also renders anywhere a normal image does - GitHub, your docs site, a Markdown preview. But because it is also an Excalidraw file, you can reopen it any time and keep editing. One file, both jobs.
Editing later
Click an existing diagram to open it back up in the Excalidraw canvas. Make your changes, save, and the inline render in your spec updates to match.
Diagrams evolve with your spec. When the design changes, update the picture - it is right there, not buried in some external tool.
Dark mode
SPECLAN is theme-aware. A diagram you drew on a light background is automatically adjusted to sit comfortably in a dark editor theme, so it never glares at you.
If you deliberately drew a dark-themed diagram, name the file with a .dark.excalidraw.png ending and SPECLAN leaves it untouched.
Diagrams on locked specs
Once a spec is locked - in development, under test, or released - it is protected from silent changes. Diagrams follow the same rule as everything else.
If you edit a diagram on a locked spec, SPECLAN notices and offers to open a Change Request, so the update is tracked and reviewed like any other change. You get a small prompt right by the diagram - one click to raise the CR.
Where the files live
Every diagram is a .excalidraw.png file inside the artifacts/ folder next to your spec. That means:
- It is versioned with your spec in git
- It travels with your repo - no external service, no broken links
- It renders as a normal image anywhere, and stays editable in Excalidraw
Diagrams are part of your specification, not an attachment to it.
Quick reference
| Task | How |
|---|---|
| View a diagram | Just open the spec - it renders inline (no extension needed) |
| Install the editor | VS Code Marketplace, "Excalidraw" by pomdtr (pomdtr.excalidraw-editor) |
| Create a diagram | Toolbar button, or Artifacts section add control |
| Edit a diagram | Click it to open the Excalidraw canvas |
| Keep a dark diagram dark | Name it .dark.excalidraw.png |
| Change a diagram on a locked spec | Accept the Change Request prompt |
| Find the files | artifacts/ folder next to the spec |
That's it
Draw, save, see it in your spec. Your diagrams live in your repo, version with your work, and render everywhere - while staying fully editable. No external tools to wrangle, no exports to keep in sync. The only thing to install is the Excalidraw extension by pomdtr, running side by side with SPECLAN.