Drawlib

Illustration & Documentation as Code

Pure-Python declarative visuals and multi-target documentation compiler built for software engineers and AI coding agents.

Official Showcase Deck · v0.3.5 Ready

Drawlib — Illustration & Documentation as Code

Drawlib at a Glance

Drawlib — Illustration & Documentation as Code

Presentation Roadmap

Six Core Chapters

Motivation (Ch. 1): Solving visual documentation drift with Python and Git
Visual Engines (Ch. 2–4): Primitives, 34 icon suites, SmartArts, charts, and diagrams
Publishing & AI (Ch. 5–6): Five project archetypes, Office export, and AI grid review

Drawlib — Illustration & Documentation as Code

Why Visual Documentation Breaks Down

Engineering teams are forced to choose between untrackable GUI binaries, rigid text DSLs, and isolated plotting libraries—causing visual architecture docs to drift behind code on every release.

Drawlib — Illustration & Documentation as Code

Illustration & Documentation as Code

Pure Python + Markdown

Turing-Complete Layout: Loops, variables, and shared utils.py helpers
Inline Code Blocks: Embed drawlib visuals directly inside Markdown
Deterministic PR Diffs: Review prose and diagram updates together

setup(width=120, height=32)
p = ChevronProcess(style=Styles.Neutral)
for s in ("Code", "Build", "Ship"): p.add(s)
p.draw((6, 8), width=108, height=16)
save()

Drawlib — Illustration & Documentation as Code

Tooling Landscape Comparison

This comparison matrix summarizes where Drawlib sits across six critical engineering dimensions. GUI whiteboards excel at freeform dragging, yet fail Git PR review, multi-target document compilation, and AI automation. Text DSLs like Mermaid pass Git review, but forfeit spatial coordinate control, rich infographics, and full document/slide publishing. Plotting libraries like Matplotlib give Python control over numeric charts, yet cannot express cloud topologies, UML diagrams, or multi-target documentation sites and slides. Drawlib combines clean Python Git diffs, exact (x, y) coordinates paired with optional graph layout solvers, 6 diagram engines with 34 icon suites, 27 SmartArts and charts, 5 publishing archetypes, and a built-in -g visual grid CLI designed from day one for AI self-healing.

Drawlib — Illustration & Documentation as Code

One Git Repository, Every Output Format

A single drawlib.toml manifest with [i18n] structural parity compiles synchronized English and Japanese deliverables across Web, Print, and Office from one Git commit.

Drawlib — Illustration & Documentation as Code

Cartesian Canvas & Visual Grid (-g)

Predictable Math Geometry

Bottom-Left Origin: (0, 0) starts bottom-left (+X right, +Y up).
Center Anchor: (x, y) centers every shape, text, and icon.
Visual Grid (-g): Overlay coordinate ticks for exact verification.

setup(width=100, height=60)
st = Styles.PrimaryFlat
rectangle((50, 30), 36, 22, style=st)
save()

Drawlib — Illustration & Documentation as Code

43 Geometric Shapes & Smart Connectors

Drawlib — Illustration & Documentation as Code

Multilingual Typography & Raster Assets

Universal Scripts & Dimage

CJK + Latin Default: Font renders English and Japanese together.
Regional Packs: FontJapanese, FontArabic, and FontSourceCode.
Exact Text Anchors: Control alignment via halign and valign.
Raster Dimage: Crop, resize, sepia, mosaic, plus font caching.

Drawlib — Illustration & Documentation as Code

34 Icon Suites & 4,500+ Vector Icons

Drawlib — Illustration & Documentation as Code

8-Color Semantic Styles & Preset Themes

Semantic Matrix: Styles.<Color><Variant> combines 8 roles (Primary..Dark) with Flat, Bold, Dashed, and Neutral.
Immutable .patch() & Themes: Customize safely via style.patch(...) or switch global themes in drawlib.toml.

Drawlib — Illustration & Documentation as Code

Process Pipelines, Lifecycles & Roadmaps

Drawlib — Illustration & Documentation as Code

KPIs, Feature Cards, Pyramids & MindMaps

Drawlib — Illustration & Documentation as Code

Tables, SourceCode, Calendars & GeoMap

Drawlib — Illustration & Documentation as Code

Declarative Bar, Line & Area Charts

Drawlib — Illustration & Documentation as Code

Pie, Radar, Scatter & Heatmap Charts

Drawlib — Illustration & Documentation as Code

Engineering Roadmaps with GanttChart

Declarative Schedule Modeling: Group workstreams with Section, track completion via Task(progress=...), and pin Milestone diamonds.
Dependencies & Live Status Markers: Route orthogonal Dependency arrows and overlay vertical Marker lines (Today, Release) in code.

Chapter 4 Overview — Engineering Diagrams, Auto-Layout Graphs & Animations:

In Chapter 3 we explored SmartArts and statistical Charts for executive storytelling and data visualization. Chapter 4 moves into deep software and systems engineering.
First, we cover Drawlib's 6 purpose-built diagram engines (drawlib.diagrams): ArchitectureDiagram for multi-tier cloud topologies, FlowDiagram and SequenceDiagram for workflows and API protocols, and ClassDiagram, ERDiagram, and StateDiagram for domain modeling.
Next, we examine drawlib.graph, Drawlib's pure-Python coordinate solver suite (ArchitectureGraph, LayerGraph, TreeGraph, RadialGraph, and GridGraph) that eliminates manual (x, y) math while preserving manual fine-tuning via offset().
Finally, we demonstrate drawlib.anim, bringing declarative frame-based APNG and Animated WebP motion to every module in Drawlib with interactive presentation playback and automatic PDF/PPTX frame extraction.

Drawlib — Illustration & Documentation as Code

Cloud Topology with ArchitectureDiagram

Cloud Infrastructure Topology with ArchitectureDiagram:

33 Built-In Icon Catalogs: ArchitectureDiagram integrates official cloud provider icons (GcpIcon, AwsIcon, AzureIcon), technology domain logos (CnativeIcon, DataIcon, DevopsIcon), and 1,500+ monochrome UI symbols (PhosphorIcon) directly inside Node cards.
Hierarchical Network Boundaries (NodeGroup): Here, Production VPC (10.0.0.0/16) encloses both GKE API Microservices (focal hero node in Styles.PrimaryFlat) and Cloud Run Async Workers using clean group-local coordinates relative to the VPC's bottom-left origin.
Orthogonal Bus Fan-Out & Clean Routing: Calling edge.fork([gke, run], at_x=60.5) creates an automatic T-junction bus from the Cloud CDN & Armor WAF edge tier into the VPC compute services, while non-crossing Manhattan edges connect compute tiers to Cloud SQL, Pub/Sub, and BigQuery.

Drawlib — Illustration & Documentation as Code

Workflows & Protocols: Flow and Sequence

Workflows & Interaction Protocols (FlowDiagram & SequenceDiagram):

Left (FlowDiagram): Implements ISO 5807 / JIS X 0121 flowchart shapes (Start, Process, Decision, Data, End) plus optional vertical or horizontal swimlanes (Lane). Explicit side anchoring (start_side="right", end_side="left") produces clean orthogonal decision branches and loopback paths—here illustrating Drawlib's own CI/CD visual grid-check loop.
Right (SequenceDiagram): Models chronological interactions across lifelines (Client, API Gateway, Auth, Order DB) without manual Y-axis calculation. Supports synchronous requests (request), dashed return messages (reply), asynchronous fire-and-forget calls (is_async=True), lifeline activation spans (activate() / deactivate()), and Python with context blocks (alt, loop, opt, par).

Drawlib — Illustration & Documentation as Code

Domain Modeling: Class, ER & State Diagrams

Domain Modeling with ClassDiagram, ERDiagram, and StateDiagram:

ClassDiagram (Left): Renders three-compartment UML 2.0 classes (ClassNode) with stereotypes (<<abstract>>, <<interface>>), member visibility (+, -, #, ~), and all 6 canonical UML relationships (inheritance, realization, composition, aggregation, dependency, association).
ERDiagram (Center): Models relational database schemas (USERS, ORDERS, ORDER_ITEMS) using Information Engineering Crow's Foot notation (1:*, 1:1..*) with aligned PK / FK constraint columns and optional row-level foreign key anchoring.
StateDiagram (Right): Expresses UML 2.x finite state machines (InitialState → Queued → Rendering → Cached / Failed → FinalState) with pseudo-states, entry/do/exit compartments, and orthogonal or curved transitions.

Drawlib — Illustration & Documentation as Code

Declarative Graph Layout (drawlib.graph)

Hybrid Algorithmic + Manual Control

Auto-Solve Topology: Crossing-free (x, y) via get_layout()
Manual Fine-Tuning: Nudge nodes with offset(dx, dy) anytime
No Black-Box Lock-In: Inspect & freeze code via print(layout)

g = LayerGraph(direction="LR")
g.edge("ingest", "validate")
g.edge("validate", "serve")
layout = g.get_layout(margin=8.0)
layout.offset("serve", dy=-4.0)

Declarative Coordinate Solving with drawlib.graph:

Traditional auto-layout tools like Graphviz or Mermaid act as black boxes: if one node lands slightly in the wrong spot, you cannot nudge it by 4 units without rewriting opaque rank hacks. Conversely, calculating every (x, y) coordinate manually becomes tedious for large DAGs and trees.
drawlib.graph gives you the best of both worlds via a clean 2-step workflow:
1. Step 1 (get_layout()): Declare nodes, edges, and clusters (LayerGraph, ArchitectureGraph, TreeGraph, RadialGraph, or GridGraph). get_layout() computes overlap-free node centers (layout[id].xy), cluster bounds (layout[cid].bottom_left), and orthogonal edge ports (edge.points) with zero rendering side effects.
2. Step 2 (offset() + Render): Optionally nudge any node via layout.offset("serve", dy=-4.0) (which automatically updates incident ports) or inspect/copy exact solved coordinates via print(layout), then render using full-power FlowDiagram, ArchitectureDiagram, or shapes primitives.

Drawlib — Illustration & Documentation as Code

Five Specialized Auto-Layout Graph Solvers

Overview of All Five Specialized Graph Solvers (drawlib.graph):

ArchitectureGraph (Top-Left): Two-level macro/micro container solver with 5-zone compass placement (pos="left" | "center" | "right" | "top" | "bottom") tailored for cloud VPCs, subnets, and microservice tiers.
LayerGraph (Top-Center): Sugiyama-style hierarchical DAG solver featuring cycle breaking, longest-path or explicit .tier() ranking, and barycenter edge-crossing minimization.
TreeGraph (Top-Right): Reingold-Tilford / Buchheim compact tree solver guaranteeing symmetrical parent centering and overlap-free sibling subtrees (TB or LR).
RadialGraph (Bottom-Left): Concentric hub-and-spoke solver (ring=0, 1, 2...) with angular sector allocation and layout.ring_radii for drawing orbital guide rings.
GridGraph (Bottom-Right): Uniform 2D (row, col) matrix solver supporting snake flows, .cluster_row() / .cluster_column() bands, and smart inter-cell channel routing.

Drawlib — Illustration & Documentation as Code

Interactive Frame Animations (APNG & WebP)

Motion as Code Across All Modules

Multi-Frame Engine: Declarative Animation(fps, loop) API
Progressive Reveal: draw_ratio on Lines, Charts & Diagrams
Interactive Stage: Live <canvas> (anim_trigger, anim_pause, A)
Static Export Ready: Auto-extracts clean frames for PDF & PPTX

anim = Animation(fps=2.0, loop=0)
for r in [0.4, 0.7, 1.0]:
    series.draw_ratio = r
    with anim.frame():
        chart.draw(xy=(10, 6))

Declarative Frame Animations Across Every Drawlib Module (drawlib.anim):

Unified Animation(fps, loop) Context Manager: Wrapping standard Drawlib calls inside with anim.frame(duration=...): compiles lossless APNG (.png) or Animated WebP (.webp) assets directly from Markdown code blocks.
First-Class Component Animation Controls: Every SmartArt, Diagram, and Chart supports .show (reserving spatial layout slots and axis scales without visual jumps) plus progressive .draw_ratio (0.0 → 1.0) for growing chart bars, sweeping lines, and revealing pipelines.
Interactive Presentation & Print Fallback: HTML slides decode APNG/WebP frames onto an interactive <canvas> supporting anim_trigger=auto|click, anim_pause=(...), and keyboard shortcut A, while PDF and PPTX exporters automatically extract clean static frames so both Frame 0 and the final completed state remain crisp and publication-ready.

Drawlib — Illustration & Documentation as Code

Five Built-In Project Archetypes

Drawlib provides five built-in project archetypes via uv run drawlib init project <type> <dir>, each tailored to a distinct engineering communication workflow while sharing the exact same Python illustration engine and drawlib.toml configuration model:

site: Multi-page documentation portals (docs_src/<lang>/ + navbar.md) that compile into responsive HTML websites with client-side full-text search, dark mode, and multi-locale switching—powering www.drawlib.com.
catalog (New in v0.3.5): Two-column API, schema, and rulebook reference sites (catalog_src/<lang>/, 1 Markdown = 1 HTML) that automatically extract # H1 categories and badged ## H2 entries with an instant / keyboard filter and zero navbar.md maintenance—powering www.drawlib.com/api.
doc: Linear multi-chapter specifications and whitepapers (doc_src/<lang>/) that compile into single-page HTML, A4 Vector PDF with --generate-index Cover/ToC pages, and native editable Microsoft Word (.docx).
slide: 16:9 widescreen presentation decks (slide_src/<lang>/) combining 1920×1080 ::: block visuals and ::: note speaker scripts into synchronized ?presenter=1 HTML, Vector PDF, and editable 960×540pt PowerPoint (.pptx).
images: Standalone Python batch illustration suites (images_src/*.py) outputting crisp SVG, PNG, WebP, and PDF assets for papers, READMEs, and CI pipelines.

Drawlib — Illustration & Documentation as Code

Web Publishing: Docs Site & API Catalog

type = "site" (Narrative Docs): Guided chapter navigation via navbar.md, full-text search, dark mode & i18n (www.drawlib.com).
type = "catalog" (API Reference): Zero-navbar.md 1 MD = 1 HTML dictionary extracting # H1 / badged ## H2 items with / instant filter (www.drawlib.com/api).

When publishing technical knowledge to the web, Drawlib offers two complementary website archetypes optimized for different reader journeys:

On the left, type = "site" powers guided narrative documentation like www.drawlib.com. Authors curate a deliberate learning path in navbar.md with numbered chapters, tutorials, full-text search, dark mode, and Prev/Next links.
On the right, type = "catalog" (introduced in Drawlib v0.3.5) powers high-density lookup portals like www.drawlib.com/api. Every Markdown file maps 1:1 to an HTML page with zero navbar.md maintenance—Drawlib automatically extracts # H1 categories and badged ## H2 entries ([CLASS], [FUNC], [GET], [POST]) into a sticky sidebar with an instant / keyboard filter, while keeping full support for inline Class, Sequence, and ER diagrams.

Drawlib — Illustration & Documentation as Code

Whitepapers: HTML, Vector PDF & MS Word

Linear Specs (`type = "doc"`)

Numbered Chapters: Merge 00_cover.md, 01_intro.md into one spec
Auto Cover & ToC: --generate-index builds cover & clickable index
Triple Export: Compile HTML, A4 Vector PDF, and editable .docx

# Build all 3 deliverables from doc_src/
uv run drawlib build html
uv run drawlib build pdf --generate-index
uv run drawlib build docx --generate-index

Drawlib — Illustration & Documentation as Code

16:9 Slide Stage, Presenter View & PPTX

Dual-Layer Slide Markdown: ::: block places crisp visuals on a 1920×1080 stage while ::: note stores speaker scripts in Git.
Live Sync & Office Export: Sync Audience Stage with ?presenter=1 Presenter View via BroadcastChannel, plus Vector PDF & .pptx.

This very presentation deck is built with type = "slide". Every slide file uses Drawlib's Dual-Layer Markdown syntax: ::: block positions headlines, concise bullets, and inline Python SVG diagrams onto a deterministic 1920×1080 widescreen stage, while ::: note captures the complete speaker script right inside the same Git-tracked file. At presentation time, pressing P (or opening ?presenter=1) launches a synchronized Presenter View window over browser BroadcastChannel, giving the speaker current and next slide previews, an elapsed timer, and scrollable ::: note talking points—plus instant L-key switching between English and Japanese. And when conference organizers or enterprise stakeholders request offline files, drawlib build pdf exports a razor-sharp 1920×1080 Vector PDF while drawlib build pptx generates a native editable 960×540pt Microsoft PowerPoint deck complete with speaker notes.

Drawlib — Illustration & Documentation as Code

Autonomous Multimodal Verification Loop

On-Demand Context: AI agents (Gemini, Claude Code, Cursor) query exact API specs via uv run drawlib rules show <topic>.
Visual Self-Correction: Agents inspect -g coordinate grid previews multimodally and fix overlaps before publishing.

Why do traditional diagramming tools fail with AI agents? Raw XML formats like .drawio or .pptx are opaque token walls, while static DSLs give agents zero visibility into rendered text collisions. Drawlib closes the loop in five deterministic steps:

drawlib rules show: Instead of stuffing thousands of lines into the system prompt, the agent loads only the specific SmartArt or Diagram guide it needs on demand.
Write Python / Markdown: The agent composes clean, typed Python code and ::: block coordinates.
drawlib show -g: Drawlib renders a headless PNG overlaid with explicit Cartesian (X, Y) coordinate rulers in under a second.
Multimodal Inspection: Vision-capable models inspect the actual rendered image for margin balance, text_size legibility, and clipping.
Self-Correct Coordinates: Whenever an overlap is spotted, the agent reads the exact coordinate delta off the -g grid and patches (x, y) before compiling the final verified artifact.

Drawlib — Illustration & Documentation as Code

Two-Tier Caching & Unified CLI

Fast feedback loops are essential for both interactive authoring and autonomous AI agents. Drawlib achieves sub-second incremental rebuilds through a Two-Tier Caching architecture:

Tier 1 — Package Asset Cache (drawlib cache list / download / clear): Downloads typography fonts, 34 cloud and Phosphor icon packs, and headless Chromium on demand into _cached_assets/, keeping the base pip / uv install lightweight while supporting air-gapped CI prefetching.
Tier 2 — Project Diagram Build Cache (.drawlib/cache.db): A content-addressed SQLite database keyed by the SHA-256 hash of each diagram's code, styles.py, utils.py, and output format. Unchanged diagrams resolve in milliseconds across HTML, PDF, DOCX, and PPTX builds, while --no-cache enforces clean verification in CI. Every stage runs through one consistent uv run drawlib CLI: init, rules, show -g, build, and serve --check for automated link and asset validation.

Drawlib — Illustration & Documentation as Code

Key Takeaways & Quickstart

Let us recap the four pillars that set Drawlib apart:

Pure Python & Git Native: Every illustration and document lives in clean, typed Python and Markdown files with shared styles.py design tokens and human-readable pull request diffs.
Rich High-Level Components: 18 SmartArts, 9 Charts, 6 Diagrams, 5 deterministic Graph layout solvers, and 34 icon suites let you express complex architectures without tedious box-and-line micromanagement.
5 Project Archetypes & Office Export: One compiler builds Web Docs (site), API Catalogs (catalog), Whitepapers (doc), 16:9 Slide Decks (slide), and Batch Asset Suites (images)—exporting HTML, Vector PDF, MS Word (.docx), and PowerPoint (.pptx).
Built for Autonomous AI Agents: 50+ drawlib rules topics, multimodal show -g coordinate grid verification, and sub-second .drawlib/cache.db SQLite caching turn AI agents into reliable visual authors. Getting started takes three commands: uv add drawlib, uv run drawlib init project slide my-deck, and uv run drawlib serve.

Thank You

Start Authoring Visuals & Docs as Code

Docs: https://www.drawlib.com/
API Catalog: https://www.drawlib.com/api/
Examples & GitHub: https://examples.drawlib.com/ · github.com/yuichi110/drawlib

Drawlib

Illustration & Documentation as Code

Drawlib at a Glance

Presentation Roadmap

Six Core Chapters

Why Visual Documentation Breaks Down

Illustration & Documentation as Code

Pure Python + Markdown

Tooling Landscape Comparison

One Git Repository, Every Output Format

Cartesian Canvas & Visual Grid (-g)

Predictable Math Geometry

43 Geometric Shapes & Smart Connectors

Multilingual Typography & Raster Assets

Universal Scripts & Dimage

34 Icon Suites & 4,500+ Vector Icons

8-Color Semantic Styles & Preset Themes

Process Pipelines, Lifecycles & Roadmaps

KPIs, Feature Cards, Pyramids & MindMaps

Tables, SourceCode, Calendars & GeoMap

Declarative Bar, Line & Area Charts

Pie, Radar, Scatter & Heatmap Charts

Engineering Roadmaps with GanttChart

Cloud Topology with ArchitectureDiagram

Workflows & Protocols: Flow and Sequence

Domain Modeling: Class, ER & State Diagrams

Declarative Graph Layout (drawlib.graph)

Hybrid Algorithmic + Manual Control

Five Specialized Auto-Layout Graph Solvers

Interactive Frame Animations (APNG & WebP)

Motion as Code Across All Modules

Five Built-In Project Archetypes

Web Publishing: Docs Site & API Catalog

Whitepapers: HTML, Vector PDF & MS Word

Linear Specs (type = "doc")

16:9 Slide Stage, Presenter View & PPTX

Autonomous Multimodal Verification Loop

Two-Tier Caching & Unified CLI

Key Takeaways & Quickstart

Thank You

Start Authoring Visuals & Docs as Code

Linear Specs (`type = "doc"`)