<div align="center">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="frontend/public/brand/evodesign-lockup-dark.svg?v=syne700-1">
<source media="(prefers-color-scheme: light)" srcset="frontend/public/brand/evodesign-lockup.svg?v=syne700-1">
<img src="frontend/public/brand/evodesign-lockup.svg?v=syne700-1" alt="EvoDesign logo" width="276" height="64">
</picture>
### Personalized diagram workspace, together with your Agent.
**English** · [简体中文](README.zh-CN.md)
<!-- PROJECT-LINKS:START -->
<div align="center">
[](https://evodesign.aurax.live/)
[](https://tianfu.wang/EvoDesign/)
[](https://arxiv.org/abs/2604.09568)
</div>
<!-- PROJECT-LINKS:END -->
<sub>The current browser edition: start from a prompt, add reference content, and choose your diagram type and model.</sub>
</div>
EvoDesign is an open-source diagram workspace that you share with your Agent. Generate an architecture, sequence or process diagram, edit every element on the canvas, and let your Agent continue the work through the EvoDesign CLI. Your structure, style and layout preferences come with you to the next diagram.
Try the [browser edition](https://evodesign.aurax.live/) with the shared GLM-5.3-Flash demo or your own model, or run the full edition locally with your own model endpoint. EvoDesign is built on our NeurIPS 2026 paper, [**EvoDesign: Agentic Editable Diagram Creation via Design Expertise Evolution**](https://arxiv.org/abs/2604.09568), which explains the method and evaluation.
[Why EvoDesign](#why-evodesign) · [Try it online](#try-it-online) · [Run locally](#run-locally) · [How it works](#how-evodesign-works) · [Repository map](#repository-map)
## Why EvoDesign
**Every element stays editable.** Not an image, not code. Every node, edge and group is a canvas object you can move, restyle or regroup, by hand or with a one-line request. Save it, reopen it, and export it when it is ready.
**Edit together with your Agent.** Your terminal Agent, such as Claude Code or Codex, reads your paper or code and proposes a diagram through the EvoDesign CLI. Review the real render in the browser, accept it and keep editing. Next time, your Agent builds on your saved edits instead of overwriting them. See [Work with your existing Agent](#work-with-your-existing-agent).
**Learns how you design.** Keep your structure, style and layout preferences as a personal Design DNA. Review, pin and export the rules, and they shape your next diagram; your Agent works with the same DNA. Underneath, EvoDesign checks each render for overlaps, crossings and text overflow, repairs only what is broken, and turns fixes that keep working into design knowledge for future diagrams.
<sub>Agent collaboration and design expertise evolution run in the full local edition. The browser edition keeps your DNA preferences locally and includes them in requests.</sub>
## What is included
| Component | What you can do |
| --- | --- |
| **Diagram engine** | Generate architecture, sequence, flow and other diagram types; evaluate and refine their design |
| **Web workspace** | Generate, edit, save, reopen and export diagrams; turn icons on or off |
| **Agent CLI + skill** | Use your existing terminal Agent to prepare candidates, inspect previews and continue from saved Web edits |
| **Personal design memory** | Manage structure, style and layout preferences; learn from edits; import and export portable rules |
| **Design expertise** | Retrieve reusable strategies from 129 bundled seed entries and evolve knowledge through feedback |
| **Research tooling** | Run baseline adapters, ablations and evaluation with your own data |
Excalidraw is the default canvas. TLDraw remains an optional adapter. Icons are optional and the default curated catalog is bundled. The project, Python package (`evodesign`) and CLI command use the **EvoDesign** name. See the [package migration notes](docs/guides/configuration.md#package-name-migration) when upgrading an older checkout.
## Try it online
Open **[EvoDesign Studio](https://evodesign.aurax.live/)** and start with the shared **GLM-5.3-Flash** demo; no API key is required. In **Model settings**, you can switch to your own API URL, model ID and key. Custom providers must allow browser requests (CORS). Projects stay in your browser; export a copy as a backup.
The browser edition offers editable generation, optional icons, content review, local edits, saving and export without running the Python backend. Shared demo requests pass through a small Vercel function to BigModel; its key stays server-side and shared usage is capped. Custom model requests go directly to your provider.
| | Browser edition | Full local edition |
| --- | --- | --- |
| **Start** | Open the demo; no API key or EvoDesign account needed | Install Python and Node.js; configure your model |
| **Generation & review** | Graph planning, local layout and optional content review | Structure, style and layout agents; verification and optional visual refinement |
| **Design memory** | Manage preferences locally and include them in prompts | Personal memory, expertise retrieval and knowledge evolution |
| **Project storage** | This browser; export copies for backup | Your backend and database |
| **External Agent collaboration** | Guide to setting up the backend edition | Project-scoped CLI connections, previews, safe commits and checkpoint restoration |
The online edition is a lightweight path for trying editable generation; the method below describes the full research framework. See the [capability and privacy guide](docs/guides/browser-edition.md) for details.
## How EvoDesign works
EvoDesign coordinates generation and feedback around a **diagram manifest**: an object-level canvas representation that agents can update and people can edit directly.
### Overall architecture
*Overall architecture from the maintained manuscript source. [Open the full-resolution figure](docs/assets/method-overview.png) · [Read the paper](https://arxiv.org/abs/2604.09568).*
1. **Create an editable diagram.** Structure, style and layout agents turn content and user requirements into a canvas manifest, guided by retrieved design expertise.
2. **Verify and refine.** Render the manifest, check geometric defects and visual quality, then apply localized edits and verify the result again.
3. **Collect useful experience.** Keep the issues, edits and outcomes from refinement traces as evidence for candidate design strategies.
4. **Evolve reusable expertise.** Distill supported strategies into broader guidelines and principles, maintain the memory, and retrieve relevant knowledge for future diagrams.
## Run locally
Requires **Python 3.11+**, **Node.js 22.12+** and a vision-capable model endpoint. Model calls use your own provider account. These instructions install from source; there is no hosted generation API included.
```sh
git clone https://github.com/GeminiLight/EvoDesign.git
cd EvoDesign
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -e ".[backend,test]"
npm ci --prefix frontend
npm ci --prefix evodesign/agentic_system/tool_services
python scripts/setup_local.py
```
Fill **`LLM_MODEL_NAME`**, **`LLM_ENDPOINT_URL`** and **`LLM_API_KEY`** in the generated root `.env`, then:
```sh
./scripts/start_service.sh
```
Open **http://localhost:5175**. The API is on port 3010 and rendering service on 3000. Stop with `./scripts/stop_service.sh`. The local setup creates unique secrets and matching guest configuration. Existing `.env` files are never overwritten. See [configuration](docs/guides/configuration.md) for provider selection, optional features and hosted deployment boundaries.
The renderer needs Playwright Chromium for image export. On a machine without it, run `cd evodesign/agentic_system/tool_services && npx playwright install chromium`. Linux may need `npx playwright install --with-deps chromium` and native Canvas libraries (`libcairo2-dev`, `libpango1.0-dev`, `libjpeg-dev`, `libgif-dev`, `librsvg2-dev`, `pkg-config`). The first design-memory run may download its embedding model.
### Work with your existing Agent
With the backend, Web and renderer running, install the lightweight CLI and connect one Excalidraw project:
```sh
python -m pip install ./cli
evodesign connect --server http://localhost:3010 --profile paper
evodesign document get --profile paper --json
```
Approve the printed code in Web. Give your Agent [the EvoDesign skill](skills/evodesign/SKILL.md) to prepare semantic edits and inspect the real PNG. You can accept candidates in Web or allow the connection to commit. Saved manual edits and DNA are shared; conflicts retain candidates, and incoming versions preserve unsaved Web drafts. Restoring a checkpoint creates a new version.
This v1 uses the backend edition; browser-local projects, MCP and TLDraw editing are outside its scope. See the **[Agent collaboration guide](docs/guides/agent-collaboration.md)** for installation, commands, handoffs and recovery. CLI edits use your Agent's reasoning and do not invoke the backend generation model.
### Use the engine without the web UI
With the Python environment, model configuration and renderer running:
```sh
python -m evodesign.agentic_system.main --example 1 --dataset-path examples/diagrams/quickstart.json
# For the research CLI, enable icons explicitly (new web diagrams default on):
python -m evodesign.agentic_system.main --example 1 --dataset-path examples/diagrams/quickstart.json --use-icons
```
Use `--help` for custom input, refinement, ablations and personal edit-learning options. [Reproducibility notes](research/reproducibility.md) explain model/judge configuration, experiment records and the distinction between this maintained release and the manuscript's reported scores.
## Personal design memory
The complete memory implementation is included: preference extraction, storage, retrieval, scoped DNA rules and web management. Start with the [design-memory guide](docs/guides/design-memory.md) and the [eight-rule blue-violet example](examples/design-memory/blue-violet.json):
```sh
python scripts/design_memory.py validate examples/design-memory/blue-violet.json
```
Signed-in users can export and additively import rules through the same utility. Guest preferences stay in the browser. Private account databases, generated diagrams and live vector stores are not bundled.
## Research and reproducibility
The [paper, **EvoDesign: Agentic Editable Diagram Creation via Design Expertise Evolution**](https://arxiv.org/abs/2604.09568), describes the method and evaluates it with CanvasBench across content, visual and cognitive dimensions.
### CanvasBench
*CanvasBench construction and evaluation from the maintained manuscript source. [Open the full-resolution figure](docs/assets/canvasbench-overview.png) · [Read the paper](https://arxiv.org/abs/2604.09568).*
The repository includes the implementation, evaluation tools and baseline adapters. **Training and test datasets will be released separately.** The one-task quick-start example is for trying the software, not benchmarking it. The website's research scores are manuscript-reported results; this maintained code release does not claim a fresh reproduction of the full experiment. See [reproducibility notes](research/reproducibility.md) for research use.
## Repository map
```text
evodesign/ Core agents, refinement, memory and renderer service
backend/ FastAPI, projects, authentication and personal DNA
frontend/ React workspace and editable canvas adapters
cli/ Standalone Agent CLI (no engine installation required)
skills/evodesign/ Portable workflow and operation references for Agents
configs/ Model roles and application settings
evaluation/ Evaluation and analysis
baselines/ Comparison methods and adapters
examples/ Quick-start task and portable personal-memory example
scripts/ Setup, services, quality checks and experiments
docs/ Website, user guides, development reference and historical records
research/ Dataset preparation, research prompts, paper metadata and reproduction notes
```
## Development
Start with the [contribution guide](CONTRIBUTING.md), [quality checks](docs/development/engineering-quality.md) and [backend API reference](docs/development/backend-api-surface.md). Contributions in English or Chinese are welcome.
```sh
python -m pip install -e ".[dev]"
./scripts/check_quality.sh all
```
See [contributing](CONTRIBUTING.md), [configuration](docs/guides/configuration.md) and [third-party notices](licenses/README.md). Please include a minimal input, model identifier, release commit and relevant redacted logs when reporting a bug. Do not attach API keys, account databases or private prompts.
## Contributors
<p>
<a href="https://github.com/GeminiLight"><img src="docs/assets/contributors/geminilight.svg" width="64" height="64" alt="Tianfu Wang" title="Tianfu Wang" /></a>
<a href="https://github.com/USTChandsomeboy"><img src="docs/assets/contributors/ustchandsomeboy.svg" width="64" height="64" alt="Yi Zhan" title="Yi Zhan" /></a>
<a href="https://github.com/one2piece2hello"><img src="docs/assets/contributors/one2piece2hello.svg" width="64" height="64" alt="novacore" title="novacore (@one2piece2hello)" /></a>
<a href="https://github.com/JoeyWu-tech"><img src="docs/assets/contributors/joeywu-tech.svg" width="64" height="64" alt="Yin WU" title="Yin WU (@JoeyWu-tech)" /></a>
</p>
## Acknowledgments
- [diagram-design](https://github.com/cathrynlavery/diagram-design) — thank you to [Cathryn Lavery](https://github.com/cathrynlavery) for sharing diagram design guidance and examples.
## Citation
If you use EvoDesign or CanvasBench, please cite our **NeurIPS 2026** paper. GitHub's **Cite this repository** action is backed by `CITATION.cff`.
<!-- CITATION:START -->
```bibtex
@inproceedings{wang2026evodesign,
title = {{EvoDesign}: Agentic Editable Diagram Creation via Design Expertise Evolution},
author = {Wang, Tianfu and
Ding, Leilei and
Tao, Ziyang and
Zhan, Yi and
Ma, Zhiyuan and
Wu, Wei and
Lei, Yuxuan and
Wang, Junyang and
Wu, Yin and
Xu, Yizhao and
Zhu, Hongyuan and
Liu, Qi and
Yuan, Nicholas Jing and
Zhang, Yanyong and
Xiong, Hui},
booktitle = {Advances in Neural Information Processing Systems (NeurIPS)},
year = {2026},
url = {https://arxiv.org/abs/2604.09568}
}
```
<!-- CITATION:END -->
## License
Original EvoDesign software contributions are released under [MIT](LICENSE). Dependencies, bundled fonts/icons and incorporated third-party material retain their own terms; see [third-party notices](licenses/README.md). In particular, the optional TLDraw SDK uses its upstream license. The software license does not relicense the paper or third-party dataset source material.