aeon-excalidraw-diagram

An Aeon skill that turns a structured drawfile into a beautiful, portable .excalidraw v2 scene. Strict two-color design system, machine-validated before commit. Renderable in any React app, exportable to SVG/PNG, no live canvas server required.

Install into your Aeon fork

./add-skill aeonbook/aeon-excalidraw-diagram --all

That copies skills/excalidraw-diagram/ into your fork, records provenance in skills.lock, and registers a disabled entry in aeon.yml. Enable it from the Aeon dashboard (or set enabled: true in aeon.yml) and dispatch with a drawfile slug.

First-time installs run the skill-security-scan against this repo. Either pass --force once, or open a PR to aaronjmars/aeon adding aeonbook/aeon-excalidraw-diagram to skills/security/trusted-sources.txt.

# Browse available skills in this repo
./add-skill aeonbook/aeon-excalidraw-diagram --list

What it produces

The skill writes three artifacts per run, all committed to your Aeon fork:

It also appends to memory/logs/<date>.md and notifies via ./notify.

How operators use it

1. Bootstrap a drawfile

./skills/excalidraw-diagram/scaffold-drawfile payment-arch
# → creates drawfiles/payment-arch.drawfile with templated sections

2. Edit the drawfile

---
slug: payment-arch
diagram_type: A1
palette: modernTeal
canvas: 1400x1000
audience: engineering review
constraints:
  max_elements: 30
  max_title_chars: 40
  max_distinct_fontsizes: 5
  min_whitespace_margin: 80
  required_focal: "Payment"
sources:
  - memory/topics/payment-arch.md
---

# Subject
The payment service architecture for v4 launch.

# What to show
- 3 lanes: API Gateway, Payment, Billing
- Payment is the focal point — it owns the transaction
- Billing handles async invoicing

# Context
[2-3 paragraphs the agent needs to draw this correctly]

# Emphasis
The Payment Service block, dead center, in solid accent.

3. Dispatch

gh workflow run aeon.yml \
  -f skill=excalidraw-diagram \
  -f var=payment-arch

4. Render the output

Drag the .excalidraw file onto excalidraw.com — it imports natively. Or use one of the embeddable rendering paths in FRONTEND-RENDERING-SPEC.md:

The design system at a glance

• Two-color rule: black #1e1e1e for ALL strokes/text + ONE accent + neutrals. Six valid hexes per diagram, never more.
• 6 palettes: Modern Teal (default), Tech Sky, Creative Violet, Growth Emerald, Energetic Amber, Elegant Rose.
• 60-30-10: 60% whitespace + neutrals, 30% accent surface area, 10% black.
• Uniform polish: roughness: 1 hand-drawn, roundness: { type: 3 } soft corners, strokeWidth: 2 standard.
• Grid alignment: shape coordinates snap to multiples of 40 (or 60 on larger canvases). Pattern helpers throw on non-snapped inputs.
• Black-and-white test: hierarchy from size + position first, color second.

Full ruleset in skills/excalidraw-diagram/references/design-system.md.

What's different from "AI draws a diagram"

Most agents write JSON freehand and self-confirm. This skill machine-enforces every rule:

• Helpers throw on non-grid-snapped coordinates — the script fails loud before the file is written.
• Validator runs as a Bash invocation in Step 4, not a markdown checklist. The agent must read structured violations and patch specific elements until exit 0.
• One retry pass. If validation fails twice, the skill aborts with EXCALIDRAW_VALIDATION_FAILED, persists the failed scene + generate script to memory/excalidraw-failures/<date>-<slug>/, and notifies. No silent-broken output.
• Drawfile constraints are contracts. max_elements, max_title_chars, required_focal, etc. are hard fails. The skill won't relax them mid-run.
• The generate script is committed. Re-running it with the same drawfile produces the same scene. The script is the source of truth; the .excalidraw is the artifact.

Repository layout

.
├── FRONTEND-RENDERING-SPEC.md               Handoff doc for frontend renderers
├── LICENSE                                   MIT
├── CHANGELOG.md
├── skills.json                               Machine-readable manifest
├── .github/workflows/validate.yml            CI: regenerate exemplar + run validator on every push
└── skills/
    └── excalidraw-diagram/
        ├── SKILL.md                          The Aeon skill spec
        ├── scaffold-drawfile                 CLI: drops drawfiles/<slug>.drawfile template
        ├── scripts/
        │   └── validate.mjs                  Machine validator
        ├── examples/
        │   ├── aeon-self-heal.drawfile       Reference drawfile
        │   ├── aeon-self-heal.generate.mjs   Reference generate script (READ BEFORE WRITING YOUR OWN)
        │   └── aeon-self-heal.excalidraw     Known-good output paired with the script above
        └── references/
            ├── design-system.md              Hardcoded design rules (read every run)
            ├── drawfile-spec.md              Drawfile format + structured constraints schema
            ├── schema.md                     Excalidraw element JSON schema
            ├── catalog.md                    31 diagram types + element-cost ranges
            ├── patterns.md                   11 composable patterns with element costs
            └── render-helpers.mjs            Pure JS: 6 palettes + helpers + validateDesignSystem

Inline invocation (other skills calling this one)

Any Aeon skill that wants to embed a diagram can inline-invoke this one. The caller writes a brief to .outputs/excalidraw-brief.md (drawfile format) and reads back paths from .outputs/excalidraw-result.json. Contract details in skills/excalidraw-diagram/SKILL.md § "Inline invocation contract".

Requirements

• Aeon — any version supporting ./add-skill from third-party repos (essentially everything since v0.1).
• Node 20+ at skill-run time (for scripts/validate.mjs and the generate scripts).
• Claude Code (the Aeon runtime).
• No external API keys. No live canvas server. Fully offline.

Iterating on this skill

This repo is the canonical home — all changes happen here.

git clone https://github.com/aeonbook/aeon-excalidraw-diagram.git
cd aeon-excalidraw-diagram

# Re-run the canonical exemplar and validate (same check CI does)
node skills/excalidraw-diagram/examples/aeon-self-heal.generate.mjs > /tmp/test.excalidraw
node skills/excalidraw-diagram/scripts/validate.mjs /tmp/test.excalidraw skills/excalidraw-diagram/examples/aeon-self-heal.drawfile

# Edit skills/excalidraw-diagram/...
git commit -m "..."
git push

Forks that installed via ./add-skill pick up updates via Aeon's skill-update-check (Sunday cron) or by re-running ./add-skill aeonbook/aeon-excalidraw-diagram --all (overwrites).

License

MIT.