Editorial diagram design for Claude Code, Codex, GitHub Copilot, Cursor, Factory Droid, Qoder, and Pi. 45 diagram types. Self-contained HTML + SVG. No shadows. No Mermaid slop.
#!/usr/bin/env python3
"""Verify exploded axonometric diagrams against the geometry they declare.
Each part carries its model box (``data-rect``, ``data-z``, ``data-t``,
``data-level``) and the figure carries its drawing origin and gap. This
checker reprojects every part with iso(x, y, z) = [x - y, (x + y) / 2 - z]
and fails when the drawing and the declaration disagree:
- a silhouette vertex or corner arc off the projection of its declared box;
- a level that does not share one z, a bottom level off z = 0, unequal gaps,
or a gap under max(0.5 x top-face height, 3 x thickest non-container part);
- a leader that is not horizontal, does not start at its part's right
extreme, or crosses another part; labels outside one column, closer than
36px, or longer than two words;
- more than one focal part, a trace line that is not vertical and dashed, an
SVG or CSS transform anywhere in the figure, a part with two labels, or an
animated part whose lift is not its exploded z minus its closed z.
python3 scripts/verify-exploded.py --all
python3 scripts/verify-exploded.py skills/diagram-design/assets/example-exploded.html
"""
from __future__ import annotations
import argparse
import math
import re
import sys
from html.parser import HTMLParser
from pathlib import Path
ROOT = Path(__file__).resolve().parent.parent
ASSETS = ROOT / "skills/diagram-design/assets"
TOL = 0.05
LABEL_PITCH = 36
NUMBER = re.compile(r"-?\d+(?:\.\d+)?")
# Scan declaration boundaries before decoding escapes: escaped punctuation,
# strings, comments and nested custom-property blocks do not delimit CSS.
CSS_ESCAPE_RE = re.compile(r"\\(?:[0-9a-fA-F]{1,6}(?:\r\n|[ \t\r\n\f])?|[^\r\n\f])")
STYLE_TRANSFORM_RE = re.compile(
r"(?:-(?:webkit|moz|ms|o)-)?transform|translate|rotate|scale", re.IGNORECASE
)
def decode_css_escape(match: re.Match) -> str:
token = match.group()[1:]
if token[0] not in "0123456789abcdefABCDEF":
return token
value = int(token.strip(), 16)
return chr(value) if 0 < value <= 0x10ffff and not 0xd800 <= value <= 0xdfff else "\ufffd"
def style_declares_transform(style: str) -> bool:
nesting = []
property_text = []
in_value = False
index = 0
while index < len(style):
char = style[index]
if style.startswith("/*", index):
if not in_value:
property_text.append(" ")
close = style.find("*/", index + 2)
index = len(style) if close < 0 else close + 2
continue
if char == "\\":
escape = CSS_ESCAPE_RE.match(style, index)
if escape:
if not in_value:
property_text.append(escape.group())
index = escape.end()
continue
if char in "\"'":
quote = char
if not in_value:
property_text.append(char) # A string cannot be a property name.
index += 1
while index < len(style):
if style[index] == "\\":
index += 2
elif style[index] == quote:
index += 1
break
else:
index += 1
continue
if char in "({[":
nesting.append(char)
elif char in ")}]" and nesting:
if nesting[-1] == {")": "(", "}": "{", "]": "["}[char]:
nesting.pop()
elif not nesting and char == ":" and not in_value:
name = CSS_ESCAPE_RE.sub(decode_css_escape, "".join(property_text)).strip()
if STYLE_TRANSFORM_RE.fullmatch(name):
return True
in_value = True
elif not nesting and char == ";":
property_text = []
in_value = False
elif not in_value:
property_text.append(char)
index += 1
return False
class Element:
def __init__(self, tag, attrs, parent):
self.tag, self.attrs, self.parent = tag, attrs, parent
self.children: list[Element] = []
self.text = ""
def ancestors(self):
node = self.parent
while node is not None:
yield node
node = node.parent
def walk(self):
for child in self.children:
yield child
yield from child.walk()
def first_attributes(attrs):
result = {}
for name, value in attrs:
result.setdefault(name, value if value is not None else "")
return result
class Tree(HTMLParser):
VOID = {"path", "line", "circle", "rect", "polygon", "ellipse", "meta", "link", "br", "img", "input", "stop"}
def __init__(self):
super().__init__(convert_charrefs=True)
self.root = Element("#root", {}, None)
self.cur = self.root
def handle_starttag(self, tag, attrs):
el = Element(tag, first_attributes(attrs), self.cur)
self.cur.children.append(el)
if tag not in self.VOID:
self.cur = el
def handle_startendtag(self, tag, attrs):
el = Element(tag, first_attributes(attrs), self.cur)
self.cur.children.append(el)
def handle_endtag(self, tag):
node = self.cur
while node is not self.root and node.tag != tag:
node = node.parent
if node is not self.root:
self.cur = node.parent
def handle_data(self, data):
# A label's visible name includes inline tspan descendants, in source
# order, as well as text before and after them. <title> and <desc> are
# never drawn, so their text stays out of the label.
self.cur.text += data
if self.cur.tag in ("title", "desc"):
return
for ancestor in self.cur.ancestors():
if ancestor.tag in ("title", "desc"):
return
if ancestor.tag == "text":
ancestor.text += data
# ---------------------------------------------------------------- projection (independent of the builder)
def corners(r):
x0, y0, x1, y1, rad = r
return [(x1 - rad, y1 - rad), (x0 + rad, y1 - rad), (x0 + rad, y0 + rad), (x1 - rad, y0 + rad)]
def outline_point(origin, r, theta, z, k=None):
k = int(math.floor(theta / 90)) % 4 if k is None else k
cx, cy = corners(r)[k]
t = math.radians(theta)
x, y = cx + r[4] * math.cos(t), cy + r[4] * math.sin(t)
return (origin[0] + x - y, origin[1] + (x + y) / 2 - z)
def walk_points(origin, r, a, b, z):
"""Endpoints of each edge and quarter arc between outline angles a and b."""
pts, arcs = [], []
rising = b > a
th = a
step = 1 if rising else -1
while (b - th) * step > 1e-9:
nxt = min(b, (math.floor(th / 90) + 1) * 90) if rising else max(b, (math.ceil(th / 90) - 1) * 90)
k = int(math.floor((th + nxt) / 2 / 90)) % 4
pts.append(outline_point(origin, r, nxt, z, k))
arcs.append(r[4] > 0)
th = nxt
if (b - th) * step > 1e-9:
pts.append(outline_point(origin, r, th, z, int(math.floor((th + step) / 90)) % 4))
arcs.append(False)
return pts, arcs
def expected_silhouette(origin, r, z0, z1):
pts = [outline_point(origin, r, 135, z1)]
arcs = [False]
p, a = walk_points(origin, r, 135, 315, z1)
pts += p
arcs += a
pts.append(outline_point(origin, r, -45, z0))
arcs.append(False)
p, a = walk_points(origin, r, -45, 135, z0)
pts += p
arcs += a
return pts, arcs
def silhouette_poly(origin, r, z0, z1, n=24):
poly = [outline_point(origin, r, 135 + 180 * i / n, z1) for i in range(n + 1)]
poly += [outline_point(origin, r, -45 + 180 * i / n, z0) for i in range(n + 1)]
return poly
def parse_path(d):
"""Return (endpoints, is_arc, arcs as (rx, ry, rotation, large-arc, sweep)) for an absolute M/L/A/Z path."""
token_re = re.compile(r"[MLAZ]|[-+]?(?:\d*\.\d+|\d+\.?\d*)(?:[eE][-+]?\d+)?")
tokens = []
end = 0
for match in token_re.finditer(d):
if d[end:match.start()].strip(" \t\r\n,"):
raise ValueError(f"unsupported path token {d[end:match.start()]!r}")
tokens.append(match.group())
end = match.end()
if d[end:].strip(" \t\r\n,"):
raise ValueError(f"unsupported path token {d[end:]!r}")
def operand(index):
value = float(tokens[index])
if not math.isfinite(value):
raise ValueError("non-finite path operand")
return value
pts, arcs, radii = [], [], []
i = 0
while i < len(tokens):
cmd = tokens[i]
if cmd in ("M", "L"):
pts.append((operand(i + 1), operand(i + 2)))
arcs.append(False)
i += 3
elif cmd == "A":
if tokens[i + 4] not in {"0", "1"} or tokens[i + 5] not in {"0", "1"}:
raise ValueError("arc flags must be literal 0 or 1")
radii.append(tuple(operand(i + k) for k in range(1, 6)))
pts.append((operand(i + 6), operand(i + 7)))
arcs.append(True)
i += 8
elif cmd == "Z":
i += 1
else:
raise ValueError(f"unsupported path token {cmd!r}")
return pts, arcs, radii
def crosses(y, xa, xb, poly):
xs = []
for i in range(len(poly)):
(x1, y1), (x2, y2) = poly[i], poly[(i + 1) % len(poly)]
if (y1 - y) * (y2 - y) < 0:
xs.append(x1 + (y - y1) * (x2 - x1) / (y2 - y1))
xs.sort()
return any(xs[i] < xb and xs[i + 1] > xa for i in range(0, len(xs) - 1, 2))
def num(value, what, errors):
try:
return float(value)
except (TypeError, ValueError):
errors.append(f"{what} is not a number: {value!r}")
return None
# ---------------------------------------------------------------- checks
def verify_source(source: str, name: str) -> list[str]:
errors: list[str] = []
tree = Tree()
tree.feed(source)
roots = [el for el in tree.root.walk() if el.tag == "g" and "data-exploded" in el.attrs]
if len(roots) != 1:
return [f"{name}: expected one <g data-exploded>; found {len(roots)}"]
fig = roots[0]
origin_vals = NUMBER.findall(fig.attrs.get("data-origin", ""))
if len(origin_vals) != 2:
return [f"{name}: data-origin must be two numbers"]
origin = (float(origin_vals[0]), float(origin_vals[1]))
gap = num(fig.attrs.get("data-gap"), f"{name}: data-gap", errors)
if gap is None:
return errors
parts = []
for el in fig.walk():
if el.tag != "g" or "data-part" not in el.attrs:
continue
key = el.attrs["data-part"]
vals = NUMBER.findall(el.attrs.get("data-rect", ""))
if len(vals) != 5:
errors.append(f"{name}: part {key!r} data-rect must be x0 y0 x1 y1 r")
continue
rect = tuple(float(v) for v in vals)
z = num(el.attrs.get("data-z"), f"{name}: part {key!r} data-z", errors)
t = num(el.attrs.get("data-t"), f"{name}: part {key!r} data-t", errors)
level = num(el.attrs.get("data-level"), f"{name}: part {key!r} data-level", errors)
if None in (z, t, level):
continue
parts.append(dict(key=key, el=el, rect=rect, z=z, t=t, level=int(level),
name=el.attrs.get("data-name", ""), housing=el.attrs.get("data-kind") == "housing",
focal="data-focal" in el.attrs, closed=el.attrs.get("data-closed-z")))
if len(parts) < 2:
errors.append(f"{name}: an exploded view needs at least two parts; found {len(parts)}")
return errors
# 1. Every silhouette is the projection of its declared box.
for p in parts:
sil = next((c for c in p["el"].walk() if c.tag == "path" and c.attrs.get("data-role") == "silhouette"), None)
if sil is None:
errors.append(f"{name}: part {p['key']!r} has no data-role=silhouette path")
continue
want, want_arcs = expected_silhouette(origin, p["rect"], p["z"], p["z"] + p["t"])
try:
got, got_arcs, radii = parse_path(sil.attrs.get("d", ""))
except (ValueError, IndexError) as exc:
errors.append(f"{name}: part {p['key']!r} silhouette is unreadable ({exc})")
continue
if len(got) != len(want) or got_arcs != want_arcs:
errors.append(f"{name}: part {p['key']!r} silhouette has {len(got)} vertices; its box projects to {len(want)}")
continue
for i, (g, w) in enumerate(zip(got, want)):
if abs(g[0] - w[0]) > TOL or abs(g[1] - w[1]) > TOL:
errors.append(f"{name}: part {p['key']!r} silhouette vertex {i} is at {g}; iso() of its box puts it at ({w[0]:.2f}, {w[1]:.2f})")
break
r = p["rect"][4]
for rx, ry, rotation, large, sweep in radii:
if abs(rx - r * math.sqrt(2)) > TOL or abs(ry - r / math.sqrt(2)) > TOL:
errors.append(f"{name}: part {p['key']!r} corner arc {rx:g}x{ry:g} is not the 2:1 ellipse of radius {r:g} ({r * math.sqrt(2):.2f}x{r / math.sqrt(2):.2f})")
break
# Both silhouette walks run clockwise on screen through quarter corners, so every
# arc is unrotated, short, and sweeps positive. A flipped flag bends the corner
# inward while its endpoints and radii still match.
if rotation != 0 or large != 0 or sweep != 1:
errors.append(f"{name}: part {p['key']!r} corner arc flags are rotation {rotation:g}, large-arc {large:g}, sweep {sweep:g}; a projected corner is 0 0 1")
break
# 2. Levels, equal gaps, the gap floor, and the bottom staying put.
levels: dict[int, list[dict]] = {}
for p in parts:
levels.setdefault(p["level"], []).append(p)
order = sorted(levels)
if order != list(range(len(order))):
errors.append(f"{name}: levels must run 0..{len(order) - 1}; found {order}")
for k in order:
zs = {round(p["z"], 3) for p in levels[k]}
if len(zs) != 1:
errors.append(f"{name}: level {k} parts sit at different z {sorted(zs)}; a level explodes together")
if order and abs(levels[order[0]][0]["z"]) > TOL:
errors.append(f"{name}: the bottom level must stay at z = 0; found {levels[order[0]][0]['z']}")
for k0, k1 in zip(order, order[1:]):
top = levels[k0][0]["z"] + max(p["t"] for p in levels[k0])
actual = levels[k1][0]["z"] - top
if abs(actual - gap) > TOL:
errors.append(f"{name}: gap between levels {k0} and {k1} is {actual:g}; the figure declares {gap:g}, and gaps must be equal")
top_h = max((p["rect"][2] - p["rect"][0] + p["rect"][3] - p["rect"][1]) / 2 for p in parts)
solids = [p["t"] for p in parts if not p["housing"]] or [p["t"] for p in parts]
floor = max(0.5 * top_h, 3 * max(solids))
if gap + TOL < floor:
errors.append(f"{name}: gap {gap:g} is under max(0.5 x top-face height, 3 x thickness) = {floor:g}")
# 3. Labels: exactly one per part, one column, horizontal leaders from each part's right extreme.
labels = {}
part_names = {p["name"] for p in parts}
for el in fig.walk():
if el.tag == "g" and el.attrs.get("data-role") == "label":
name_el = next((c for c in el.walk() if c.tag == "text" and c.attrs.get("data-role") == "name"), None)
leader = next((c for c in el.walk() if c.tag == "line" and c.attrs.get("data-role") == "leader"), None)
if name_el is None or leader is None:
errors.append(f"{name}: a label group needs a data-role=name text and a data-role=leader line")
continue
text = name_el.text.strip()
if text in labels:
errors.append(f"{name}: part {text!r} has more than one label; each part gets exactly one")
continue
if text not in part_names:
errors.append(f"{name}: label {text!r} names no declared part")
continue
labels[text] = (name_el, leader)
polys = {p["key"]: silhouette_poly(origin, p["rect"], p["z"], p["z"] + p["t"]) for p in parts}
columns, anchor_ys = set(), []
for p in parts:
if p["name"] not in labels:
errors.append(f"{name}: part {p['key']!r} has no label named {p['name']!r}")
continue
name_el, leader = labels[p["name"]]
words = p["name"].split()
if len(words) > 2:
errors.append(f"{name}: label {p['name']!r} has {len(words)} words; keep labels to one or two")
x1, y1, x2, y2 = (float(leader.attrs.get(k, "nan")) for k in ("x1", "y1", "x2", "y2"))
if abs(y1 - y2) > TOL:
errors.append(f"{name}: leader for {p['name']!r} is not horizontal ({y1:g} to {y2:g})")
top_right = outline_point(origin, p["rect"], -45, p["z"] + p["t"])
bottom_right = outline_point(origin, p["rect"], -45, p["z"])
ax, ay = top_right[0], (top_right[1] + bottom_right[1]) / 2
if abs(y1 - ay) > TOL or abs(x1 - (ax + 6)) > TOL:
errors.append(f"{name}: leader for {p['name']!r} starts at ({x1:g}, {y1:g}); the part's right extreme is ({ax:.2f}, {ay:.2f})")
anchor_ys.append((ay, p["name"]))
columns.add(round(float(name_el.attrs.get("x", "nan")), 2))
for q in parts:
if q is not p and crosses(y1, x1, x2, polys[q["key"]]):
errors.append(f"{name}: leader for {p['name']!r} crosses part {q['key']!r}")
if len(columns) > 1:
errors.append(f"{name}: labels sit in {len(columns)} columns {sorted(columns)}; use one aligned column")
anchor_ys.sort()
for (ya, na), (yb, nb) in zip(anchor_ys, anchor_ys[1:]):
if yb - ya < LABEL_PITCH - TOL:
errors.append(f"{name}: labels {na!r} and {nb!r} are {yb - ya:.1f}px apart; the minimum is {LABEL_PITCH}")
# 4. One focal part at most.
focal = [p["key"] for p in parts if p["focal"]]
if len(focal) > 1:
errors.append(f"{name}: {len(focal)} focal parts {focal}; the accent goes on one")
# 5. Trace lines run straight up and are dashed.
for el in fig.walk():
if el.tag == "line" and el.attrs.get("data-role") == "trace":
if abs(float(el.attrs.get("x1", "nan")) - float(el.attrs.get("x2", "nan"))) > TOL:
errors.append(f"{name}: trace line is not vertical")
if not el.attrs.get("stroke-dasharray"):
errors.append(f"{name}: trace line must be dashed")
# 6. Geometry comes from coordinates alone: no SVG or CSS transform in the figure.
for el in [fig, *fig.walk()]:
if "transform" in el.attrs:
errors.append(f"{name}: <{el.tag}> carries transform={el.attrs['transform']!r}; position comes from projected coordinates")
style = el.attrs.get("style", "")
if style_declares_transform(style):
errors.append(f"{name}: <{el.tag}> carries style={style!r}; a CSS transform moves projected geometry")
# 7. Animated parts lift by exactly their explode distance.
for p in parts:
style = p["el"].attrs.get("style", "")
if "data-motion-item" in p["el"].attrs:
if p["closed"] is None:
errors.append(f"{name}: animated part {p['key']!r} needs data-closed-z")
continue
m = re.fullmatch(r"\s*--lift:\s*(-?\d+(?:\.\d+)?)px;?\s*", style)
if not m:
errors.append(f"{name}: animated part {p['key']!r} must carry only style=\"--lift:Npx\"; found {style!r}")
continue
want = p["z"] - float(p["closed"])
if abs(float(m.group(1)) - want) > TOL:
errors.append(f"{name}: part {p['key']!r} lifts {m.group(1)}px; z {p['z']:g} minus closed z {p['closed']} is {want:g}")
elif style:
errors.append(f"{name}: static part {p['key']!r} carries a style attribute; position comes from geometry")
return errors
def verify(path: Path) -> list[str]:
try:
display = path.resolve().relative_to(ROOT).as_posix()
except ValueError:
display = str(path)
return verify_source(path.read_text(encoding="utf-8"), display)
def main() -> int:
parser = argparse.ArgumentParser(description="Verify exploded axonometric geometry.")
parser.add_argument("files", nargs="*", type=Path)
parser.add_argument("--all", action="store_true", help="check every shipped example-exploded*.html")
args = parser.parse_args()
files = sorted(ASSETS.glob("example-exploded*.html")) if args.all else args.files
if not files:
parser.error("name files or pass --all")
errors = []
for path in files:
errors += verify(path)
if errors:
print(f"FAIL exploded axonometric: {len(errors)} problem(s)")
for error in errors:
print(f" - {error}")
return 1
print(f"OK exploded axonometric: {len(files)} file(s) match their declared geometry")
return 0
if __name__ == "__main__":
sys.exit(main())