Create Drawio Diagram

Create Draw.io Diagram

Quick Start

Create editable Draw.io diagrams for architecture deliverables using the templates in templates/ and the visual rules in STYLE.md.

Use this skill when a generated architecture document needs diagrams that stakeholders can edit in Draw.io or diagrams.net. Store generated .drawio files in the same folder as the architecture document they support.

Diagram Templates

Use these templates as starting points:

• templates/capability-overview.drawio for actors, neighboring capabilities, and external dependencies
• templates/target-architecture-diagram.drawio for a simple target architecture overview across capabilities, applications, data, integrations, and technology
• templates/solution-architecture-diagram.drawio for a simple solution architecture overview across channels, components, integrations, data stores, and external systems
• templates/data-architecture-diagram.drawio for a simple data architecture overview across source systems, canonical data objects, owners, consumers, integrations, and governance
• templates/data-flow.drawio for data flow diagrams with process stages across the top, systems as horizontal lanes, and labeled data movements between lanes
• templates/application-component-view.drawio for applications, services, components, platforms, and responsibilities
• templates/conceptual-data-model.drawio for canonical data objects and relationships
• templates/integration-design.drawio for component maps organized in vertical layers: Public Internet, Frontend, Engagement, Integration, and Enterprise Foundation (Backoffice)
• templates/integration-flow.drawio for producers, consumers, interfaces, triggers, protocols, and sequence

Style Rules

Use STYLE.md for colors, shape styles, connector styles, and layout rules.

Do not introduce new colors unless the user explicitly asks for a palette change. Reuse the standard palette so diagrams stay consistent across solution architecture documents.

Light Theme Source Rules

Create .drawio sources as light-theme diagrams from the start.

• Every mxGraphModel must set background="#fbfcfa". Do not leave the page background unset or transparent.
• Every visible shape, layer band, connector, label, and application header must use explicit hex colors from STYLE.md.
• Do not use Draw.io inherited or theme-dependent values such as strokeColor=default, fontColor=default, labelBackgroundColor=default, currentColor, CSS variables, or light-dark(...).
• Use dark text, normally fontColor=#17201d, on light fills. Use fontColor=#5d6964 for connector labels unless a specific palette color communicates flow type.
• Use labelBackgroundColor=#fbfcfa for connector labels so labels remain readable on light layer bands.
• Treat dark-theme or theme-adaptive source styles as defects in the .drawio file. Fix the .drawio source before exporting SVG.

Workflow

1. Confirm the diagram purpose and choose the closest template.
2. Copy the template into the target architecture folder using a descriptive same-purpose filename, such as capability-overview.drawio.
3. Replace placeholder labels with concrete architecture content from the source document, glossary, capability overview, or clarification session.
4. Apply the exact standard colors and connector styles from STYLE.md. Do not use dark theme variants, approximate colors, or inherited editor defaults.
5. Keep labels business-readable and concise. Use notes in the surrounding architecture document for detail that would clutter the diagram.
6. Keep canonical data object names general. Do not use vendor object names, table names, endpoint resources, or internal system names in this public repository.
7. Do not invent systems, relationships, protocols, owners, or data flows. Mark unknowns as assumptions or open questions in the architecture document.
8. If an image export is needed, export the Draw.io diagram to a same-basename .svg using the SVG export rules below, then embed the SVG in the architecture document with a nearby link to the .drawio source.

Capability Context Layout

When using templates/capability-overview.drawio, preserve the template topology. The diagram is a context view, not an inventory list.

• Place actors, teams, and channels in the left zone.
• Place the target capability in the center as the primary green node. The target capability node label must be only the capability name, such as CRM; do not list features, workspaces, screens, data products, roles, baselines, or responsibilities inside the target capability node.
• Place systems or capabilities that deliver data to the target capability below the target capability.
• Place systems or capabilities that get data from the target capability above the target capability.
• Place external dependencies, third parties, regulatory constraints, and vendor dependencies in the right zone.
• Connect each node to the target capability with a concise relationship label.
• Use light palette colors from STYLE.md: actors yellow, target capability green, upstream/downstream systems blue, and external dependencies red.
• When a node is backed by a named application, show only the application name in a separate 10 px high header box overlaid on the top edge of that node. Use the Application name header style from STYLE.md, make the header as wide as the component, align its top with the component top, and render it above the component body. Put capability names, component names, dependencies, and responsibilities in the node body. If the application name is unknown, omit the header.
• Show each confirmed stakeholder, user group, actor, or channel as a separate actor node. Do not collapse stakeholders and users into one list box, and do not create a wrapper node titled Stakeholders and users.
• Show components that provide data to the target capability as separate bottom nodes per main data object and/or contributing capability. When several data objects come from one application or source system, create one node per data object and repeat the application name in the node's application header. Do not collapse multiple main data objects into one provider box.
• Show each confirmed produced outcome, downstream consumer, or related capability as a separate top consumer node. Do not collapse produced outcomes into one list box.
• Do not stack every actor, system, platform, and dependency in one vertical column.
• Do not convert the target capability into a system dependency. Keep it visually distinct.
• Route actor connectors from the right side of actor nodes to the left side of the target capability, data-provider connectors from bottom nodes into the bottom of the target capability, consumer connectors from the top of the target capability to top nodes, and external dependency connectors from the right side of the target capability.
• Use orthogonal connectors for capability context diagrams. Do not use diagonal straight-line connectors when an orthogonal route can keep labels and arrowheads clearer.
• Attach arrows to the nearest relevant edge of each box using explicit ports. Do not let arrowheads float near a box or land inside another box.
• Route connector waypoints through whitespace lanes between rows and columns. Connectors must not cross through node bodies, application headers, or node text.
• Do not route multiple capability overview connectors through a shared bus line when their labels, arrowheads, or vertical segments would overlap. Use one staggered orthogonal lane per connector for actor, input-provider, outcome, and external-dependency relationships.
• Keep repeated relationship labels on their own connector segments. If repeated labels such as uses / governs, produces, provides input, or depends on collide, stagger the connector lanes or shorten the labels before exporting.
• Avoid repeated relationship labels that overlap. When many connectors share the same relationship such as provides input or gets data, label one clear lane or stagger labels in whitespace rather than labeling every parallel connector.
• Leave generous vertical space between the top consumer row, the target capability, and the bottom data-provider row so connector labels do not sit on top of nodes or each other.
• When there are multiple nodes in one zone, stagger their connector lanes so labels and arrowheads do not overlap. Use explicit mxPoint waypoints where automatic routing creates overlap.
• If a zone has many items, widen the canvas and spread nodes across the zone before grouping. Group only when the source content does not provide enough detail to keep the nodes meaningful or the diagram would become unreadable even after widening.
• If the source content does not identify a relationship direction, keep the node out of the diagram and record the gap as an assumption or open question in the document.

Capability Context Helper

Use scripts/write-capability-context-diagram.py when a workflow needs to generate both an editable .drawio source and a same-basename .svg for a capability context diagram.

python3 skills/create-drawio-diagram/scripts/write-capability-context-diagram.py "Order Management" \
  --output-dir capabilities/order-management \
  --stakeholder "Customer service" \
  --stakeholder "Operations" \
  --input-provider $'ERP\nCustomer order\nCustomer account' \
  --input-provider "Commerce platform: Cart checkout event" \
  --outcome "Inventory Management" \
  --constraint "Order status is fragmented across systems."

By default, the helper creates capability-overview.drawio and capability-overview.svg in the output directory. Use --basename when a different same-basename pair is needed.

For --input-provider, pass either a single application or source system name, an inline Application: Data object value, or a multiline block where the first line is the application/source system and each later line is a main data object or contributing capability. Multiline blocks generate one bottom node per later line.

The helper also accepts compatibility aliases for upstream capability workflows:

• --existing-system as an alias for --input-provider
• --related-capability as an alias for --outcome
• --pain-point as an alias for --constraint

Solution Architecture Layout

When using templates/solution-architecture-diagram.drawio, preserve the layered architecture structure. The diagram is a solution overview for one application or capability implementation, not a detailed sequence diagram or interface catalog.

• Place components inside the corresponding layer band, ordered from top to bottom: Public Internet, Frontend, Engagement Services, Integration, and Enterprise Foundation (Backoffice).
• When the solution includes a Backend-for-Frontend component, place it in the Frontend layer directly below the frontend/channel component it supports. Align the frontend component and BFF on the same x-position and use a vertical connector between them whenever possible.
• Do not place a Backend-for-Frontend component in Engagement Services or Integration. It remains a Frontend component even when it calls APIs, composes responses, or orchestrates channel-specific requests.
• Treat the canvas as flexible. Increase pageWidth, pageHeight, and every layer-band width or height whenever the default template would force cramped components, overlapping connectors, clipped labels, or crowded layer bands.
• Prefer widening or heightening the canvas and spreading components before shrinking boxes, shortening important labels, or stacking unrelated components.
• Grow all layer bands to the same width when the diagram needs more horizontal space so the architecture layers remain visually aligned. Increase layer heights and move lower bands down when components, notes, or connector labels need more vertical space.
• Leave enough whitespace between components for connector routing and labels. For labeled horizontal connectors, reserve at least 180 px between component edges; for labels longer than 24 characters, reserve at least 240 px or move detail into the document.
• Use separate routing lanes for different relationships. Do not let connectors share the same segment when their labels, arrowheads, or vertical drops would overlap.
• Route long cross-layer connectors through open whitespace lanes. Do not run connectors through layer labels, component bodies, application headers, or other connector labels.
• For dense solution architecture diagrams, widen and heighten the canvas first, then increase layer heights, then move components farther apart. Do not accept an SVG where component labels, connector labels, or arrowheads overlap.
• Keep the diagram readable at document scale. It is better to create a wider or taller same-basename SVG than to compress a complete solution into the default canvas.

Integration Design Layout

When using templates/integration-design.drawio, preserve the vertical layer structure. The diagram is a layered component map for an integration design, not a sequence diagram, endpoint catalog, or source-to-destination column layout.

• Place components inside the corresponding layer band, ordered from top to bottom: Public Internet, Frontend, Engagement Services, Integration, and Enterprise Foundation (Backoffice).
• Use plain colored rectangles for layer bands, not Draw.io swimlanes. Keep layer labels left-aligned and top-aligned. Use the layer fill color with no stroke.
• Treat the canvas as flexible. Increase pageWidth, pageHeight, and the layer-band rectangle sizes as needed so all components, routing lanes, connector labels, and notes fit cleanly.
• Treat every layer band as flexible in width and height. Grow a layer wider for additional horizontal component lanes, and grow it taller for stacked components or extra connector routing space.
• Leave clear top and bottom padding around components inside each layer band.
• Align components toward the left side of the canvas by default. Start the first meaningful component column close to the layer content area, then place later components to the right as the integration progresses. Do not center the whole diagram when there is unused space on the left.
• Use a consistent component grid across layers: align related components by x-position when they participate in the same flow, and align peer components on the same baseline inside a layer.
• Prefer vertical flow columns for linear integrations across layers. When a component in one layer directly calls, publishes to, or consumes from a component in another layer, place the related components above and below each other on the same x-position where space allows.
• Use horizontal placement primarily for peer components in the same layer, branching alternatives, fan-out/fan-in paths, or same-layer handoffs. Do not force a left-to-right stair-step layout when a top-to-bottom column would be clearer.
• Keep components as the main diagram elements. Use the exact layer colors from STYLE.md to classify each component: Public Internet light red, Frontend light yellow, Engagement light green, Integration light grey, and Enterprise Foundation (Backoffice) light blue.
• Show every confirmed component needed to understand how data or commands move from source to destination.
• Show the integration path by connecting components across layers. Route connectors clearly between layers and between peer components when needed.
• Use concise connector labels for trigger, protocol, contract, routing, transformation, retry, acknowledgement, or ownership details.
• For cross-layer flows, connect components from bottom-to-top or top-to-bottom using straight vertical orthogonal connectors whenever possible. Use side connectors only when vertical routing would cross another component or label.
• Route every connector around components, not through components. Use explicit orthogonal `mx

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Future-CX
• Source: Future-CX/AI-Architecture-Toolkit
• License: MIT

Install and usage instructions live in the source repository linked above.