drawlib 0.3.8

Pure-Python Library for "Illustration as Code" & "Illustrated Documentation as Code"

English | 日本語

Drawlib is a declarative drawing library and integrated multi-format documentation compiler engineered for software developers, technical writers, and autonomous AI coding agents. Instead of maintaining brittle diagrams in external GUI tools (draw.io, Visio, PowerPoint) and manually pasting exported screenshots into wikis, Drawlib lets you author, animate, localize, version-control, and compile architectural diagrams, quantitative charts, technical documents (HTML / PDF / Word .docx), and 16:9 slide decks (PowerPoint .pptx) entirely from code in Git. Beyond Python projects, zero-install uvx drawlib works immediately in any language repository (Go, Rust, TypeScript, Java, Terraform) as well as standalone non-code documentation and slide folders with zero Python environment setup.

• Official Website & Documentation: English (www.drawlib.com) | 日本語 (www.drawlib.com/ja/) | Zero-Install uvx Guide | API & CLI Reference (www.drawlib.com/api/) | Internal Architecture Spec
• Live Examples Gallery: Browse All Showcase Projects (examples.drawlib.com) | Source (drawlib-examples)
  • 16:9 Slide Decks: About Drawlib (HTML / PDF / PPTX) · DDoS Incident Postmortem (HTML / PDF / PPTX)
  • Guides & Whitepapers: Dogfooding Whitepaper — English / 日本語版 · Quickstart Guide (HTML / PDF / DOCX)

Try in 30 Seconds (Zero Install with uvx)

No pyproject.toml, virtual environment, or package installation required—works immediately in any directory (including Go, Rust, TypeScript, Java, and Terraform codebases, or standalone non-development documentation/slide folders) using uv:

# 1. Scaffold a bilingual documentation site (or: catalog, doc, slide, images)
uvx drawlib init project site -l en,ja

# 2. (Optional) Generate Drawlib rules for your AI coding agent (claude, cursor, antigravity, copilot, ...)
uvx drawlib init agent claude

# 3. Compile HTML site + Markdown + diagrams & launch local preview
./docs_src/build.sh
uvx drawlib serve docs_html/

Python project or global CLI? Install with uv add drawlib, uv tool install drawlib, or pip install drawlib. See the Zero-Install Workflow with uvx guide for polyglot repository and non-code documentation patterns.

Why Drawlib?

1. SmartArt Infographics, Quantitative Charts & Declarative Animations

Compose executive-ready infographics (drawlib.smartarts), quantitative data plots (drawlib.charts), and multi-frame APNG / WebP / GIF animations (drawlib.anim) on the exact same coordinate canvas:

• 18 SmartArt Components (drawlib.smartarts): High-level structured layouts including ChevronProcess, Cycle, Table, TreeNode, MindMapNode, Pyramid, BoxList, CardList, KpiCards, Roadmap, Panel, BulletPoints, GridLayout, syntax-highlighted SourceCode, offline vector maps (GeoMap), and MonthCalendar / WeekCalendar / DayCalendar.

• 10 Quantitative Charts (drawlib.charts): Pure-Python BarChart, BoxChart, LineChart, AreaChart, PieChart, RadarChart, ScatterChart, GanttChart, and HeatmapChart / HeatmapOverlay styled with the same design tokens as surrounding diagrams—no low-level Matplotlib boilerplate required.
• Declarative Animations (drawlib.anim): Turn any diagram, chart, or workflow into a crisp multi-frame APNG, WebP, or dither-free GIF animation (Animation(fps=..., loop=0)) for GitHub README.md files, HTML docs, X/LinkedIn posts, PowerPoint decks, and enterprise wikis.

2. Auto-Layout Graphs & Software Engineering Diagrams

Stop hand-tuning complex node coordinates. Combine automatic graph layout solvers (drawlib.graph) with domain-specific software engineering diagrams (drawlib.diagrams):

• 5 Auto-Layout Coordinate Solvers (drawlib.graph): Pure coordinate calculators (ArchitectureGraph, LayerGraph, TreeGraph, RadialGraph, GridGraph) that compute overlap-free node centers (.xy), nested cluster bounds, and offset() fine-tuning via get_layout() for seamless rendering with drawlib.diagrams and drawlib.shapes.

• 6 Technical Diagram Engines (drawlib.diagrams):
  • Cloud Architecture (ArchitectureDiagram): Nested VPC/subnet boundaries, multi-tier service cards, and official cloud provider icons.
  • Flowcharts (FlowDiagram): Process steps, decision branches, and orthogonal connectors.
  • Sequence Diagrams (SequenceDiagram): Client/server lifelines, synchronous/asynchronous calls, activation bars, and loop/alt frames.
  • State, UML Class & ER Diagrams (StateDiagram, ClassDiagram, ERDiagram): State lifecycles, object-oriented class hierarchies, and relational database schemas.

3. 34 Icon Suites (4,500+ Icons), 43 Primitives & Semantic Design System

At its core, Drawlib cleanly separates Content (geometry, coordinates, structure) from Style (colors, typography, borders, themes)—just like HTML and CSS:

• 34 Standardized Icon Suites (drawlib.icons): Over 4,500 offline-cached vector icons spanning Phosphor (1,512 icons across 5 weights), Cloud Providers (gcp, aws, azure), 15 Official Tech Brand Suites (ai, business, client, cloud, cnative, code, data, devops, facility, itservice, network, security, server, social, workspace), and 15 Flat 2D Suites (original_*).
• Rich Primitives (drawlib.shapes, lines, images, text, fonts):
  • 43 Geometric Shapes: Spanning basic, polygon, arrow, badge, container, and symbol primitives.
  • Lines & Connectors: Straight, curved (bend), quadratic/cubic Bezier, and rounded polylines with rich arrowheads ("->", "<-", "<->").
  • Images & Nested Canvases: Non-destructive Dimage transformations (crop(), sepia(), grayscale(), mosaic(), mirror()) plus in-memory diagram nesting via get_dimage_from_code().
  • Multilingual Typography: Automatic on-demand font caching (FontRoboto, FontSansSerif, FontSerif, FontSourceCode, FontJapanese, FontChinese, FontKorean, FontArabic, etc.).
• 7-Role Semantic Style System (drawlib.styles):
  • 6 built-in themes (default, google, essentials, monochrome, warm, cold) accessed via Styles.<Token> (Styles.Neutral, Styles.PrimaryFlat, Styles.SecondaryNeutral, Styles.MutedDashed, Styles.SuccessNeutral, Styles.WarningNeutral, Styles.DangerNeutral).

4. Illustrated Documentation & 16:9 Slide Deck as Code (Multi-Locale & SEO Ready)

Author Markdown files with embedded ```drawlib code fences inside a unified drawlib.toml project. A single build compiles your repository into web portals, GitHub Markdown, PDFs, editable Word documents, HTML slide decks, and PowerPoint files:

• Unified drawlib.toml, Multi-Locale ([i18n]) & Declarative SEO ([seo]): Configure [project] metadata, [i18n] locales (langs = ["en", "ja"] with structural parity checks), [seo] publishing (site_url, Open Graph / X social cards, hreflang, sitemap.xml, robots.txt, and AI-ready llms.txt), and [catalog] reference navigation directly in drawlib.toml.
• 5 Project Scaffolds (drawlib init project <type>):
  • drawlib init project site [-l en,ja]: Multi-page documentation website (docs_html/ with language switcher, search, and sidebar TOC) and GitHub Markdown (docs_markdown/).
  • drawlib init project catalog [-l en,ja]: Illustrated catalog & reference website (catalog_html/ with automatic # H1 / ## H2 sidebar extraction, 50+ semantic badges, and / instant filter) for APIs, CLI references, schemas, and service registries.
  • drawlib init project doc [-l en,ja]: Linear technical specification or whitepaper (*_html/, *_markdown/, vector *_<lang>.pdf, plus editable MS Word *_<lang>.docx via ./<target>_src/build_docx.sh or drawlib build docx).
  • drawlib init project slide [-l en,ja]: 16:9 presentation slide deck (::: block + ::: note speaker notes) with native SVG typography, Presenter View, keyboard navigation (slide_html/), vector slide_<lang>.pdf, and editable MS PowerPoint slide_<lang>.pptx via ./<target>_src/build_pptx.sh or drawlib build pptx.
  • drawlib init project images: Standalone batch Python illustration scripts (images_src/ -> images/) backed by multi-core parallel rendering (-w auto) and sub-millisecond .drawlib/cache.db incremental caching.
• Multi-Core Parallel Build & Sub-Millisecond Incremental Cache (drawlib build -w auto): Cold diagram builds scale automatically across CPU cores (1 <= cores - 1 <= 8 spawn workers across all 7 build targets), while unchanged diagrams restore from .drawlib/cache.db in under 1 ms.
• AI Inner Loop & Human Outer Loop (drawlib init agent <agent>): Built from the ground up for AI coding agents (Claude Code, Cursor, Antigravity, Copilot, Windsurf, Cline, Roo, Codex, Gemini). Generate native workspace instruction files in one command (drawlib init agent claude), while agents query drawlib rules show <topic> on demand, render headless coordinate-grid previews via drawlib show -g, and multimodally self-correct text clipping or layout defects—freeing engineers to focus on high-level architecture and review.

Installation

Run drawlib instantly with zero installation via uvx, or install from PyPI into your Python project or global CLI environment (Python >= 3.11):

# Zero-install CLI (ideal for quick try & non-Python repos: Go, Rust, TypeScript, Java)
uvx drawlib --version

# Add to a Python uv project (for importing `drawlib.*` in scripts/tests)
uv add drawlib

# Or install globally as a persistent CLI tool / via pip
uv tool install drawlib   # or: pip install drawlib

Configure AI Agent Instructions (Optional — Strongly Recommended)

If you author code or documentation with an AI coding agent (Claude Code, Cursor, Antigravity, GitHub Copilot, Windsurf, Cline, Roo Code, OpenAI Codex, or Gemini CLI), initialize workspace agent instructions right after setup (prefix with uvx or uv run as needed) so your agent automatically follows Drawlib's bottom-left (0, 0) coordinate space, 50%+ neutral style discipline, drawlib init project scaffolding, and 3-stage visual self-correction loop:

drawlib init agent list                   # List supported agents & target file paths
drawlib init agent claude                 # -> .claude/rules/drawlib.md
drawlib init agent cursor                 # -> .cursor/rules/drawlib.mdc
drawlib init agent antigravity            # -> .agents/rules/drawlib.md
drawlib init agent claude cursor copilot  # Initialize multiple agents (or 'all')

Zero-Config Export & Offline Caching

PDF, MS Word (.docx), and MS PowerPoint (.pptx) export work out of the box—playwright, python-docx, and python-pptx are standard dependencies, and headless Chromium (chromium-headless-shell) downloads automatically on your first drawlib build pdf or drawlib build pptx run.

• Offline / Air-Gapped / CI Environments: Pre-download all fonts, icons, maps, and headless Chromium ahead of time with drawlib cache download --all (or Chromium only with drawlib cache download --browser).
• Minimal Linux Containers (e.g., python:3.12-slim lacking OS shared libraries such as libnss3 or libgbm1): Install OS browser dependencies once via playwright install-deps chromium (or playwright install --with-deps --only-shell chromium).

Quick Start

1. Standalone Python Script (5-Step Drawing Workflow)

Every Drawlib script follows a clean 5-step pattern: Import -> Setup Canvas -> Draw Zones (Optional) -> Shapes & Lines -> Save:

Create client_server.py:

from drawlib.canvas import save, setup
from drawlib.lines import line
from drawlib.shapes import circle, rectangle
from drawlib.styles import Styles
from drawlib.text import text

setup(width=100, height=44)
# Optional: boundary zone
rectangle((50, 22), 92, 36, style=Styles.MutedDashed)
circle((25, 22), 12,
       style=Styles.Neutral, text="Client")
rectangle((75, 22), 26, 20,
          style=Styles.PrimaryFlat, text="Server")
line((37, 22), (62, 22),
     arrow_head="->", style=Styles.DarkBold)
text((49.5, 27), "REST API", style=Styles.DarkBold)
save()

Run the script to generate client_server.png:

# Zero-install via uvx (works anywhere without project setup)
uvx drawlib show client_server.py -o client_server.png

# Or inside a Python uv project (`uv add drawlib`)
uv run python client_server.py

Core Principles at a Glance

• Bottom-Left Origin (0, 0): setup(width=100, height=44) defines a Cartesian coordinate canvas where x spans 0..100 (left to right) and y spans 0..44 (bottom to top).
• Predictable Coordinate Anchors: Core primitives (rectangle, circle, icon, image, text) anchor at their center (cx, cy) for effortless alignment, while high-level Charts and Diagrams anchor at bottom-left (x0, y0).
• 50%+ Neutral Baseline: Ground supporting shapes in calm neutral tokens (Styles.Neutral, Styles.SecondaryNeutral, Styles.MutedDashed) and reserve saturated fills (Styles.PrimaryFlat) for 1–2 focal elements.
• Non-Destructive Style Patching (.patch()): Customize any preset token cleanly via Styles.MutedBold.patch(text_size=10) or Styles.Primary.patch(shape_line_width=2).

2. Illustrated Documentation & Slide Deck Workflow

Scaffold a multi-page documentation site, linear whitepaper, or 16:9 slide deck in seconds (pass -l en,ja for multi-locale <src_dir>/<lang>/ projects; prefix with uvx if running zero-install):

# Initialize a bilingual multi-page documentation site in docs_src/ (en/ & ja/)
drawlib init project site -l en,ja

# Or initialize a 16:9 presentation slide deck in slide_src/
drawlib init project slide -l en,ja

# Generate AI coding agent instructions for your IDE / CLI agent
drawlib init agent claude

Inside your Markdown files (docs_src/en/index.md), embed Python drawing blocks using the ```drawlib fence:

# System Architecture

Below is our core request routing pipeline:

```drawlib code=fold align=center file=service_routing.png caption="Service Routing Pipeline"
from drawlib.canvas import save, setup
from drawlib.lines import line
from drawlib.shapes import rectangle
from drawlib.styles import Styles

setup(width=100, height=40)
rectangle((25, 20), width=30, height=16, r=2, style=Styles.Neutral, text="Ingress")
rectangle((75, 20), width=30, height=16, r=2, style=Styles.PrimaryFlat, text="Core API", text_style=Styles.WhiteBold)
line((40, 20), (60, 20), arrow_head="->", style=Styles.DarkBold)
save()
```

Compile, export, and preview with the generated scripts (which automatically detect uv run drawlib, drawlib, or uvx drawlib) or the CLI:

# Build HTML site, GitHub Markdown, or PDF via generated build script
./docs_src/build.sh

# Export editable MS Word (.docx) or MS PowerPoint (.pptx) per locale
./doc_src/build_docx.sh      # or: drawlib build docx doc_src/ -o spec.docx --generate-index
./slide_src/build_pptx.sh    # or: drawlib build pptx slide_src/ -o deck.pptx

# Launch local HTTP server with pre-flight broken-link verification
drawlib serve docs_html/ --check

# Render a single diagram with coordinate grid (-g) for visual layout inspection
drawlib show docs_src/en/index.md service_routing.png -g -o preview_grid.png

3. CLI Reference Summary

Links & Resources

• Official Documentation: English (https://www.drawlib.com/) | 日本語 (https://www.drawlib.com/ja/) | API & CLI Reference (https://www.drawlib.com/api/) | Internal Architecture Spec (https://www.drawlib.com/architecture/)
• Live Examples Gallery: https://examples.drawlib.com/ (yuichi110/drawlib-examples)
• Release Notes & Changelog: English | 日本語
• Contributor & Developer Guide: CONTRIBUTING.md | docs_src/README_DEV.md
• PyPI Package: https://pypi.org/project/drawlib/
• GitHub Repository: https://github.com/yuichi110/drawlib
• License: Apache License 2.0