drawspec specification

Date: 2026-08-11 Ticket / PR: #1 Author: drawspec

Language models produce diagrams by emitting SVG with absolute x/y coordinates, and they fail at the same things every time. In the 87-diagram evidence corpus (corpus/), 63 drew a complaint from a human reviewer, and every complaint was about placement, not content: arrows with a head but no shaft, text escaping its box, lines stopping short of the shape they point at, a different font size in every element. These failures cannot be reviewed away — a cheap mechanical check over finished SVG catches 17 of the 63 and misses 46. Nor can they be prompted away, because the author cannot see the result. They have to be made unrepresentable: the author describes what the diagram means, and every decision that requires seeing the output is taken by the tool. drawspec is that tool — a Python library and CLI that takes a declarative document and emits SVG clean enough to drop into whatever surrounds it, inheriting the host document's colour where that is wanted and surviving greyscale printing everywhere.

Output targets. Markdown is the sharpest constraint, not the only one: it forces inline embedding, where a global <style> leaks, ids collide between two diagrams on one page, and a hardcoded colour breaks dark mode. Meeting that bar covers HTML embedding for free. But standalone consumption — an .svg file linked rather than pasted, or converted to PDF — has the opposite requirement: currentColor has nothing to inherit from and resolves to a converter default, so a standalone file must carry explicit colour and its own dimensions. drawspec therefore emits under an embedding profile:

Both profiles share every other invariant — no global <style>, namespaced ids, no embedded fonts, no information carried by colour alone. The profile changes what the SVG assumes about its surroundings, nothing else.

Success criteria (measurable) — each seeds a task Gate in the plan:

• [ ] unrepresentable_failure_families == 11 — for each of the 11 categorized failure families in docs/brief.md, a test demonstrates that no valid input document can produce it. Judged per family: either the input schema has no field that expresses it, or a layout invariant excludes it.
• [ ] embedding_safety_violations == 0 over every generated fixture in both profiles — no <style> element, no id that is not prefixed with the document's unique namespace, no embedded or referenced external font, no fill/stroke literal outside the values the active theme declares, and for standalone no unresolved currentColor. Mechanically checked by the emitter's own validator.
• [ ] greyscale_ambiguous_role_pairs == 0 — for a theme to load, every pair of semantic roles must differ in at least one non-colour channel (shape, dash pattern, stroke weight, fill pattern) or by a luminance delta >= 0.25 in relative luminance. Checked once per theme at load time.
• [ ] text_overflow_count == 0 over the regression fixture set — no text run's measured advance width exceeds its container's usable width, and no text block's measured height exceeds its container's usable height.
• [ ] system_dependencies == 0 — pip install drawspec followed by drawspec render succeeds in a container with no non-Python binaries installed beyond CPython itself.
• [ ] text_measurement_error_ratio <= 0.02 — for a font with published metrics, drawspec's measured advance width for a reference string set is within 2% of the value computed from the font's own hmtx/kern tables by an independent reader.
• [ ] nondeterministic_reruns == 0 — rendering the same document twice with the same theme produces byte-identical SVG.
• [ ] line_coverage >= 0.85.
• [ ] A document whose content cannot fit at the theme's minimum legible size fails loudly rather than shrinking type or overflowing. Judged by a test asserting a specific exception, not by a number.

drawspec is a greenfield library, so the table maps its own subsystems rather than existing services. "Needs changes" reads as "must be built".

Impact dimensions.

• Data: none — the tool is a pure function from document to SVG. No storage.
• API contract: the input schema is the contract, and it is the thing most expensive to change later, because documents written against it live in the consumer's repository. Versioned from v1 with an explicit version field. High.
• Performance: irrelevant at corpus scale (median 4 nodes, max 17). A render should be milliseconds. Not a design constraint. Low.
• User-facing: the diagrams are the product for the consumer's readers. Regressions are visible. High.
• Operational: adding a system binary dependency would push an install burden onto every consumer and every CI job. Medium, and it is the reason Option C below is not recommended.
• Risk of inaction: hand-written SVG keeps producing a ~72% complaint rate (63 of 87), with review cost borne by a human on every diagram, forever.

All consulted 2026-08-11. The question is not "does it draw well" but the brief's two acceptance tests: (1) does it emit SVG safe to paste inline into Markdown — no global <style>, no colliding ids, no embedded fonts, colour inherited, greyscale-safe; and (2) can it fix the three worst corpus diagrams.

What the survey settles.

1. No candidate passes acceptance test 1. Every tool that renders, renders to its own taste: global <style>, its own palette, its own ids, sometimes its own fonts. Post-processing another tool's SVG into inline-safe SVG is a permanent tax paid on every release of that tool. So drawspec owns the renderer regardless of which option is chosen. This is not a decision; it is a finding.
2. The useful candidates are coordinate oracles, not renderers. Graphviz (-Tplain), ELK and grandalf all hand back positions and let the caller draw. That is exactly the seam drawspec needs, and it makes the layout engine a swappable component rather than an architectural commitment.
3. The dependency question the brief left open has an answer. pip install graphviz installs bindings only; the dot executable is a separate system install. For a library whose whole point is to be called from another Python project's build, that pushes an out-of-band binary install onto every consumer and every CI job. ELK is worse: a JVM or a Node process.
4. The corpus is small enough that this matters more than engine power. Median 4 boxes, maximum 17. Graphviz's and ELK's real value is on graphs two orders of magnitude larger. At this scale a pure-Python layered layout is adequate, and adequacy with no system dependency beats excellence with one.

• Description: Pick D2 or Graphviz, write the declarative format as a thin transpiler to its input language, and post-process the emitted SVG into inline-safe form — strip <style>, rewrite ids, replace colours with currentColor, drop font declarations.
• Scope: A transpiler, an SVG rewriter, a theme mapped onto the upstream tool's styling options. No layout, routing, templates or measurement of our own.
• Effort: Small to start, Medium and rising to maintain.
• Tradeoffs: Fastest to a first diagram, and the brief explicitly counts this as a success if it works. But post-processing is structurally fragile — it is pattern-matching another project's output, and it breaks on their releases. Worse, it does not deliver the core promise: text still is not measured by us, so box sizing stays the upstream tool's decision, and the "text does not fit" family is only usually fixed rather than unrepresentable. Pyramids, concentric circles and axis charts are not expressible at all — 3 of 9 types unserved. And it inherits a system binary.
• Compatibility: Consumers install a Go or C binary.

• Description: drawspec owns the input schema, text measurement, theme, routing, templates, charts and SVG emission. Graph layout sits behind a narrow LayoutEngine protocol — nodes with measured sizes in, coordinates out — with a pure-Python implementation as the default. Additional engines (Graphviz via -Tplain, ELK via a subprocess) become optional extras for anyone who has them and wants them on larger graphs.
• Scope: All of src/drawspec/. The engine boundary is one small protocol, making the choice of engine reversible.
• Effort: Large — but concentrated where the brief says the real work is (style layer, measurement, non-graph shapes), not in reimplementing layout research.
• Tradeoffs: Most work up front. In exchange: no system dependency, so pip install drawspec is the whole install story; total control of the SVG, so acceptance test 1 is satisfied by construction rather than by rewriting; and all three rendering families served by one theme and one measurement core. The risk is layout quality — mitigated by the graph sizes actually in evidence, and by the escape hatch of a Graphviz engine for anyone who needs it. Whether the default engine wraps grandalf (EPL-1.0 arm, ~600 lines of Sugiyama, lightly maintained) or implements layered layout directly is a decision the protocol defers; the prototype should answer it.
• Compatibility: Pure Python, 3.12+. One pure-Python runtime dependency for font parsing (fonttools).

• Description: As Option B, but the layout engine is Graphviz driven via -Tplain, with no pure-Python fallback.
• Scope: Same as B minus the layout implementation, plus a subprocess boundary and its error handling.
• Effort: Medium.
• Tradeoffs: Removes the layout work and gets a battle-tested engine for free. But it makes a C binary a hard install requirement for a Python library, in exchange for capability the corpus does not need; it introduces a subprocess with version-dependent output to parse; and it makes the system_dependencies == 0 success criterion unachievable. Graphviz's orthogonal routing is also not good enough to own the arrow failure families, so the routing work does not actually go away.
• Compatibility: Consumers install Graphviz.

Recommended option: B — own the renderer, pluggable pure-Python layout.

The survey converts the brief's opening hypothesis ("do not write a layout engine, wrap one") into something more precise. The half that survives contact with the evidence is: do not write a renderer around someone else's opinions — and the answer there is the opposite of wrapping, because every candidate's SVG fails the inline-Markdown test and post-processing it is a permanent tax. The half that does not survive is the assumption that wrapping a layout engine is cheap: at median 4 and maximum 17 nodes, the engine's power is not the binding constraint, while its install cost is charged to every consumer forever. Keeping the engine behind a one-method protocol gets the benefit of the hypothesis (we can drop Graphviz or ELK in later, and should, if the default proves inadequate) without paying its cost on day one.

Three consequences worth stating explicitly, because they shape the plan:

• Three rendering families, one core. Graph-shaped diagrams (flow, tree, cycle) need the layout engine. Grid-shaped ones (stack, timeline, column comparison) and parametric shapes (pyramid, concentric circles) need geometry and text fitting, not graph theory. Axis charts are a third family again. All three share exactly two things: the theme and text measurement. Nothing else should be shared, and no chart library (matplotlib included) can be used for the third, because their SVG fails acceptance test 1 more badly than the diagram tools do.
• Text measurement is the critical path. It gates box sizing, pyramid fitting and chart labels, and it must work for a font drawspec has never seen — read from the font file with fonttools, cached, never a hardcoded table. The known-hard part is that the rendered font may not be the measured font, since the SVG inherits the page's stack; the design must carry an explicit safety margin and never rely on a tight fit.
• The failure families are the acceptance suite. For each of the 11, the plan should name the structural reason it cannot be expressed, and a test that demonstrates it.

Immediate next action: run design to turn this into status/plan.md — the input schema first, since it is the contract everything else reads and the most expensive thing to change later, then text measurement, then the emitter, then the three rendering families in that order.

Decisions taken (2026-08-11):

• [x] Font resolution — replace and warn. When the theme names a font that is not resolvable, drawspec substitutes a metric-compatible fallback, measures against the substitute, and emits a warning naming both fonts. It never fails on this alone and never substitutes silently. The warning must reach the CLI's stderr and the library's warnings channel, so a build can be configured to treat it as an error.
• [x] Sizing input — width binding, height advisory. The document may carry a width, a height, or both. Width is always binding: content is laid out to fit it, and failing to fit at the theme's minimum legible size is an error. Height is advisory by default — the canvas grows past it rather than compressing — and becomes binding only when the author marks it so, at which point overflow is an error like width.
• [x] Theme format — TOML. A theme is a TOML file so a consumer can version and diff it without importing drawspec. The loader parses it into a frozen dataclass; that dataclass is also constructible directly for programmatic use, but TOML is the documented surface.
• [x] Default layout engine — deferred behind the protocol. Whether the default engine wraps grandalf (EPL-1.0 arm, ~600 lines of Sugiyama, v0.8, lightly maintained) or implements layered layout directly is left open deliberately. The LayoutEngine protocol is the commitment; the implementation behind it is not. The first prototype of the three worst corpus diagrams settles it, and the plan should carry a task for that comparison before a task for the implementation.

Open questions:

• [ ] Diagram titles: the consumer's style rules leave "Figure 1"-style titles undecided. Proposed: a theme switch, default off, so the decision stays with the consumer and costs nothing to change.
• [ ] Metric-compatible fallback set: "replace and warn" needs a defensible substitution table (which fallback for a named serif / sans / mono, and on what basis). Whether drawspec bundles a font for this or maps onto the host's fonts is a packaging decision for the plan.

Sections 5–6 (contracts, risks) are appended by design.

The tool has no network surface and no database. Its contracts are four: the input document, the theme file, the public Python API, and the CLI. The first is by far the most expensive to change, because documents written against it live in the consumer's repository.

A document is JSON (or any format that parses to the same mapping). It carries an explicit version, and a kind that selects both the rendering family and which further fields are legal.

{
  "version": 1,
  "kind": "flow",
  "title": "Request validation",
  "description": "An incoming request is validated, then either accepted for processing or rejected with a reason.",
  "width": 640,
  "nodes": [
    {"id": "in",  "text": "Request arrives",        "role": "start"},
    {"id": "chk", "text": "Is the payload valid?",  "role": "decision"},
    {"id": "ok",  "text": "Queue for processing",   "role": "step"},
    {"id": "no",  "text": "Reject with a reason",   "role": "terminal"}
  ],
  "edges": [
    {"from": "in",  "to": "chk"},
    {"from": "chk", "to": "ok", "label": "yes"},
    {"from": "chk", "to": "no", "label": "no"},
    {"from": "no",  "to": "in", "role": "link"}
  ]
}

That last edge is a plain connector rather than a directed step: the author picks the semantic role link, and the theme decides it draws as a line with no head. See §5.2.

What the author may write. version, kind, title, description, width, height (with an optional height_binding flag), theme, and the per-kind payload: nodes/edges/groups for graph kinds, levels for pyramid, rings for rings, items for stack/timeline/columns, axes/series for chart. On a node: id, text, role, optional note. On an edge: from, to, optional label, optional role naming a theme-declared edge role (flow by default; link for a plain undirected connector — see §5.2).

What the author may not write — and the schema rejects rather than ignores. Because the schema sets additionalProperties: false throughout, an author who writes any of these gets a validation error naming the field, not a silently discarded key. That error message is the teaching surface for a model authoring blind:

Both role fields draw from closed vocabularies the theme defines — node roles (start, step, decision, terminal, emphasis, note, group) and edge roles (flow, link, exchange, weak, owns) — so a role the theme does not declare is a validation error too. Text may carry inline spans — `code` for the monospace role and **bold** for the emphasis role — because those are semantic, not typographic.

Versioning. version is required and validated. v1 is frozen once the first consumer document exists; additive fields ship as v1 minor changes with defaults, and anything that changes the meaning of an existing field ships as v2 with both readable in parallel for at least one release.

version = 1
name = "example"

[canvas]
width = 640
min_legible_size = 9.0

[font]
sans = ["Source Sans 3", "DejaVu Sans", "sans-serif"]
mono = ["Source Code Pro", "DejaVu Sans Mono", "monospace"]
serif = ["Source Serif 4", "DejaVu Serif", "serif"]
default = "sans"

[scale]
title = 15.0
heading = 13.0
body = 11.0
label = 10.0

# How far the whole type scale may stretch to make content fit. One factor is
# applied to every level at once — see "Elastic fit" below.
[fit]
scale_min = 0.85
scale_max = 1.0

[box]
padding = [10.0, 12.0, 10.0, 12.0]
line_height = 1.35
corner_radius = 4.0

[edge]
stroke_width = 1.5
min_shaft_length = 16.0
head_length = 6.0

# Node roles: shape and line treatment per semantic role.
[role.step]
shape = "rect"
stroke = "currentColor"
dash = "none"

[role.decision]
shape = "diamond"
stroke = "currentColor"
dash = "none"

[role.note]
shape = "rect"
stroke = "currentColor"
dash = "3 2"
stroke_width = 1.0

# Edge roles: head, tail and line treatment per semantic role. This is where a
# connector that is *not* an arrow lives.
[edge_role.flow]
head = "arrow"
tail = "none"
dash = "none"

[edge_role.link]
head = "none"          # a plain line, no head at all
tail = "none"
dash = "none"

[edge_role.exchange]
head = "arrow"
tail = "arrow"         # bidirectional
dash = "none"

[edge_role.weak]
head = "open"          # an open V rather than a filled triangle
tail = "none"
dash = "4 3"

[edge_role.owns]
head = "diamond"
tail = "none"
dash = "none"

A theme is rejected at load time if any two roles are distinguishable only by colour — see the greyscale_ambiguous_role_pairs criterion in §1. Colour is optional throughout; currentColor is the default and the documented norm.

Edge roles are how "no arrow, just a line" is said. The author names a semantic role — link, weak, owns — and the theme decides whether that means a filled triangle, an open V, a diamond, or no head at all, and whether the line is solid or dashed. The author never writes arrow_head = "triangle", because head geometry is a typographic decision and belongs with the other decisions taken away from them; but they can say that two things are merely associated rather than one flowing into the other, because that is meaning. The head vocabulary is closed (arrow, open, diamond, circle, bar, none) and lives in the theme, so a document stays readable when the theme changes.

Elastic fit. [fit] declares how far the type scale may stretch to make a document fit its width. drawspec computes the largest factor in [scale_min, scale_max] at which the content fits, and applies that one factor to every level at once — title, heading, body and label together. This is deliberate: scaling levels independently would reintroduce the "mixed type sizes in one drawing" failure (51 of 87 in the corpus), whereas a uniform factor preserves the hierarchy exactly and keeps one size per level. If the content still does not fit at scale_min, or if scale_min × body falls below canvas.min_legible_size, that is a FitError — the tool says restructure the diagram, it does not keep shrinking.

scale_max defaults to 1.0, meaning drawspec will shrink to fit but never grow. Growing is available (scale_max > 1.0) but is opt-in, because type size being comparable across diagrams is the reason the theme fixes a canvas width in the first place; a theme that lets small diagrams inflate has traded that away and should do so knowingly.

from drawspec import render, render_document, load_theme, Theme

svg: str = render(
    document: Mapping[str, Any],
    theme: Theme | str | Path | None = None,
    profile: Literal["inline", "standalone"] = "inline",
) -> str

• Pure function: same document plus same theme yields byte-identical SVG.
• Raises DocumentError (schema violation, naming the offending field), ThemeError (malformed or greyscale-ambiguous theme), FitError (content cannot fit at the theme's minimum legible size), LayoutError (the engine could not produce a valid arrangement).
• Emits FontSubstitutionWarning through warnings when a named font is not resolvable, naming the requested and substituted families, so a consumer can promote it with warnings.simplefilter("error", FontSubstitutionWarning).

--width/--height override the document's own values, so a build can render one document at several widths without editing it. --profile selects the embedding profile from §1.

Yes, there is a real schema, and it validates like HTML's does. The document format is defined by a published JSON Schema, not by prose. Three consequences worth stating, because this is the main affordance for an author — human or model — working without seeing the output:

• drawspec validate is the validator, and it reports violations by JSON pointer (/nodes/2/font_size), so a failure names the exact location and the exact field, the way an HTML validator names a line and an attribute.
• The schema is a versioned, addressable artefact with a stable $id, committed to the repository and shipped in the package. A document that carries "$schema": "…/drawspec-v1.schema.json" gets completion and inline error reporting in any editor with JSON Schema support — the author is told font_size is not allowed while typing it, rather than after a render.
• additionalProperties: false makes the schema teach. Because a forbidden field is an error rather than a silently ignored key, the schema is not only a description of what is legal but an active statement of what the author must not decide. That is the point of §5.1's rejection table.

The output has a validator too, but a different one: the emitter's embedding-safety check in §5.5, which enforces the invariants on the SVG it produces rather than on the input.

The Scene seam is the load-bearing one: every rendering family converges on one primitive list, so acceptance test 1 is satisfied in exactly one file rather than four — and adding an embedding profile, or a fifth family, does not multiply that work.

None. drawspec has no database and no migrations; it is a pure function from document to string. The only files it reads are the document, the theme, and font files it does not modify.

The scope discipline above — nine kinds, no feature nobody asked for, one corpus as the acceptance suite — is a shipping tactic, not the ambition. It exists because the reliable way to never finish a generic tool is to start generic.

What the project is actually for:

A tool useful to most people with different needs, while keeping its central goal: that a human or a language model can call it with a declarative input and get correct, beautiful output.

Three things follow, and they shape decisions taken now even though the features they enable are not v1:

• Nothing consumer-specific goes in, ever. The theme is the boundary, and the fact that a real consumer's entire style guide reduces to a theme file (docs/theme-requirements.md) is the standing proof. Any requirement that cannot be expressed as theme configuration is a design smell to be fixed, not a special case to be added.
• Extension points are chosen now, populated later. The closed vocabularies (node roles, edge roles, kinds) and the two seams (Scene, LayoutEngine) are picked so that a tenth kind, a sixth head shape or a different layout engine is an addition rather than a redesign. That is what "generic later" costs today: a few interfaces, not a few features.
• "Correct" is mechanically checkable; "beautiful" is not, quite. The success criteria in §1 cover correctness in full. Beauty is carried by the theme and judged by eye — which is why themes are data a consumer can iterate on without touching the tool, rather than opinions compiled into it.

The rule that keeps both true at once: build it generic, drive it with the corpus. Generality is bought through interface design, which is cheap now; features are bought through evidence, which arrives later.