teamai-test/.teamai/skills/common/diagram-design/references/output-spec.md

Draw.io import output spec — format × size × detail × audience

Four dials decide what an imported diagram becomes. Set them before redrawing — they change the deliverable, layout, type ramp, node count, and wording, so retrofitting them afterwards means redrawing.

Dial	Question it answers	Default
Format	Where does this file land?	html
Size	How big is the canvas, and how far away is the reader?	doc-inline
Detail level	Reproduce every element, or compress it?	balanced
Audience	How technical should the wording be?	mixed

Infer choices that are clear from the request (for example, "for my deck" implies a slide preset). Ask one concise question for anything material that remains ambiguous. If the user does not care, use the defaults above and say which ones you used.

---

1. Format

Format	Deliverable	Keeps	Drops
html	self-contained .html (default)	header, diagram, summary cards, footer, live fonts	nothing
svg	.svg next to the source	the <svg> node, vector text	editorial wrapper; fonts substitute in offline tools
png	.png at device_scale_factor	pixels exactly as the browser renders them	vector editability
html+png	both	—	—

Always generate the HTML first — svg and png are produced from it via export.md. Never hand-author an SVG file directly; the HTML is the source of truth and the only artifact the taste gate (SKILL.md §9) is written against.

Pick by destination:

Destination	Format	Size preset
Blog post, README, docs site	html (embed) or png	doc-inline
Keynote / PowerPoint / Google Slides	png @2	slide-16x9
Figma / Illustrator / further editing	svg	fit
X / LinkedIn / OG link card	png @2	social-og
Printed handout, PDF deck	png @3	print-a4-landscape
Confluence / Notion / internal wiki	png @2	doc-wide

---

2. Size

The preset sets the SVG viewBox. Every value below is divisible by 4, so the grid rule in SKILL.md §7 still holds.

Preset	viewBox	Aspect	PNG @2	Type ramp	Use
doc-inline (default)	0 0 960 600	8:5	1920×1200	standard	Body-width diagram in a post or README
doc-wide	0 0 1280 720	16:9	2560×1440	standard	Full-width docs, wiki pages
slide-16x9	0 0 1280 720	16:9	2560×1440	presentation	Deck slide, projected
slide-4x3	0 0 1024 768	4:3	2048×1536	presentation	Legacy deck templates
social-og	0 0 1200 632	~1.9:1	2400×1264	presentation	Link preview card
social-square	0 0 1080 1080	1:1	2160×2160	presentation	Feed post, carousel
print-a4-landscape	0 0 1120 792	~1.41:1	@3 → 3360×2376	print	A4 landscape, ~10mm margins at 96dpi
print-letter-landscape	0 0 1056 816	~1.29:1	@3 → 3168×2448	print	US Letter landscape
fit	derived from content	any	@2	standard	Vector hand-off; no fixed frame

Deriving fit

Round the content bounding box up to the next multiple of 4, then add the fixed chrome: 40px outer margin on every side, plus 60px at the bottom for the legend strip. Never let the content touch the viewBox edge.

Type ramp per size class

Node names shrink relative to the canvas as it grows — resist that. Scale the ramp with the preset so a projected slide stays readable from the back row.

Role	standard	presentation	print
Title (Instrument Serif)	28	40	32
Node name (Geist 600)	12	16	12
Sublabel (Geist Mono)	9	12	9
Arrow label (Geist Mono)	8	12	8
Eyebrow / tag (Geist Mono)	8	8	8
Node box min height	48	64	48
Min gap between nodes	24	40	24

Presentation ramp implies fewer nodes — 16px names in 64px boxes eat the canvas. If a slide-16x9 layout won't fit, that's the size dial telling you the detail dial is set too high; drop a level rather than shrinking the type.

Safe areas

• All presets: 40px outer margin; legend strip is the bottom 60px and nothing else lives there.
• social-og: keep the outer 64px clear on every side — link-card crops are unpredictable across platforms.
• slide-*: keep the bottom 80px clear if the deck template has a footer bar; ask if unsure.

---

3. Detail level

How much of the source survives. This is a count dial — it governs how many elements make it through, not how they're worded (that's §4).

Level	Nodes	Edges	Sublabels	What survives
faithful (詳細)	≤24, zoned	≤32	every port, protocol, version	Every distinct component in the source. Only exact duplicates merge.
balanced (default)	≤12	≤16	technical sublabel on ≤4 nodes	Components that carry the story; leaf clusters collapse to one node each.
simplified (簡略)	≤7	≤9	none	Capabilities and their sequence. Infrastructure disappears.

balanced and simplified sit inside the standard complexity budget (SKILL.md §7). faithful deliberately exceeds it — that's the trade, and it comes with conditions:

1. Zoning is mandatory. Above 9 nodes, every node belongs to a labeled zone (2–4 zones, hairline-bordered, paper-2 fill, mono uppercase zone label at top-left). An unzoned 20-node diagram is a wiring diagram, not a schematic.
2. Connector rules don't relax. SKILL.md §6 rules 1–5 still apply at 24 nodes. If you can't route it without overlaps, you're over the real ceiling — split.
3. Above 24 nodes, split. Produce an overview (zones as nodes, balanced grammar) plus one detail diagram per zone. Name them <base>-overview.html, <base>-<zone>.html. Never ship a 40-node single canvas.
4. Accent stays at 2. More nodes never buys more focal elements.

Degrade ladder

When the source has more than the level allows, cut in this order and stop as soon as you're under budget. Never cut ad hoc.

1. Decorative cells — sticky notes, free-floating text, title blocks, watermarks, the source's own legend. (Notes worth keeping become annotation callouts — max 2, see primitive-annotation.md.)
2. Exact duplicates — N identical workers/replicas/shards become one node labeled Worker ×N.
3. Leaf clusters — a container whose children are all leaves collapses to the container: Core Services replaces its three boxes. The extractor lists these under collapsible groups.
4. Degree-1 sinks that don't change the story — a monitoring hook, a log bucket, an archive tier.
5. Cross-cutting infrastructure — logging, metrics, secrets, CI. At simplified these go without asking; at balanced keep at most one, and only if the diagram is about it.
6. Still over? Split into overview + detail. Splitting beats shrinking.

Anything cut in steps 2–6 goes in the fidelity ledger (§5). Step 1 doesn't need reporting.

---

4. Audience level

Independent of the detail dial: the same 12 nodes get named differently for a platform team than for a steering committee. Detail sets how many; audience sets what they're called.

Audience	Node names	Sublabels	Edge labels	Never
engineer	exact service / component names	protocol, port, version, image tag	POST /v2/orders, SQL, gRPC	Vague verbs like "connects to"
mixed (default)	component names, expanded acronyms	technology only where it changes a decision	plain verbs — verifies, writes, notifies	Ports, versions, internal codenames
executive	capabilities and outcomes	none	business verbs — approves, pays out	Vendor names, infrastructure, protocols

Worked example — the same node through all three:

Audience	Node name	Sublabel
engineer	Auth Service	JWT · RS256 · :8443
mixed	Auth Service	token check
executive	Sign-in	—

Two rules that hold at every audience level:

• Never invent detail to fill a slot. If the source says svc-04, executive output says what it does only if you can tell from context — otherwise ask, don't guess a business name.
• Keep the source's vocabulary for proper nouns. Renaming Kafka to Message Bus is fine at executive; renaming it to Event Grid (a different product) is a factual error.

Non-Latin labels

Geist has no CJK coverage. When labels contain Japanese, Chinese, or Korean text, extend the family on those <text> elements — don't swap the whole skin:

<text font-family="'Geist', 'Hiragino Sans', 'Noto Sans JP', 'Yu Gothic', sans-serif">認証サービス</text>

For mono sublabels use 'Geist Mono', 'Noto Sans Mono CJK JP', monospace. CJK glyphs render ~10% wider than Latin at the same size — budget box width accordingly, and prefer 12px names over 8px sublabels for CJK, which goes muddy below 10px.

---

5. Fidelity ledger

Any time output is smaller than input — every balanced and simplified run, and most faithful ones — report what you cut, in chat, after the file path. Short and specific:

Detail: balanced · 18 source nodes → 9 drawn
Merged:  worker-01..06 → "Ingest Worker ×6"
Collapsed: "Observability" group (Grafana, Loki, Tempo) → one node
Dropped: 2 sticky notes, CI pipeline (cross-cutting)
Kept in full: the request path (Client → Gateway → Orders → Postgres)

The reader of the diagram can't see what's missing. The person who asked for it needs to.

---

6. Checklist

Run alongside the SKILL.md §9 taste gate.

• All four dials set — explicitly requested, inferred from the destination, or defaulted and stated?
• viewBox matches the size preset exactly, values divisible by 4?
• Type ramp matches the size class — not the standard ramp on a slide?
• 40px outer margin honoured (64px for social-og)?
• Node count inside the detail level's ceiling?
• faithful above 9 nodes → zoned, and split above 24?
• Node names, sublabels, and edge labels all at the same audience level?
• CJK labels given a font fallback?
• Fidelity ledger reported for anything cut?
• Diagram <svg> has role="img", resolving aria-labelledby, a non-empty first-child <title>, a non-empty <desc>, and per-diagram/variant prefixed IDs?
• Requested non-HTML formats produced via export.md, not hand-authored?