Archscribe

Archscribe

Turn an article, system description, process, or reference image into a polished hand-drawn diagram. The default browser renderer can produce PNG, GIF, MP4, SVG, editable Excalidraw, and interactive HTML.

1. Check the environment

Run once per session:

python -X utf8 -c "import PIL, svg.path"
python -X utf8 -c "from playwright.sync_api import sync_playwright"
python -X utf8 scripts/doctor.py

• Missing base packages: python -m pip install -r requirements.txt
• Missing Playwright: python -m pip install -r requirements-browser.txt && python -m playwright install chromium
• Missing ffmpeg: MP4 is skipped; other browser formats still work.
• Chromium unavailable: use --renderer pillow. Pillow supports PNG, GIF, and Excalidraw with the classic flow animation.

Bundled fonts, icons, and rough.js keep the main visual system portable. Chromium, ffmpeg, and rare CJK fallback fonts remain environment dependencies.

2. Pick a layout

Decision rule:

• Whole system with multiple regions → panorama
• Parallel categories, variants, roles, or a comparison ("the N types of X") → swimlane (each lane gets a tinted band, a darker title column with optional subtitle such as "Triggered by: ...", and right-to-left in-lane connections automatically drop into a dashed loop channel under the cards)
• Anything with its own topology: linear stages, forks/joins, multiple distinct loops → graph (declare nodes + edges; kind: "loop" edges become dashed return channels that fire after the forward wave). Long rightward graphs auto-stack downward to prevent clipped sides and top-heavy layouts.

3. Write and validate the spec

Start from assets/default-spec.json or a file under assets/examples/. The complete field reference is references/spec-format.md.

Keep titles short, use the user's language, and move detail into bodies, notes, or an interactive HTML sidebar.

python -X utf8 scripts/render_animated_diagram.py --spec spec.json --outdir out --validate-only

Fix every error. Warnings identify long text, unknown icons, ignored fields, content that exceeds a layout's capacity, graph auto-stacking, or ignored graph canvas width/height.

4. Choose a visual theme

Two styles, both first-class:

• default: black-canvas neon hand drawing — glowing beams, grain, vignette. The brand hero look.
• paper: light warm-white paper (DailyDoseOfDS-style) — sage/periwinkle band tints, near-black ink, white cards with colored strokes; the flow animation becomes small solid dots traveling the arrows instead of neon beams.

Styles control the full palette and finish. Use --style to override the spec. Any other style name fails validation.

5. Choose animation

• flow: continuous data movement; safe default
• draw: whiteboard construction
• relay: one connection at a time
• trace: follow a request path
• chapter: staged explanatory build-up
• failure-recovery: failure/retry-oriented narrative timing

The last three use deterministic narrative choreography and longer minimum timelines. The browser renderer is required for every preset except classic Pillow flow.

6. Render and verify

First render a PNG for layout review:

python -X utf8 scripts/render_animated_diagram.py --spec spec.json --outdir out --basename diagram --formats png --check

Then render the publishing set:

python -X utf8 scripts/render_animated_diagram.py --spec spec.json --outdir out --basename diagram --formats gif,mp4,png,excalidraw,svg,html --verify --check --strict-formats

--formats is exact: only requested, supported files are emitted. Unknown formats fail. Use --strict-formats for publishing so missing MP4/SVG/HTML fails instead of silently falling back. --check must return "ok": true.

Visually inspect the PNG for overlap, crossing connectors, cramped labels, weak hierarchy, clipped edges, and empty-space imbalance. Shorten copy or switch layout before reducing text below a readable size.