Skip to content

drafael/coding-harness / skills/diagram-design

diagram-design

Verified

Create branded architecture, IT current-state, flowchart, sequence, state machine, ER/data model, timeline, swimlane, quadrant, radar/spider, polar chart (polar/radial lollipop), loop/flywheel, nested, tree, org chart, layer stack, Venn, pyramid/funnel, treemap, bar, line, Gantt and scatter charts, high-level, process, medallion, data flow, DP integration, DP security matrix, Sankey, fishbone, Wardley map, kanban, user journey, deployment, dependency graph, UML class, story map, or database schema diagrams as standalone HTML/SVG/PNG. Redraw .drawio/.drawio.png/.drawio.svg or Mermaid .mmd sources at a chosen size/detail; onboard brand tokens from a website; add semantic patterns, callouts, accessible motion, or sketchy/hand-drawn styling.

FileKindSize
LICENSEother1.0 KB
README.mdmarkdown5.6 KB
SKILL.mdskill md38.6 KB
THIRD_PARTY_LICENSES.mdmarkdown2.6 KB
assets/example-architecture-dark.htmlother11.8 KB
assets/example-architecture-full.htmlother14.6 KB
assets/example-architecture.htmlother11.8 KB
assets/example-bar-dark.htmlother8.8 KB
assets/example-bar-full.htmlother11.0 KB
assets/example-bar.htmlother8.7 KB
assets/example-bubble-dark.htmlother11.2 KB
assets/example-bubble-full.htmlother14.8 KB
assets/example-bubble.htmlother11.1 KB
assets/example-data-flow-dark.htmlother12.7 KB
assets/example-data-flow-full.htmlother15.5 KB
assets/example-data-flow.htmlother12.5 KB
assets/example-datalake-dark.htmlother24.3 KB
assets/example-datalake-full.htmlother27.7 KB
assets/example-datalake.htmlother25.8 KB
assets/example-db-schema-dark.htmlother24.1 KB
assets/example-db-schema-full.htmlother27.0 KB
assets/example-db-schema.htmlother23.9 KB
assets/example-dependency-dark.htmlother17.4 KB
assets/example-dependency-full.htmlother20.6 KB
assets/example-dependency.htmlother17.2 KB
assets/example-deployment-dark.htmlother13.2 KB
assets/example-deployment-full.htmlother16.4 KB
assets/example-deployment.htmlother13.1 KB
assets/example-dp-integration-dark.htmlother14.4 KB
assets/example-dp-integration-full.htmlother16.9 KB
assets/example-dp-integration.htmlother14.4 KB
assets/example-dp-security-matrix-dark.htmlother10.0 KB
assets/example-dp-security-matrix-full.htmlother12.3 KB
assets/example-dp-security-matrix.htmlother10.7 KB
assets/example-er-dark.htmlother13.9 KB
assets/example-er-full.htmlother16.7 KB
assets/example-er.htmlother13.8 KB
assets/example-fishbone-dark.htmlother8.5 KB
assets/example-fishbone-full.htmlother11.1 KB
assets/example-fishbone.htmlother8.4 KB
assets/example-flowchart-dark.htmlother9.0 KB
assets/example-flowchart-full.htmlother11.9 KB
assets/example-flowchart.htmlother9.0 KB
assets/example-gantt-dark.htmlother10.0 KB
assets/example-gantt-full.htmlother11.6 KB
assets/example-gantt.htmlother9.8 KB
assets/example-high-level-dark.htmlother23.6 KB
assets/example-high-level-full.htmlother27.8 KB
assets/example-high-level-vertical-dark.htmlother24.4 KB
assets/example-high-level-vertical-full.htmlother28.1 KB
assets/example-high-level-vertical.htmlother29.7 KB
assets/example-high-level.htmlother26.3 KB
assets/example-import-drawio.htmlother11.8 KB
assets/example-import-mermaid.htmlother7.9 KB
assets/example-it-state-dark.htmlother11.7 KB
assets/example-it-state-full.htmlother13.9 KB
assets/example-it-state.htmlother12.2 KB
assets/example-journey-dark.htmlother8.9 KB
assets/example-journey-full.htmlother11.5 KB
assets/example-journey.htmlother8.9 KB
assets/example-kanban-dark.htmlother10.8 KB
assets/example-kanban-full.htmlother13.6 KB
assets/example-kanban.htmlother10.7 KB
assets/example-layers-dark.htmlother6.8 KB
assets/example-layers-full.htmlother9.8 KB
assets/example-layers.htmlother6.7 KB
assets/example-line-dark.htmlother7.3 KB
assets/example-line-full.htmlother9.8 KB
assets/example-line.htmlother7.3 KB
assets/example-loop-dark.htmlother6.7 KB
assets/example-loop-full.htmlother9.7 KB
assets/example-loop-terminal.htmlother9.8 KB
assets/example-loop.htmlother6.6 KB
assets/example-medallion-dark.htmlother12.7 KB
assets/example-medallion-full.htmlother15.5 KB
assets/example-medallion.htmlother12.6 KB
assets/example-nested-dark.htmlother6.6 KB
assets/example-nested-full.htmlother9.6 KB
assets/example-nested.htmlother6.7 KB
assets/example-org-chart-dark.htmlother11.3 KB
assets/example-org-chart-full.htmlother11.8 KB
assets/example-org-chart.htmlother11.3 KB
assets/example-paved-road-animated.htmlother27.6 KB
assets/example-polar-dark.htmlother10.2 KB
assets/example-polar-full.htmlother12.4 KB
assets/example-polar.htmlother10.1 KB
assets/example-policy-trace-animated.htmlother24.9 KB
assets/example-process-dark.htmlother14.7 KB
assets/example-process-full.htmlother17.1 KB
assets/example-process.htmlother14.6 KB
assets/example-pyramid-dark.htmlother6.5 KB
assets/example-pyramid-full.htmlother9.5 KB
assets/example-pyramid.htmlother6.4 KB
assets/example-quadrant-consultant.htmlother11.6 KB
assets/example-quadrant-dark.htmlother6.5 KB
assets/example-quadrant-full.htmlother9.4 KB
assets/example-quadrant.htmlother6.4 KB
assets/example-queue-animated.htmlother29.2 KB
assets/example-radar-dark.htmlother7.5 KB
assets/example-radar-full.htmlother10.2 KB
assets/example-radar.htmlother7.7 KB
assets/example-ridgeline-dark.htmlother10.1 KB
assets/example-ridgeline-full.htmlother13.9 KB
assets/example-ridgeline.htmlother10.0 KB
assets/example-sankey-dark.htmlother8.8 KB
assets/example-sankey-full.htmlother11.5 KB
assets/example-sankey.htmlother8.7 KB
assets/example-scatter-dark.htmlother9.3 KB
assets/example-scatter-full.htmlother11.3 KB
assets/example-scatter.htmlother9.2 KB
assets/example-sequence-dark.htmlother13.5 KB
assets/example-sequence-full.htmlother17.8 KB
assets/example-sequence-oauth-dark.htmlother11.8 KB
assets/example-sequence-oauth-full.htmlother16.2 KB
assets/example-sequence-oauth.htmlother14.0 KB
assets/example-sequence.htmlother13.4 KB
assets/example-slopegraph-dark.htmlother10.2 KB
assets/example-slopegraph-full.htmlother13.6 KB
assets/example-slopegraph.htmlother10.1 KB
assets/example-state-dark.htmlother8.5 KB
assets/example-state-full.htmlother11.4 KB
assets/example-state.htmlother8.5 KB
assets/example-story-map-dark.htmlother12.0 KB
assets/example-story-map-full.htmlother15.1 KB
assets/example-story-map.htmlother11.9 KB
assets/example-swimlane-dark.htmlother10.3 KB
assets/example-swimlane-full.htmlother13.2 KB
assets/example-swimlane.htmlother10.2 KB
assets/example-timeline-dark.htmlother7.2 KB
assets/example-timeline-full.htmlother10.1 KB
assets/example-timeline.htmlother7.2 KB
assets/example-tree-dark.htmlother10.8 KB
assets/example-tree-full.htmlother13.7 KB
assets/example-tree.htmlother10.7 KB
assets/example-treemap-dark.htmlother7.5 KB
assets/example-treemap-full.htmlother10.5 KB
assets/example-treemap.htmlother7.4 KB
assets/example-uml-class-dark.htmlother12.1 KB
assets/example-uml-class-full.htmlother15.3 KB
assets/example-uml-class.htmlother12.1 KB
assets/example-venn-dark.htmlother6.5 KB
assets/example-venn-full.htmlother9.7 KB
assets/example-venn.htmlother5.0 KB
assets/example-wardley-dark.htmlother8.7 KB
assets/example-wardley-full.htmlother11.1 KB
assets/example-wardley.htmlother8.7 KB
assets/icons.htmlother106.0 KB
assets/index.htmlother15.2 KB
assets/template-dark.htmlother3.1 KB
assets/template-full.htmlother22.0 KB
assets/template-motion.htmlother19.4 KB
assets/template-terminal.htmlother4.8 KB
assets/template.htmlother3.2 KB
local-patches/playwright-chromium-discovery.patchother32.2 KB
references/animation.mdmarkdown11.5 KB
references/doctor.mdmarkdown5.4 KB
references/export.mdmarkdown8.3 KB
references/import-drawio.mdmarkdown12.8 KB
references/import-mermaid.mdmarkdown8.7 KB
references/onboarding.mdmarkdown13.5 KB
references/output-spec.mdmarkdown10.9 KB
references/primitive-annotation.mdmarkdown1.7 KB
references/primitive-icons.mdmarkdown103.5 KB
references/primitive-sketchy.mdmarkdown1.7 KB
references/primitive-terminal.mdmarkdown3.8 KB
references/profiles.mdmarkdown13.9 KB
references/semantic-patterns.mdmarkdown10.1 KB
references/style-guide.mdmarkdown8.5 KB
references/type-architecture.mdmarkdown4.9 KB
references/type-bar.mdmarkdown13.3 KB
references/type-data-flow.mdmarkdown20.8 KB
references/type-db-schema.mdmarkdown4.8 KB
references/type-dependency.mdmarkdown4.1 KB
references/type-deployment.mdmarkdown4.1 KB
references/type-dp-integration.mdmarkdown21.7 KB
references/type-dp-security-matrix.mdmarkdown18.6 KB
references/type-er.mdmarkdown1.5 KB
references/type-fishbone.mdmarkdown5.6 KB
references/type-flowchart.mdmarkdown1.1 KB
references/type-gantt.mdmarkdown2.4 KB
references/type-high-level.mdmarkdown26.1 KB
references/type-it-state.mdmarkdown29.3 KB
references/type-journey.mdmarkdown5.0 KB
references/type-kanban.mdmarkdown4.2 KB
references/type-layers.mdmarkdown1.5 KB
references/type-line.mdmarkdown26.8 KB
references/type-loop.mdmarkdown12.3 KB
references/type-medallion.mdmarkdown21.7 KB
references/type-nested.mdmarkdown1.4 KB
references/type-org-chart.mdmarkdown3.0 KB
references/type-polar.mdmarkdown7.6 KB
references/type-process.mdmarkdown27.9 KB
references/type-pyramid.mdmarkdown1.7 KB
references/type-quadrant.mdmarkdown6.1 KB
references/type-radar.mdmarkdown5.5 KB
references/type-sankey.mdmarkdown8.7 KB
references/type-scatter.mdmarkdown11.0 KB
references/type-sequence.mdmarkdown6.5 KB
references/type-state.mdmarkdown1.1 KB
references/type-story-map.mdmarkdown4.7 KB

references/output-spec.md

View on GitHub
# 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`](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](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:

```svg
<text font-family="'Geist', 'Hiragino Sans', 'Noto Sans JP', 'Yu Gothic', sans-serif">認証サービス</text>
<text font-family="'Geist', 'Apple SD Gothic Neo', 'Noto Sans KR', 'Malgun Gothic', sans-serif">인증 서비스</text>
```

The Hiragino/Yu Gothic stack carries no Hangul glyphs, so Korean labels need the Korean stack — don't reuse the Japanese one. For mono sublabels use `'Geist Mono', 'Noto Sans Mono CJK JP', monospace` (Japanese) or `'Geist Mono', 'Noto Sans Mono CJK KR', monospace` (Korean). Budget **1em per full-width CJK glyph**, not a small percentage over the average Latin glyph; `verify-treemap.py` uses that conservative contract for Unicode wide/full-width characters and treats combining marks as non-advancing. Prefer 12px names over 8px sublabels for CJK, which goes muddy below 10px. Actual width still varies by fallback font, so run the relevant geometry verifier after translating labels.

---

## 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`](export.md), not hand-authored?
rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 194kUpdated Claude CodeCodexVerifiedInstall