<div align="center">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="docs/images/figurecraft-wordmark-dark.svg">
<source media="(prefers-color-scheme: light)" srcset="docs/images/figurecraft-wordmark-light.svg">
<img src="docs/images/figurecraft-wordmark-light.svg" width="360" alt="FigureCraft — Deterministic figures for agents">
</picture>
### Publication-quality charts and technical diagrams from one prompt
Give **OpenAI Codex**, **Claude Code**, or **GitHub Copilot** a prompt, data file,
or structured FigureSpec. FigureCraft returns a validated figure plus the source
artifacts needed to inspect, edit, and reproduce it.
**English** · [简体中文](README.zh-CN.md)
[5-minute start](#quick-start) · [Gallery](#examples) · [How it differs](#why-figurecraft) · [Documentation](#documentation)
[](pyproject.toml)
[](LICENSE)
[](https://github.com/Zchary1106/figurecraft/actions/workflows/install-platforms.yml)
</div>
> **What it is:** a portable Agent Skill suite that turns requests such as
> “visualize these benchmark results” or “map this repository architecture”
> into deterministic, reviewable deliverables.
>
> **What it is not:** an image-generation wrapper or a hosted drawing canvas.
> FigureCraft uses Matplotlib for quantitative charts and an SVG-first layout
> engine for diagrams.
## One prompt, reproducible output
These are real FigureCraft outputs—not mockups. The lead example combines two
modality streams, bidirectional cross-attention, residual fusion, a repeated
transformer backbone, auxiliary supervision, and multiple task heads.
<p align="center">
<a href="skills/figurecraft/assets/examples/multimodal-fusion-network.json">
<img src="docs/images/multimodal-fusion-network.svg" width="100%" alt="A complex multimodal neural network with parallel vision and language encoders, cross-attention, residual fusion, transformer blocks, and multiple output heads">
</a>
</p>
<p align="center"><sub><strong>Complex neural architecture:</strong> click the figure to inspect the complete FigureSpec.</sub></p>
<table>
<tr>
<th width="50%">Scientific chart</th>
<th width="50%">Agent system architecture</th>
</tr>
<tr>
<td><a href="skills/figurecraft/assets/examples/uncertainty-band.json"><img src="docs/images/uncertainty-band.svg" width="100%" alt="A publication-ready uncertainty-band chart generated by FigureCraft"></a></td>
<td><a href="skills/figurecraft/assets/examples/agent-evidence-workflow.json"><img src="docs/images/agent-evidence-workflow.svg" width="100%" alt="An evidence-driven agent architecture generated by FigureCraft"></a></td>
</tr>
<tr>
<td>Units, confidence intervals, legends, and data checks.</td>
<td>Semantic roles, routed connectors, provenance, and editable Draw.io.</td>
</tr>
</table>
## At a glance
| Need | FigureCraft provides |
| --- | --- |
| **Research figures** | Line, bar, scatter, error-bar, histogram, box, and heatmap charts with units, uncertainty, and data checks. |
| **Technical diagrams** | Architecture, agent systems, process flows, swimlanes, Gantt charts, research frameworks, system landscapes, and neural-network figures. |
| **Reliable output** | Schema validation, measured typography, deterministic layouts, structural SVG linting, provenance, and hashes. |
| **Usable deliverables** | SVG source, optional PNG/PDF, editable Draw.io, the input FigureSpec, manifest, and preview page. |
| **Safe iteration** | Controlled revisions can preserve approved geometry; failed exports do not replace the prior delivery. |
## Quick start
### 1. Install for Codex
Clone the repository and install the skills into your user-level Codex skills
directory. The installer creates an isolated Python runtime and performs
readiness checks.
**macOS**
```bash
git clone https://github.com/Zchary1106/figurecraft.git
cd figurecraft
bash ./install.sh --agent codex
```
**Windows PowerShell**
```powershell
git clone https://github.com/Zchary1106/figurecraft.git
cd figurecraft
powershell -NoProfile -ExecutionPolicy Bypass -File .\install.ps1 --agent codex
```
Restart Codex or start a new task after installation so it can discover the
new skills.
<details>
<summary><strong>Claude Code, GitHub Copilot, project-only installs, and upgrades</strong></summary>
```bash
# Install for another supported host
bash ./install.sh --agent claude # or: copilot
# Install all supported hosts
bash ./install.sh
# Make skills available to a single project
bash ./install.sh --agent codex --scope project --project "/path/to/project"
# Update installed copies while preserving customized copies as backups
bash ./install.sh --agent codex --force
```
</details>
### 2. Paste one request
```text
Use FigureCraft to inspect this repository and create a reader-facing system
architecture diagram. Show the major components and verified relationships only.
Deliver the FigureSpec, SVG, editable Draw.io, and a slide-ready PNG.
```
Or start from data:
```text
Use FigureCraft to create a double-column scientific error-bar plot from
results.csv. The x-axis is epoch, the y-axis is accuracy, and error values are
standard deviation. Deliver SVG, 300 DPI PNG, and PDF.
```
The agent selects the relevant specialist automatically. You can also explicitly say `figurecraft-charts`, `figurecraft-architecture`, or another specialist name.
### 3. Inspect the delivery
A normal render produces an output folder with the figure, its editable and reproducibility artifacts, and a local preview page.
```text
output/
├── figure.svg # Primary vector figure
├── figure.drawio # Editable diagram file, when requested/supported
├── figure.png / figure.pdf # Optional final-size exports
├── figure-source.json # Normalized FigureSpec
├── figure-manifest.json # Checks, provenance, hashes, environment metadata
└── index.html # Local preview and delivery index
```
## Why FigureCraft
Most agent drawing workflows optimize for getting an image quickly. FigureCraft
optimizes for getting a figure you can trust, revise, and deliver.
| Workflow | Fast preview | Reproducible source | Semantic validation | Editable vector | Scientific checks |
| --- | :---: | :---: | :---: | :---: | :---: |
| Image-generation prompt | Yes | No | No | No | No |
| Generic diagram generation | Yes | Sometimes | Limited | Sometimes | No |
| **FigureCraft** | **Yes** | **FigureSpec** | **Yes** | **SVG + Draw.io** | **Yes** |
- **Deterministic:** the same FigureSpec and environment produce the same layout.
- **Inspectable:** every delivery includes normalized source, provenance, checks,
hashes, and a manifest.
- **Editable:** diagrams can include Draw.io alongside the primary SVG.
- **Medium-aware:** paper, slide, web, and poster outputs use explicit size and
typography constraints.
- **Fail-closed:** invalid data semantics, missing glyphs, lint failures, or
broken exports do not silently replace the last valid delivery.
## Examples
Every gallery image is generated from a checked-in FigureSpec. The wider layouts
are intentionally shown at full width so that tensor dimensions, repeated
blocks, residual paths, and connector semantics remain readable.
### Neural-network architecture plate
<p align="center">
<a href="skills/figurecraft/assets/examples/cnn-architecture.json">
<img src="docs/images/cnn-architecture.svg" width="100%" alt="A residual CNN architecture plate with tensor geometry, stage repeats, transitions, residual bottleneck detail, and visual grammar">
</a>
</p>
The plate exposes the full macro path, exact tensor schedule, repeated stages,
downsampling transitions, a representative bottleneck inset, projection
shortcut, and the visual grammar used to read the model.
### More figure families
<table>
<tr>
<th width="50%">Dense system landscape</th>
<th width="50%">Research framework</th>
</tr>
<tr>
<td><a href="skills/figurecraft/assets/examples/system-landscape.json"><img src="docs/images/system-landscape.svg" width="100%" alt="A dense system landscape generated by FigureCraft"></a></td>
<td><a href="skills/figurecraft/assets/examples/research-framework.json"><img src="docs/images/research-framework.svg" width="100%" alt="A research framework generated by FigureCraft"></a></td>
</tr>
<tr>
<th>Scientific comparison</th>
<th>Role-based process</th>
</tr>
<tr>
<td><a href="skills/figurecraft/assets/examples/bar-comparison.json"><img src="docs/images/bar-comparison.svg" width="100%" alt="A scientific bar comparison generated by FigureCraft"></a></td>
<td><a href="skills/figurecraft/assets/examples/swimlane.json"><img src="docs/images/swimlane.svg" width="100%" alt="A role-based swimlane process generated by FigureCraft"></a></td>
</tr>
</table>
See all checked-in inputs under [`skills/figurecraft/assets/examples/`](skills/figurecraft/assets/examples/).
## Pick the right specialist
| Skill | Best for |
| --- | --- |
| [`figurecraft`](skills/figurecraft/SKILL.md) | Shared FigureSpec workflow, rendering, exports, validation, and delivery. |
| [`figurecraft-charts`](skills/figurecraft-charts/SKILL.md) | Scientific plots, axes, units, uncertainty, annotations, and data validation. |
| [`figurecraft-architecture`](skills/figurecraft-architecture/SKILL.md) | Software architecture, system landscapes, agent systems, interfaces, and protocols. |
| [`figurecraft-neural-networks`](skills/figurecraft-neural-networks/SKILL.md) | Neural topology, tensor shapes, CNN stages, residual paths, and model plates. |
| [`figurecraft-research-frameworks`](skills/figurecraft-research-frameworks/SKILL.md) | Research methods, evidence chains, validity, and multi-workstream framework matrices. |
| [`figurecraft-process-diagrams`](skills/figurecraft-process-diagrams/SKILL.md) | Flowcharts, algorithms, swimlanes, and Gantt charts. |
| [`figurecraft-visual-critic`](skills/figurecraft-visual-critic/SKILL.md) | Reviewing and improving hierarchy, typography, routing, color, and readability. |
## How it works
[](skills/figurecraft/assets/examples/how-it-works.json)
FigureCraft uses a `FigureSpec` as the source of truth. The spec captures the content, semantics, output formats, language, final-size medium, layout options, and provenance. This makes a figure reproducible, reviewable, and safer to revise than a bitmap-only workflow.
## Output formats and requirements
| Output | Use case | Requirement |
| --- | --- | --- |
| **SVG** | Primary vector output and diagrams | Included by default. |
| **Draw.io** | Manual editing of supported diagrams | Included by default for supported diagram grammars. |
| **PNG / PDF** | Papers, slides, and raster workflows | Charts use Matplotlib; diagram conversion requires native Cairo. |
For Chinese labels, install a CJK font such as PingFang SC, Microsoft YaHei, or Noto Sans CJK SC. SVG and Draw.io diagram output work without native Cairo. To require every export during install:
```bash
bash ./install.sh --require-export
```
On macOS, install the diagram-export dependency with:
```bash
brew install cairo
```
For detailed diagnostics, supported library paths, Windows setup, and safe upgrades, see [Installation and runtime readiness](skills/figurecraft/references/installation.md).
## Use the CLI directly
Agent use is the standard path, but the CLI is useful in CI and local development.
```bash
# Check the runtime for a requested pipeline
python3 skills/figurecraft/scripts/figure.py check-env \
--format png --kind diagram.architecture --cjk
# Validate a FigureSpec without rendering
python3 skills/figurecraft/scripts/figure.py validate \
skills/figurecraft/assets/examples/line-chart.json
# Render one figure
python3 skills/figurecraft/scripts/figure.py render \
skills/figurecraft/assets/examples/agent-evidence-workflow.json \
--output output/agent-evidence-workflow
# Render a coordinated overview/detail set
python3 skills/figurecraft/scripts/figure.py render-set \
skills/figurecraft/assets/examples/framework-matrix.json \
--output output/framework
```
## Reliability boundaries
FigureCraft is designed to make the correct workflow easy, but it does not claim to replace editorial judgment.
- Values, units, uncertainty semantics, Gantt dependencies, declared network dimensions, and FigureSpec structure are validated before rendering.
- Text is measured using installed FreeType fonts; missing glyphs and impossible layouts are reported instead of silently clipped.
- Rendering is transactional: an export or lint failure preserves the previous complete delivery.
- Dense diagrams may still benefit from decomposition, a secondary detail view, or human visual review.
- Draw.io changes are not imported back into the FigureSpec automatically.
- Reference images guide layout and visual language; they are not copied pixel for pixel.
## Documentation
- [Contributing guide](CONTRIBUTING.md)
- [FigureSpec reference](skills/figurecraft/references/figure-spec.md)
- [Installation and runtime readiness](skills/figurecraft/references/installation.md)
- [Scientific-chart guidance](skills/figurecraft/references/scientific-charts.md)
- [Technical-diagram guidance](skills/figurecraft/references/technical-diagrams.md)
- [Final-size output for papers and slides](skills/figurecraft/references/output-media.md)
- [Controlled revisions](skills/figurecraft/references/controlled-edits.md)
- [Language and provenance](skills/figurecraft/references/language-and-provenance.md)
- [Reference-figure distillation](skills/figurecraft/references/reference-distillation.md)
- [Visual critique rubric](skills/figurecraft/references/critique-rubric.md)
New contributors can start with a real-world FigureSpec example, an installation
diagnostic, or a regression test for typography, routing, validation, or export.
Use the repository issue templates to report a reproducible problem or propose a
new figure family.
## Development
```bash
python3 -m venv .venv
.venv/bin/python -m pip install -e ".[export]"
# Full test suite
.venv/bin/python -m unittest discover -s tests -v
# Validate every bundled example
for spec in skills/figurecraft/assets/examples/*.json; do
.venv/bin/python skills/figurecraft/scripts/figure.py validate "$spec"
done
```
If macOS Python cannot discover Homebrew Cairo, run export tests with:
```bash
DYLD_FALLBACK_LIBRARY_PATH=/opt/homebrew/lib \
.venv/bin/python -m unittest discover -s tests -v
```
## Repository layout
```text
.
├── install.py / install.sh / install.ps1 Cross-platform installer
├── skills/ Core and six specialist skills
│ └── figurecraft/ Renderer, schema, examples, themes, and references
├── docs/images/ Checked-in gallery outputs
├── tests/ Renderer, installer, export, and safety regressions
└── .github/workflows/ Cross-platform install checks
```
## License
[MIT License](LICENSE)