/drawio-diagram-forge

Style Guide

Node Colors

Edge Styles

Orthogonal (Recommended)

edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;

Curved

edgeStyle=elbowEdgeStyle;elbow=horizontal;rounded=1;

Straight

endArrow=classic;html=1;

Shape Styles

Rounded Rectangle

rounded=1;whiteSpace=wrap;html=1;

Ellipse

ellipse;whiteSpace=wrap;html=1;

Diamond

rhombus;whiteSpace=wrap;html=1;

Swimlane/Container

swimlane;horizontal=1;startSize=30;

Layout Recommendations

Title / Caption

• Do NOT embed title text in the diagram (e.g., "図1-1 ..."). Captions belong in the document layer (Markdown ![caption](...), Re:VIEW //image[id][caption], etc.).
• Embedding titles causes duplication when the document already renders a figure caption.
• If the exported image is likely to circulate standalone (chat, slide, ticket, SNS, pasted image), use the diagram title/subtitle to identify the feature or topic name directly. Avoid generic headings like before / after alone.
• Good: Summarized Gateway Prefixes の before / after
• Weak: ExpressRoute の広告ルート数を before / after でみる when the feature name is missing from the image itself.

Spacing

Top Callouts / Note Boxes

For explanatory note boxes placed near the top of a panel or container:

• Inset from the outer frame by at least 16-24px. Do not let the note box kiss or visually merge with the panel border.
• Prefer 3-4 short lines over 2 long lines. If Japanese text feels tight, reduce line length before reducing font size.
• Increase note box height first when text feels crowded. Do not solve crowding only by shrinking fonts.
• Keep arrow labels on a separate Y band from the note box. Labels that sit at the same height tend to look overlapped in exports.
• Review at actual embed width after export. A diagram that looks fine at full canvas size can still collide when embedded in Markdown or docs.

Article Concept / Lifecycle Diagrams

For article-facing concept diagrams that explain a repeated workflow:

• Use a single visible start point. If the flow begins from multiple places, readers often cannot tell what to follow first.
• For metric diagrams such as usage rate, show denominator and numerator explicitly, then summarize the formula in one final node. Avoid long dashed aggregation lines that make the diagram feel like a wiring diagram.
• Keep the main cycle to 3-4 primary nodes. Support tools, marketplaces, and implementation aids should be a footer note or side callout, not peer nodes in the main loop.
• Use outcome-oriented node titles such as Skill を改善, not implementation-detail titles such as Gotchas に戻す. Highlight the important detail (Gotchas) inside the node body instead.
• Split long slash-separated phrases into separate short lines. If a line like description / Gotchas / references feels tight at embed width, rewrite it as description を整える + Gotchas / references に分ける.
• Shrink-wrap the canvas after layout changes. If footer notes move up, reduce page height so exported assets do not carry large dead whitespace.
• Validate both source and delivery artifacts after wording tweaks: .drawio is the editable SSOT, and .drawio.svg is the Markdown/web artifact.

Edge Crossing Prevention

Apply to small diagrams too; automatic elbows can overlap node borders even with only two nodes.

• Route stepped connectors inside the gap — for a rightward connector between vertically offset boxes, put both bend points at the gap midpoint: (gapX, sourceY) and (gapX, targetY). Enter the target horizontally, not along its border. Widen the gap if the arrowhead lacks clearance; routing hints still require exported-image inspection.

• Separate forward and return paths — give a feedback edge a different entry side and corridor from the forward edge (for example, enter the earlier node from below). Preserve the process meaning and keep the return label off nodes and other lines.

• Align source and target y — place each agent/processor at the same y as its output node. Lines stay horizontal, crossing drops to near zero.

• Avoid unnecessary return/merge lines — use nearby terminal nodes for decision outcomes; keep semantically required feedback on a separate path. Long detours may validate while remaining visually tangled.

• Reorder sibling nodes before drawing detours — if a connector from one item in a stacked group must jump around another item, first swap or move the related item closer to its target/callout. A short straight connector is usually clearer than a routed line that skirts sibling boxes.

• Avoid swimlane-relative coordinates — when edges cross swimlane boundaries, exitX/entryY resolve to group-relative positions that are hard to predict. Use absolute positioning (parent="1") for all nodes instead.

• Spread entryY on shared targets — when multiple edges enter the same node, enlarge the node height and assign distinct entryY values (e.g., 0.1 / 0.5 / 0.9) so lines arrive at different vertical points.

• Collapse fan-out into one edge — instead of N individual arrows from an orchestrator to N children, draw a single dashed arrow to a group outline and label it (e.g., "delegates").

• Separate auxiliary elements — legends, data stores, and footnotes must sit below the main flow with ≥40px vertical gap from the lowest flow node. Never place them at the same y as flow outputs.

Nested Containers (Hierarchy Diagrams)

When using nested rectangles to show hierarchy (e.g., Enterprise > Org > Team > Repo):

• Container height = content bottom edge + 15–20px padding. Do not use large fixed heights when children are few.
• Legend placement = always outside the outermost container. Never inside a child container — it reads as part of that group.
• Page size = tightest bounding box of all elements + 20px margin. Avoid "generous" pages that create dead whitespace.
• Edges are optional — spatial containment already conveys hierarchy. Only add arrows when showing data/control flow across containers.

Flow Diagrams (Branch/Merge Lines)

When combining diagonal branch/merge lines with annotation boxes (e.g., GitHub Flow step labels):

• Place step boxes below the diagonal endpoints — if a diagonal goes from (x1,y1) to (x2,y2), boxes must have y > max(y1, y2) to avoid crossing.
• Dashed connectors starting from a box edge should begin at y - 2px (not exactly at the top edge) to avoid false overlap in validators.
• Keep horizontal feature branch and step row on separate Y bands — minimum 40px gap between the branch line Y and the top of step boxes.
• Wrap a long linear flow into a serpentine rather than stretching it across the page. Row 1 runs left to right, row 2 sits under it running right to left, and the only cross-row arrow is a single vertical segment, so the figure lands inside the aspect band and leaves no diagonal for the geometry sweep to flag. A six-step flow measured at 5.3:1 came back to 2.3:1 this way.

Icons On Connectors

When a small service icon sits close to a busy connector or arrow:

• Prefer icon-only and let the nearby node / edge label carry the meaning. Do not force a second label under the icon if it creates collisions.
• Move the icon 10-20px away from the connector centerline before shrinking it further.
• Keep the icon above the connector in z-order / draw order so the arrow does not cut through the symbol.
• If the connector already has a readable label, avoid repeating the same service name under the icon.

Alignment

• Align nodes in grid (gridSize=10)
• Center labels in nodes
• Use consistent node sizes
• Container with children → verticalAlign=top;spacingTop=5; to keep the label above child nodes
• Standalone box (no children) → verticalAlign=middle; to center text and avoid lopsided whitespace

Public-safe Labels

• For diagrams that may be published externally, avoid customer-specific or vendor-internal acronyms unless the acronym itself is the subject of the diagram.
• Prefer generic labels such as On-premises gateway, On-premises router, or Edge network over terms that only make sense in one customer's environment.
• If an internal acronym must appear somewhere, keep it in the surrounding article text, not as the primary label inside the figure.
• For commercially published work, resolve a third party's logo or wordmark against the mark owner's own permitted-use page before drawing it. When that page enumerates the media it allows and also says the mark needs prior written permission, treat a medium missing from the list as not covered and escalate rather than assuming. A neutral concept shape with a text label avoids the question entirely and usually costs the figure nothing.
• An approximation of a mark inherits the same question as the mark. So does redrawn product chrome — header bars, sidebars, tab strips — which carries the exposure of a screenshot without its evidence. Generic pictograms (cloud, folder, machine, key, document) are fine when their licence permits commercial use; keep the outline simple so it survives reduction, and always pair one with a label.

Monochrome Print Profile

When the destination is a printed page, the figure is reduced, converted to grayscale, and placed at a fixed column width. Design to that first.

• Keep the content to what survives reduction: roughly 4-7 primary nodes (9 at the outside), about six arrows, at most two levels of branching, and code fragments of three to five lines
• Prefer landscape. Column width is fixed, so a near-square figure eats close to half a page; aim between 1.5:1 and 3:1
• Never carry meaning in colour alone. Use line style, border weight, and labels, then check the result in grayscale
• Keep the lead sentence and any summary box out of the figure alongside the title. Confirm whether the destination renders figure captions and numbers at all; where it does not, anything the reader must have has to live in the prose
• Draw the line by what a string does, not by how long it is. Element labels, the criterion a step is judged by, and a reading-order legend earn their place in the figure; a claim, a conclusion, or a piece of advice belongs to the prose. Grep the surrounding section before deleting one — a note that survived review is usually already stated there, so removing it costs no information
• Stripping prose out of a figure shortens it and can push the aspect ratio back out of range. Treat that as the tell that the sentence was padding the height. Win the height back with structure, an extra labelled band or a wrapped row, not with another sentence
• Verify the figure shows what the prose claims about it. A simplified diagram that contradicts its own sentence costs more trust than a missing figure would

Diagram Size

Pre-delivery Geometry Sweep

A structural validator proves the XML parses and the ids resolve. It says nothing about where the shapes ended up. Sweep the geometry mechanically before looking at the render, so the visual pass spends its attention on meaning.

Scan the .drawio source and the exported asset for:

• edges that overlap another edge along a shared span
• edges left to the router whose endpoints sit in a diagonal relationship
• edge endpoints that terminate underneath a node instead of at its border
• labels whose bounding box intersects a node
• geometry that falls outside the page rectangle
• measured aspect ratio, read from the exported width and height, against what the destination allows

Report these rather than blocking on them. They are strong hints, not verdicts, and a deliberate overlap occasionally reads better than the alternative.

Check meaning against the accompanying text: arrows imply direction or sequence, so do not chain independent comparison categories into a pipeline. For a whole-set review, include diagrams with no machine warnings; record each as revised and visually checked, unchanged and visually checked, or unverified. Contact sheets support triage, not proof that small text is readable at the delivery size.

Always shrink-wrap: set page width/height to tightest bounding box + 20px margin.

Editable Source Policy

• Treat .drawio as the editable source of truth for documentation diagrams.
• Treat .drawio.svg as the delivery/render artifact for Markdown and web embedding.
• When the user explicitly needs to edit the diagram, ship and link the .drawio first; preview SVG/PNG is optional and must not replace the editable source.
• Do not label a plain SVG as .drawio.svg. That suffix is reserved for metadata-embedded SVG exports that Draw.io can reopen.
• If a diagram required manual SVG-level cleanup, recreate or preserve the equivalent .drawio source before calling it done.
• Do not leave a documentation diagram as SVG-only unless the user explicitly asked for a disposable one-off artifact.
• If the editor keeps resolving a stale path or refuses to open a file that exists, it is acceptable to create short alias filenames such as current-understanding.drawio and current-understanding.svg, then repoint local links to the alias pair.

Font Settings

fontSize=12;fontStyle=0;fontFamily=Helvetica;

Web article / blog embed (Qiita, WordPress, Medium, note)

For diagrams embedded in web articles that are viewed inline with body text (typically 700–900px wide, retina/HiDPI scaling), the floor must be raised:

• Title: 18-22px (fontSize=22;fontStyle=1)
• Primary node label: 14-18px
• Sub label / caption inside node: 13-15px (use <font style="font-size: 14px"> inline)
• Edge label: 13px+
• Footnote / insight band: 14-15px

Verify by viewing the exported PNG at the article's actual rendered width (not at 100%). If the reader can't read the label on a 13-inch laptop screen without zooming, the font is too small. Re-export and reload, don't ship.

Also avoid wasting interior space:

• verticalAlign=middle for single-line cells. Use top + spacingTop only when the cell is a container with children below.
• Box height should be roughly font-size * line-count * 1.5 + 20-30px padding. A 70px box with a single 14px label leaves ~40px of dead vertical space.

For book/PDF diagrams that are scaled down by the publishing pipeline, raise the floor before export:

• Use at least 13px for minor labels, 15-17px for edge/action labels, and 17-23px for primary state or step nodes.
• Delete legend, tips, and sentence-like explanations from the figure when the surrounding text already explains them. Extra text shrinks the real teaching labels.
• Use dead whitespace to enlarge boxes and labels, then shrink-wrap the canvas. A wide empty margin makes every label smaller in the final PDF.
• Put arrow labels on their own lane, or remove labels already implied by nearby text. Never let a label hide the arrow shaft or arrowhead.
• For hierarchy diagrams, stack sparse sibling groups vertically when that lets labels and child boxes grow.
• For workflow diagrams, move trigger/source groups above the main workflow when side-by-side placement creates wasted width.

Export for PDF Pipelines

When diagrams are embedded in PDF (via Re:VIEW, LaTeX, Pandoc, etc.):

• Export directly from .drawio to PNG using the draw.io desktop CLI:

  draw.io --export --format png --scale 2 --output out.png source.drawio

• Do NOT use browser/Edge --screenshot on SVG — this produces a fixed-viewport capture (e.g., 756×488) regardless of diagram size, causing blurriness and cropping.
• --scale 2 produces 2× resolution for crisp text at print DPI.
• The SVG exported by the draw.io CLI is plain SVG unless --embed-diagram is passed; without it the file is no longer re-editable in the VS Code Draw.io extension. Keep the .drawio as the editable source either way.
• For Markdown preview, reference *.drawio.svg. For PDF build, use the PNG export.
• Render the final PDF page, not only the exported PNG. The publishing layer may scale, float, or move the image.
• If changing a wrapper macro does not affect image size, inspect generated TeX for per-image options such as width=\maxwidth. In that case, enlarge the diagram content and shrink-wrap the canvas instead of assuming the global width rule applies.