✎ DesignCore

🌐 Project website

Verified diagrams for documentation — draw.io, Mermaid, or Excalidraw, from a spec your AI agent can actually be trusted to write.

DesignCore turns a coordinate-free graph spec into a verified diagram, where the model never places a shape and nothing counts as finished until it has actually rendered. It ships three agent skills (architecture-diagram, flow-diagram, concept-sketch) that carry the judgment layer on top.

🧭 What "verified" means

The spec compiled cleanly, every backend rendered successfully, and deterministic structural/density/geometry checks passed.

It does not mean the diagram is visually correct or that it communicates well — judgment about content stays with you.

⚖️ The two rules

LLMs are good at structure and bad at pixels. DesignCore splits the job along exactly that line: judgment lives in the skills, mechanism lives in the package.

🚀 Install

Requires uv.

# As an installable CLI tool (from GitHub today; PyPI pending)
uv tool install git+https://github.com/BlinkVoid/DesignCore.git

# Or from a clone, for development
git clone https://github.com/BlinkVoid/DesignCore.git && cd DesignCore
uv sync
uv run designcore doctor

Render backends

designcore doctor reports what's available and names the exact install command for anything missing:

The Excalidraw helper needs its own dependencies once:

npm install --prefix src/designcore/render/js

🛠️ Commands

--root points at the diagram directory (default docs/diagrams). render also takes --format, and the choice is sticky: an explicit flag wins over the manifest's recorded format, which wins over the excalidraw default. A diagram has one format and one manifest entry at a time — switching format replaces the entry, and check reports the abandoned files as orphans.

💡 Mermaid is the right choice when the diagram lives in markdown: it renders natively on GitHub and diffs as text. See skills/_shared/references/format-selection.md.

📐 How it fits together

.spec.yaml ──► parse_spec ──► layout_spec (Graphviz) ──┬──► emit_* ──► source file
                                                       │                  │
   rejects coordinates                                 │                  ▼
   at parse time                                       │              render_* ──► svg + png
                                                       │                  │
                                                       └────────────── lint ◄┘
                                                                          │
                                                                     diagrams.yaml

Judgment lives in the skills; mechanism lives in the package. The package makes no aesthetic decisions, and the skills compute no geometry.

📁 Example

A worked example lives in examples/docs/diagrams/: one spec, its excalidraw render, and a populated manifest.

uv run designcore render designcore-pipeline --root examples/docs/diagrams

📚 Further reading

📄 License

MIT