drawthe.net
Draw network/architecture diagrams (AWS, Azure, Cisco) from a natural-language description or from a proposed system architecture, using the drawthe.net MCP server's YAML DSL and icon tools. Use this skill whenever the user asks to "draw a diagram", "create an architecture diagram", "visualize this infrastructure", "sketch the network", or asks you to propose/illustrate a system design.
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Check it deeper on your machine
It has changed since its scan on 11 Nov 2026.
As a Claude Code plugin, install it and then ask Claude Code:
/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/cidrblock/drawthe.net with scanskillsafety
Or from a terminal, clone it and run it:
git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/cidrblock/drawthe.net'
It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.
Badge for your README
Markdown
[](/listings/cidrblock--drawthe-net)HTML
<a href="/listings/cidrblock--drawthe-net"><img src="/api/listings/cidrblock--drawthe-net/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
Run `npm run dev` to open the editor locally.
Clear the editor and paste the following in, then click draw or ctrl-enter.
diagram:
fill: "white"
rows: 5
columns: 5
title:
author: Your Name
company: Comapny Name
color: black
logoFill: white
logoUrl: https://upload.wikimedia.org/wikipedia/commons/b/b3/Wikipedia-logo-v2-en.svg
text: Hello world
subText: additional information about this diagram
type: bar
stroke: black
# Set defaults for icons, groups, connections
iconDefaults: &iconDefaults
color: black
fill: white
stroke: black
iconFamily: aws
groupDefaults: &groupDefaults
fill: "none"
color: black
stroke: black
connectionDefaults: &connectionDefaults
color: "black"
stroke: "black"
noteDefaults: ¬eDefaults
color: black
fill: white
stroke: black
xAlign: center
yAlign: center
# Add the icons
icons:
dns: {<<: *iconDefaults, icon: net_route53_hostedzone, x: 2, y: 3 }
lb: {<<: *iconDefaults, icon: cmpt_elasticloadbalancing, y: "-1" }
server1: {<<: *iconDefaults, icon: cmpt_ec2_instance, x: "-1", y: "-1" }
server2: {<<: *iconDefaults, icon: cmpt_ec2_instance, x: "+1" }
server3: {<<: *iconDefaults, icon: cmpt_ec2_instance, x: "+1" }
# Add the groups
groups:
servers: { <<: *groupDefaults, name: Web Servers, members: [server1, server2, server3] }
# Add connections
connections:
- { <<: *connectionDefaults, endpoints: [dns, lb] }
- { <<: *connectionDefaults, endpoints: [lb, servers] }
notes:
note1:
<<: *noteDefaults
x: 0
y: 3
text: "##Note\n\nThis is the text for the note."Hopefully, the following diagram is created.
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
SKILL.md · Manifest · 250 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
- ---
- name: drawthe.net
- description: Draw network/architecture diagrams (AWS, Azure, Cisco) from a natural-language description or from a proposed system architecture, using the drawthe.net MCP server's YAML DSL and icon tools. Use this skill whenever the user asks to "draw a diagram", "create an architecture diagram", "visualize this infrastructure", "sketch the network", or asks you to propose/illustrate a system design.
- ---
- # drawthe.net diagram authoring skill
- This skill teaches an agent how to turn a description (or a proposed
- architecture) into a drawthe.net YAML diagram and render it via the
- drawthe.net MCP server's tools. The result should be a build blueprint:
- someone reading it should understand what to provision, how traffic and
- data move, what is required versus optional, and what to configure next.
- ### ARCHITECTURE DIAGRAM DESIGN SYSTEM & AESTHETIC DIRECTIVES
- When authoring system architecture diagrams in YAML, adhere strictly to these architectural visual design principles:
- #### 1. Architectural Layout & Directional Flow
- * **Determine the Primary Axis:**
- * **Top-to-Bottom (Layered Systems):** Use for Tiered/Client-Server architectures (Presentation → Processing/Logic → Storage → External Infrastructure).
- * **Left-to-Right (Data & Workflow Pipelines):** Use for event-driven systems, ETL pipelines, integration flows, or user journey sequences.
- * **Dedicated Cross-Cutting Rows/Columns:** Place auxiliary or cross-cutting services (e.g., Logging, Authentication, Telemetry, Storage) on a dedicated side column or bottom row rather than interspersing them within the core flow.
- * **Spatial Breathability:** Always leave 1–2 empty grid steps between connected components to provide space for connection lines without crossing icons or text.
- #### 2. Restrained Color System & Contrast
- * **Canvas:** Use the established white canvas (`white`) unless the user requests another treatment.
- * **Default Elements:** Use dark readable text and lines (`black` for labels and `#334155` for connections/borders). Do not use the historical orange renderer defaults for blueprint styling.
- * **Containers:** Use light-gray or very lightly tinted fills with a consistent border, such as `#F1F5F9` with `#94A3B8`. Container color should establish hierarchy without competing with the topology.
- * **Icons:** Preserve native vendor icon artwork. Do not impose a diagram-wide accent palette or override icon fills/strokes unless the selected icon has been previewed and the override is intentional.
- #### 3. Domain Grouping & Boundaries
- * **Container Enclosure:** Wrap related components in named groups (e.g., Services, Data Domain, External System, Core Boundary).
- * **Line Style Rules:**
- * **Solid Lines:** Direct synchronous calls, primary system processes, or hard structural boundaries.
- * **Dashed Lines (`strokeDashArray: [4, 4]`):** Asynchronous events, metadata/telemetry flows, or logical/trust boundaries.
- * **Group Headers:** Choose one placement for all group names, commonly `bottomMiddle` for north-to-south flows, and keep it consistent unless a collision is unavoidable.
- #### 4. Typography & Label Symmetry
- * **Unified Alignment:** Standardize `textLocation` across the entire diagram. Use the selected group/icon placement consistently; the established blueprint default is `bottomMiddle`. Never mix alignments within the same diagram unless a documented collision makes it unavoidable.
- * **Readable Display Names:** Always use explicit, concise display text with the `text:` attribute (e.g., `text: "Auth Service"`) instead of raw technical identifiers (e.g., `auth_svc_node_01`).
- #### 5. Connection Line Discipline
- * Align connected components along straight grid lines to eliminate diagonal line clutter.
- * Group multi-destination fan-outs neatly through shared alignment rather than overlapping multiple connection lines across the canvas.
- ## Prerequisites
- The drawthe.net MCP server must be connected and expose these tools:
- - `get_dsl_reference` — returns the full YAML DSL syntax reference.
- - `list_icon_families` — lists available icon families and icon counts.
- - `list_icons` — lists/searches icon names within a family.
- - `get_icon` / `get_icon_svg` — preview a specific icon (PNG/SVG) to confirm it looks right before using it.
- - `render_diagram` — renders a YAML diagram to PNG or SVG.
- ## Procedure
- 1. **Read the DSL reference first.** Call `get_dsl_reference` before
- writing any YAML if you have not already seen it in this conversation.
- Do not guess at the syntax — the `diagram`, `title`, `icons`, `notes`,
- `groups`, and `connections` sections each have specific required and
- optional fields.
- 2. **Identify the components in the description.** Break the request down
- into concrete entities (servers, load balancers, databases, gateways,
- VPCs/VNets, users, external services, etc.) and the connections between
- them. If the user proposes an architecture rather than describing an
- existing one, design a sensible one first (reasonable tiers, redundancy,
- networking boundaries), then diagram it.
- State the architecture assumption in the title or a note when the
- request is ambiguous. For example, RHDH on ROSA is materially different
- from RHDH on EKS or RHDH on EC2.
- Design the blueprint before choosing icons. Organize it into these layers
- where they apply:
- - prerequisites and network foundation: account, region, VPC, AZs,
- public/private subnets, routing, security groups, IAM, and certificates;
- - request path: users, DNS, edge/load balancer, ingress, and application;
- - platform: cluster, namespaces, operators, ingress controller, and
- workload replicas;
- - dependencies: identity, database, secrets, object storage, registries,
- source control, and observability;
- - build notes: required configuration, optional choices, and an ordered
- implementation sequence.
- Do not draw every plausible service. Include a component only when it
- answers a deployment question, and mark it as required, optional, or
- external in its label or notes.
- 3. **Choose the right icon family based on vendor keywords in the
- request** — there is no fixed default family. Inspect the request for
- vendor/platform signals:
- - AWS services/terms → `aws2026` (preferred, current) or `aws` (legacy).
- - Azure services/terms → `azure2026` (preferred), or `azureCloud` /
- `azureEnterprise` (legacy).
- - Cisco/network hardware terms → `cisco2026` (preferred) or `cisco` (legacy).
- - Generic/vendor-neutral request → pick whichever family has the closest
- conceptually matching icon; prefer the modern `*2026` families.
- Call `list_icon_families` if you're unsure what's available.
- 4. **Never invent an icon name.** For every component, call `list_icons`
- with the family and a keyword query (e.g. `query: "load_balanc"`) to find
- the real icon name before writing an `icon:` reference in YAML. Use
- `get_icon` or `get_icon_svg` to visually confirm an ambiguous match
- before committing to it.
- 5. **Always prefer a meaningful, accurate icon over a generic
- placeholder.** If an exact icon for a component doesn't exist in the
- chosen family, search for the closest conceptually similar icon (e.g. a
- generic "server" or "compute" icon for an unlisted service type) rather
- than defaulting to a plain box or an unrelated icon. Only fall back to a
- generic shape (e.g. via `notes`) if truly no reasonable icon exists in
- any relevant family.
- 6. **Write the YAML diagram** using the DSL: define `diagram` (grid size,
- background), optionally `title`, then `icons` (with `x`/`y` grid
- coordinates, using relative positions like `x: "+1"` where convenient),
- `groups` to box related components together, and `connections` between
- icon keys. Use YAML anchors for repeated styling if helpful.
- Start from the light, readable style below unless the user explicitly
- requests a different visual treatment:
- diagram:
- fill: "white"
- gridLines: false
- groupPadding: 0.4
- title:
- color: "black"
- fill: "white"
- logoFill: "none"
- stroke: "black"
- type: "box"
- heightPercentage: 6
- group: &group
- - { color: "black", stroke: "#94a3b8", fill: "#f1f5f9" }
- connection: &connection
- color: "#334155"
- stroke: "#334155"
- Use `groups` as a list of objects, not a map. Layer groups must be
- visibly distinct from a white canvas. For a hierarchy, use a restrained
- sequence of light fills so the layers can be scanned without competing
- with the topology, for example: foundation `#eaf2f8`, request/data flow
- `#eef6ee`, platform `#fff7e6`, and workloads/dependencies `#f1f5f9`.
- Keep the border treatment consistent across all groups. Use
- Choose one `textLocation` for every group heading before laying out the
- diagram, and use it consistently across the hierarchy. `bottomMiddle` is
- often a good choice for north-to-south flows because headings sit outside
- the incoming edge of each layer. Label placement must be consistent
- unless consistency is impossible because the label is blocked. If a
- connection, icon, or note crosses or obscures a heading, first fix the
- layout by moving the affected component, changing spacing, or rerouting
- the connection. Only when those fixes cannot remove the collision may one
- heading use another position, and that exception must be documented.
- Do not set `iconFill`, `iconStroke`,
- or `preserveWhite` globally without previewing the selected family first;
- those overrides can erase or wash out native vendor icon artwork.
- Never rely on renderer defaults for presentation output: the historical
- defaults use orange and are intended for backward compatibility. Always
- specify a background, title colors, group styling, and connection colors.
- For blueprint icons, set `color: "black"`, `fill: "white"`, and a dark
- `stroke` explicitly so labels remain readable around vendor artwork.
- Every icon must have an explicit human-readable `text` label. Never
- expect the viewer to infer a service from an icon or filename. Keep icon
- labels short (normally one to three words), such as `RHDH`, `ROSA`,
- `PostgreSQL`, and `Route 53`; put `(required)`, `(optional)`, or
- `(external)` in notes or a legend rather than shrinking a long label until
- it becomes unreadable. Use notes for configuration detail rather than
- packing prose into icon labels.
- Use connections to show meaningful flows, not merely membership. Add
- notes that explain numbered flows such as `1. DNS resolves the public
- hostname`, `2. ingress terminates TLS`, and `3. RHDH accesses PostgreSQL
- and secrets`. Avoid a dense web of lines from one central icon to every
- service; group dependencies and use notes to explain shared access.
- For layered network, platform, or application diagrams, orient the
- dominant data or request flow north-to-south: producers, users, or
- external/WAN edge at the top; routing, security, or core next; access,
- platform, or processing tiers below that; and databases, storage, or
- downstream consumers at the bottom. If the system's dominant flow is
- different, state the assumption and preserve one clear direction rather
- than mixing vertical and horizontal reading orders. Reuse the same x
- coordinates across tiers wherever devices form a logical column or pair.
- Inspect every group heading against the rendered connection paths and
- icons. Do not leave a label underneath a line or behind an icon. Prefer
- repairing the layout while preserving the chosen label position; use a
- different position only when the collision cannot otherwise be removed.
- Within each layer, calculate and use an intentional spacing rhythm for
- sibling icons. Equal-role nodes should use equal x intervals unless a
- documented architectural grouping requires otherwise. Do not move one
- icon to solve a collision and leave the remaining layer on an accidental
- set of unequal gaps; rebalance the entire layer and update its connections.
- For nontrivial diagrams, perform at least three render-review passes:
- render the initial layout, inspect the actual SVG and PNG/SVG preview,
- correct spacing/labels/connections, and render again. Repeat until the
- topology, hierarchy, label placement, and whitespace are stable. Do not
- deliver a diagram based only on YAML inspection or a single successful
- render command.
- 7. **Render with `render_diagram`.** Default to `format: png` unless the
- user asks for SVG (e.g. for further editing). Always read the
- `warnings` returned in the response — a warning like "Icon not found"
- means a placeholder was drawn instead of a real icon; if you see one,
- go back to `list_icons` and fix the reference, then re-render.
- 8. **Run the blueprint quality gate.** Before presenting the result, verify
- that the image answers these questions:
- - What deployment target and assumptions are shown?
- - What must be provisioned first?
- - How does a user reach the application?
- - Where do authentication, persistence, secrets, and images come from?
- - Which components are required, optional, or external?
- - What should the reader configure next?
- Reject and revise any diagram with unlabeled icons, unexplained vendor
- artwork, ambiguous flows, decorative components, or a layout that cannot
- be read at normal viewing size.
- 9. **Iterate.** If the rendered layout looks cramped, overlapping, or
- components are misaligned, adjust the `diagram` grid size (`rows`/
- `columns`) or icon `x`/`y` coordinates and re-render rather than leaving
- a poor-quality diagram. Check the actual image preview, not just the
- tool response: the canvas must be light and opaque, labels must be
- readable, groups must not overlap unrelated groups, and connection lines
- must not dominate the diagram. Increase the grid size before shrinking
- labels or packing more components into one cell.
- 11. **Always deliver the source YAML.** After the diagram passes the quality
- gate, save the complete YAML as a new `.yaml` document and provide that
- document to the user alongside the rendered image. Never provide only a
- screenshot or an inline abbreviated snippet; the YAML is the editable
- blueprint the user will build from and revise later.
- ## Notes
- - The MCP server runs locally over stdio (`npm run mcp` in this repo, or
- configure your MCP host to spawn `npx tsx mcp/server.ts` from the repo
- root). It has no network dependency for rendering.
- - Icon families and counts as of this writing: `aws` (231), `aws2026`
- (303), `azure2026` (636), `azureCloud` (208), `azureEnterprise` (101),
- `cisco` (295), `cisco2026` (295). Always confirm current counts/names via
- `list_icon_families`/`list_icons` rather than relying on this list, since
- icon sets may be refreshed over time.
README.md · README · 633 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
- ## drawthe.net: Decent looking diagrams for engineers.
- drawthe.net draws network diagrams dynamically from a text file describing the placement, layout and icons. Given a yaml file describing the hierarchy of the network and it's connections, a resulting diagram will be created.
- 
- ## Motivation
- Complex network diagrams typically involve specific place of icons, connections and labels using a tool like Visio or OmniGraffle using a mouse and constantly zooming in and out for single pixel placement. The goal behind drawthe.net, was to be able to describe the digram in a text file and have it rendered in SVG in the browser.
- I simply wanted to be able to draw network diagrams as fast as it could be done on a dry-erase board without using a mouse.
- ## Development
- Requires Node.js 20.19+, 22.12+, or 24+.
- ```
- npm install
- npm run dev # start the Vite dev server
- npm run build # typecheck + production build to dist/
- npm run lint # eslint
- npm run typecheck # tsc --noEmit
- npm run render -- examples/NTP.yaml out.svg # headless YAML -> SVG render (Node/CLI)
- ```
- The renderer core (`src/renderer`) has no browser dependency and can run headlessly in
- Node via `src/cli/render.ts` - this is the seam future automation/agent tooling will use.
- The app has three static entry points, built by Vite as a multi-page app:
- - `index.html` - the YAML editor (Monaco + JSON Schema diagnostics and live preview)
- - `fullscreen.html` - a popup window that renders the design shared by `index.html` (`window.opener`)
- - `render.html` - renders a single YAML doc from a `?doc=` (bundled example) or `?key=` (saved doc) query param, with no editor UI
- For embedding diagrams in Hugo posts, see [the Hugo shortcode integration](integrations/hugo/README.md). It inlines SVG generated by the headless CLI from a page-bundle YAML resource.
- The browser editor validates YAML syntax and documented diagram properties against a JSON Schema. Its diagnostics panel also reports renderer warnings, including unresolved icons and overlapping groups.
- Reusable icon defaults can opt into strict schema validation with `type: icon`. Unknown properties on the tagged anchor and on icon mappings that inherit it are reported as editor diagnostics; untagged custom anchors remain extensible. For example:
- ```yaml
- cisco: &cisco
- type: icon
- iconFamily: cisco
- icon: router
- icons:
- edge: {<<: *cisco, x: 1, y: 1}
- ```
- ### npm package releases
- Publishing a non-prerelease GitHub Release triggers the npm publish workflow. Configure npm Trusted Publishing for GitHub Actions with organization `cidrblock`, repository `drawthe.net`, and workflow filename `publish-npm.yml`; allow direct publishing with `npm publish`. No long-lived CI token is required. Update the package version, then publish a GitHub Release tagged `v<version>` (for example, `v2.0.3`). The workflow runs lint, typecheck, and build before publishing; npm generates provenance automatically for trusted publishes.
- Install the package and render a diagram from another project with:
- ```sh
- npm install --save-dev drawthe.net
- npx drawthe-net diagrams/network.yaml docs/network.svg --width=1200 --height=800
- ```
- ### Podman container image
- Stable GitHub Releases publish versioned images and update the `latest` tag in GHCR. For the first image publication, change the package visibility to **Public** in the GitHub package settings so Podman can pull it without authentication.
- ```sh
- # Run the web editor at http://localhost:5173
- podman pull ghcr.io/cidrblock/drawthe.net:latest
- podman run --rm -p 5173:5173 ghcr.io/cidrblock/drawthe.net:latest ui
- # Convert YAML to SVG
- podman run --rm \
- --userns=keep-id \
- --user "$(id -u):$(id -g)" \
- -v "$PWD:/workspace:Z" \
- -w /workspace \
- ghcr.io/cidrblock/drawthe.net:latest \
- diagrams/network.yaml docs/network.svg --width=1200 --height=800
- ```
- Use a versioned tag such as `ghcr.io/cidrblock/drawthe.net:v2.0.3` instead of `latest` for a pinned image.
- ## Quick start
- Run `npm run dev` to open the editor locally.
- Clear the editor and paste the following in, then click draw or ctrl-enter.
- ```yaml
- diagram:
- fill: "white"
- rows: 5
- columns: 5
- title:
- author: Your Name
- company: Comapny Name
- color: black
- logoFill: white
- logoUrl: https://upload.wikimedia.org/wikipedia/commons/b/b3/Wikipedia-logo-v2-en.svg
- text: Hello world
- subText: additional information about this diagram
- type: bar
- stroke: black
- # Set defaults for icons, groups, connections
- iconDefaults: &iconDefaults
- color: black
- fill: white
- stroke: black
- iconFamily: aws
- groupDefaults: &groupDefaults
- fill: "none"
- color: black
- stroke: black
- connectionDefaults: &connectionDefaults
- color: "black"
- stroke: "black"
- noteDefaults: ¬eDefaults
- color: black
- fill: white
- stroke: black
- xAlign: center
- yAlign: center
- # Add the icons
- icons:
- dns: {<<: *iconDefaults, icon: net_route53_hostedzone, x: 2, y: 3 }
- lb: {<<: *iconDefaults, icon: cmpt_elasticloadbalancing, y: "-1" }
- server1: {<<: *iconDefaults, icon: cmpt_ec2_instance, x: "-1", y: "-1" }
- server2: {<<: *iconDefaults, icon: cmpt_ec2_instance, x: "+1" }
- server3: {<<: *iconDefaults, icon: cmpt_ec2_instance, x: "+1" }
- # Add the groups
- groups:
- servers: { <<: *groupDefaults, name: Web Servers, members: [server1, server2, server3] }
- # Add connections
- connections:
- - { <<: *connectionDefaults, endpoints: [dns, lb] }
- - { <<: *connectionDefaults, endpoints: [lb, servers] }
- notes:
- note1:
- <<: *noteDefaults
- x: 0
- y: 3
- text: "##Note\n\nThis is the text for the note."
- ```
- Hopefully, the following diagram is created.
- 
- ## Overview
- The YAML document has major sections which describe the diagram. These are the basic root types:
- **diagram**: The page on which the diagram will be drawn.
- **title**: Information about the diagram.
- **icons**: Objects to be placed on the diagram.
- **notes**: Text boxes with information.
- **connections**: Lines drawn between objects.
- **groups**: Collections of objects.
- ### Custom sections
- The YAML document above has the following additional custom sections:
- **iconDefaults**: A YAML anchor which describes common icon attributes which will be inherited later.
- **groupDefaults:** A YAML anchor which describes common group attributes which will be inherited later.
- **connectionDefaults:** A YAML anchor which describes common connection attributes which will be inherited later.
- **noteDefaults:** A YAML anchor which describes common note attributes which will be inherited later.
- YAML reference: https://en.wikipedia.org/wiki/YAML
- ### Placement
- Icons and notes have the following attributes, which allows the object to be placed and sized on the place.
- **x:** The X coordinate value.
- **y:** The Y coordinate value.
- **w:** The width of the object, in X coordinate steps, extending right toward the right side of the screen.
- **h:** The height of the object, in Y coordinate steps, extending down toward the bottom of the diagram.
- ### Basic styling
- Common to most entities are the following:
- **color:** The color of the text.
- **fill:** Sets the color inside the object.
- **stroke:** Sets the color of the line drawn around the object.
- ### Icons
- The following icon families are available:
- - aws
- - azureCloud
- - azureEnterprise
- - cisco
- - aws2026 (current AWS architecture service icons, full-color pictograms)
- - azure2026 (current Azure public service icons, unified set replacing the separate cloud/enterprise split)
- - cisco2026 (current revision of the same Cisco network topology icon set)
- Icons have the following basic attributes:
- **iconFamily:** The family from which to pull the icon.
- **icon:** The name of the icon within the family.
- **iconFill:** Set the color inside the icon.
- **iconStroke:** Sets the color of the line drawn within the icon.
- Each icon and icon family may behave differently when the fill and stroke are applied, review the icon cut sheets to see the icons available for each family with the iconFill and iconStroke set.
- Note: the icon sets bundled with this project are redistributed legally, but each vendor's icon set carries its own usage terms (some restrict recoloring or other alteration of the icon itself). This tool lets you apply `iconFill`/`iconStroke`/`preserveWhite` to any icon family regardless of those terms - see [Icon licensing](#icon-licensing) below. It is your responsibility to comply with the license that applies to the icon family you use.
- ### Notes
- Notes can be plain text or markdown. See the 'notes' example for the use of markdown. (Indentation is critical when using markdown for notes.)
- ## Additional examples
- Run `npm run dev` and choose an example from the editor menu to explore different diagram layouts and styles.
- ### Troubleshooting
- The most common mistake I've made is in the YAML syntax. The developer tools window in chrome should give you an idea of what might be wrong.
- It's also handy to comment out lines (with a #) to see where the issue may be.
- ## AI assistance (MCP server + skill)
- drawthe.net includes an MCP (Model Context Protocol) server that lets AI
- coding agents draw diagrams directly, either from a natural-language
- description or by illustrating a proposed system architecture.
- ### Running the MCP server
- ```bash
- npm run mcp
- ```
- This starts the server over stdio (`mcp/server.ts`). Point your MCP-compatible
- agent host at this command (or `npx tsx mcp/server.ts` from the repo root) to
- connect. The server has no network dependency — rendering happens locally.
- For an MCP host configuration, use the repository root as the working
- directory and spawn `npm run mcp`. The server communicates over stdio; it does
- not expose an HTTP port.
- ### Tools exposed
- - `get_dsl_reference` — full YAML DSL syntax reference.
- - `list_icon_families` — lists available icon families (`aws`, `aws2026`,
- `azure2026`, `azureCloud`, `azureEnterprise`, `cisco`, `cisco2026`) and icon
- counts.
- - `list_icons` — search icon names within a family.
- - `get_icon` / `get_icon_svg` — preview a specific icon (PNG/SVG).
- - `render_diagram` — renders a YAML diagram to PNG or SVG, returning any
- warnings (e.g. unresolved icon references).
- ### Skill
- [`SKILL.md`](SKILL.md) documents the procedure an agent should follow: read
- the DSL reference, choose an icon family based on vendor keywords in the
- request, look up real icon names (never invent one), prefer accurate/similar
- icons over generic placeholders, then render and iterate on warnings. It also
- requires agents to produce a deployment blueprint rather than an icon collage:
- use explicit labels, meaningful flow direction, grouped layers, intentional
- spacing, collision-free connections, build notes, and multiple render-review
- passes. Agents must save and provide the complete editable YAML source as a
- new document alongside the rendered image.
- ### Example blueprint
- [`examples/hybrid-platform-reference-blueprint.yaml`](examples/hybrid-platform-reference-blueprint.yaml)
- demonstrates a complex hybrid platform with AWS edge services, a private Cisco
- spine-leaf fabric, redundant application services, data services, backups, and
- solid versus dashed connections. Render it locally with:
- ```bash
- npx tsx src/cli/render.ts \
- examples/hybrid-platform-reference-blueprint.yaml \
- /tmp/hybrid-platform-reference.svg \
- --width=2600 --height=1900
- ```
- The same YAML can be passed to the MCP server's `render_diagram` tool for PNG
- or SVG output.
- ## API Reference
- ### Diagram
- `diagram`:
- - `aspectRatio`: (defualt 1:1) The width:height ratio of the diagram.
- - `columns`: (default: 10) The number of columns in the diagram.
- - `fill`: (default: orange) The background color of the diagram.
- - `gridLines:` (default: true)
- - `true`: Show the gridlines.
- - `false`: Hide the gridlines.
- - `gridPaddingInner`: (default: .4) The ration of the icon box size to the spacing between the boxes.
- - `groupPadding`: (default: .33) The percentage of the space between icons to use for the group boundary.
- - `iconTextRatio`: (default: .33) The percentage of the icon box to allocate to the icon text.
- - `iconLabelFontSize`: Optional diagram-wide icon label size in px; defaults to automatic fitting.
- - `connectionLabelFontSize`: Optional diagram-wide connection label size in px; defaults to automatic sizing.
- - `margins`:
- - `top`: (default: 20) The top margin of the diagram in px.
- - `right`: (default: 20) The right side margin in px.
- - `bottom`: (default: 50) The bottom margin in px.
- - `left`: (default: 20) The left side margin in px.
- - Example: `margins: {top: 20, right: 20, bottom: 50, left: 20 }`
- - `rows:` (default: 10) The number of rows.
- ### Title
- `title`:
- - `author`: (default: "Bradley A. Thornton") The author of the diagram.
- - `color`: (default: orange) The title text color.
- - `company`: (default: Self) The company name.
- - `date`: (default: `new Date().toLocaleDateString()`) The date for the diagram.
- - `fill`: (default: orange) The title fill color.
- - `heightPercentage`: (default: 6) The percentage of the diagram height to use for the title.
- - `logoFill`: (default: orange) The color behind the logo.
- - `logoUrl`: (default: `/images/radial.png`) The URL for the logo.
- - `stroke`: (default: orange) The line color for the title.
- - `subText`: The title subtext.
- - `text`: The title text.
- - `type`: (default: box). The title type.
- - `box`: Draw a box around the title using the stroke color.
- - `bar`: Draw a line above the title using the stroke color.
- - Example: `type: bar`
- - `version`: (default: 1.01) The version of the diagram.
- ### Icons
- The icon's key will be used as the text value, therefore icon names have to be unique.
- `icons`:
- - `color`: (default: orange) The icon text color.
- - `fill`: (default: orange) The fill color for the icon bounding box.
- - `h`: (default: 1) The height of the icon.
- - `icon`: (default: none) The name of the icon in the icon family.
- - `iconFamily`: (default: none) The name of the icon family from which to get the icon.
- - `iconUrl`: Optional custom HTTPS URL pointing directly to an image file, or a base64 image data URL (`SVG`, `PNG`, `JPEG`, `GIF`, or `WebP`, up to 5 MiB). It replaces `iconFamily`/`icon`; an HTML page URL (including a Wikipedia media page) is not an image URL. SVG input is sanitized before embedding. Browser loads require CORS permission; headless HTTPS loads are limited to publicly routed hosts.
- - `labelFontSize`: Optional icon label size in px, overriding `diagram.iconLabelFontSize`.
- - `iconFill`: (default: use the colors specified in the icon's svg file) The fill color for the icon.
- - `iconStroke`: (default: use the colors specified in the icons's svg file) The color of the lines in the icon.
- - `iconStrokeWidth`: (default: use the colors specified in the icons's svg file) The size of the lines within the icon.
- - `metadata`: (default: none) A hash for the mouse over metadata (see the example)
- - `url`: If provided, with HTTP GET the metadata, expects a simple json object as a response.
- - Note: The URL can contain {{ var }} for replacements, where var is the key or another attribute of the icon.
- - `errorText`: (default: HTTP status and text) Custom error message if HTTP GET fails.
- - `preserveWhite`: (default: none) Don't change white in the source svg file. (this is useful for the cisco icon family)
- - `stroke`: (default: orange) The color of the icon bounding box line.
- - `strokeDashArray`: (default [0,0]) The stroke dash size in px and the spacing between the dashes in px.
- - `text`: (default: none) Instead of the the icon's key use this text label for the icon label.
- - `textLocation`: (default: bottomMiddle) The location of the text for the icon.
- - `bottomLeft`: Position the text along the bottom, in the left corner.
- - `bottomMiddle`: Position the text along the bottom, centered.
- - `bottomRight`: Position the text along the bottom, in the right corner.
- - `center`: Position the text in the center of the bounding box.
- - `leftBottom`: Position the text along the left side, in the bottom corner.
- - `leftMiddle`: Position the text along the left side, centered.
- - `leftTop`: Position the text along the left side, in the top corner.
- - `rightBottom`: Position the text along the right side, in the bottom corner.
- - `rightMiddle`: Position the text along the right side, centered.
- - `rightTop`: Position the text along the right side, in the top corner.
- - `topLeft`: Position the text along the top, in the left corner.
- - `topMiddle`: Position the text along the top, centered.
- - `topRight`: Position the text along the top, in the right corner.
- - Example: `textLocation: rightMiddle`
- - `url`: (default: none) A link/URL for the icon text
- - `w`: (default: 1) The width of the icon.
- - `x`: (default: none) The x-coordinate location of the icon.
- - `n`: An absolute position.
- - `"+n"`: A value added from the previous icon's x value.
- - `"-n"`: A value subtracted from the previous icon's x value.
- - Example: `{x: "+5", y: 0}`
- - `y`: (default: none) The y-coordinate location of the icon.
- - `n`: An absolute position.
- - `"+n"`: A value added from the previous icon's x value.
- - `"-n"`: A value subtracted from the previous icon's x value.
- - Example: `{x: 0, y: "+5"}`
- ### Groups
- Groups are drawn in order, so place groups that should have a lower z-index at the top of the group array. A group is the smallest rectangle that includes it's members, so in the case of large groups, it will only be necessary to include the upper-left and lower-right most members.
- `groups`:
- - `color`: (default: orange) The group text color.
- - `fill`: (default: orange) The fill color for the group.
- - `members`: (default: none) An array of members for the group.
- - Note: A member can be another group or icon.
- - Example: ` inner: { <<: *group, stroke: none, fill: "white", textLocation: "rightMiddle", members: [T1, T4, NSG1] }`
- - `padding`: Optional inner padding, as a fraction of the gap between grid cells (default: `diagram.groupPadding`).
- - `paddingTop`, `paddingRight`, `paddingBottom`, `paddingLeft`: Optional side-specific padding values overriding `padding`.
- - `margin`: Optional outer margin, in the same gap units, that a parent group reserves around this group and that is kept inside the canvas.
- - `marginTop`, `marginRight`, `marginBottom`, `marginLeft`: Optional side-specific margins overriding `margin`.
- - `fontSize`: Optional label size in px. The label always sits in the padding on its `textLocation` side; that side grows to fit it, and the font shrinks if the label is longer than the side.
- - `name`:
- - `stroke`: (default: orange) The color of the group's bounding box line.
- - `strokeDashArray`: (default [0,0]) The stroke dash size in px and the spacing between the dashes in px.
- - `textLocation`: (default: bottomMiddle) The location of the text for the icon.
- - `bottomLeft`: Position the text along the bottom, in the left corner.
- - `bottomMiddle`: Position the text along the bottom, centered.
- - `bottomRight`: Position the text along the bottom, in the right corner.
- - `center`: Position the text in the center of the bounding box.
- - `leftBottom`: Position the text along the left side, in the bottom corner.
- - `leftMiddle`: Position the text along the left side, centered.
- - `leftTop`: Position the text along the left side, in the top corner.
- - `rightBottom`: Position the text along the right side, in the bottom corner.
- - `rightMiddle`: Position the text along the right side, centered.
- - `rightTop`: Position the text along the right side, in the top corner.
- - `topLeft`: Position the text along the top, in the left corner.
- - `topMiddle`: Position the text along the top, centered.
- - `topRight`: Position the text along the top, in the right corner.
- - Example: `textLocation: rightMiddle`
- ### Connections
- Connections are an array of individual connections. The order is insignificant because connections will always be drawn from left to right.
- `connections`:
- - `color`: (default: orange) The connection text color.
- - `curve`: (default: curveLinear) The type of connection to draw.
- - `curveLinear`: Draws a line directly connecting the endpoints.
- - `curveStep`: Draws a line consisting of alternating horizontal and vertical lines. The y-value changes at the midpoint of each pair of adjacent x-values.
- - `curveStepAfter`: Draws a line consisting of alternating horizontal and vertical lines. The y-value changes after the x-value.
- - `curveStepBefore`: Draws a line consisting of alternating horizontal and vertical lines. The y-value changes before the x-value.
- - `endpoints`: An array of 2 icons, groups or notes to draw connections between.
- - Note: When an endpoint is a group, lines will be drawn to each group member.
- - Example: `endpoints: [spines:40Gb,leaves:40Gb]`
- - Example: `endpoints: [allNTP:sync, allNTP:sync]`
- - **labels:** Labels can be appended to the endpoint names and will be added to the line.
- Example: `endpoints: ["router:eth0", "firewall:eth1"]`
- - `labels`: Optional list of labels placed on one connection path. Each item
- supports `text`, `position` (`start`, `middle`, or `end`), `side` (`over` or `under`), and `fontSize`.
- `side` is relative to the path direction; it defaults to `over`.
- Example: `labels: [{text: "HTTPS", position: start}, {text: "443", position: middle, side: under}, {text: "primary", position: end}]`
- - `label`: Legacy single-label form; equivalent to one `labels` item.
- - `labelPosition`: Legacy placement field for `label`.
- - `labelSide`: Legacy side field for `label` (`over` or `under`, default: `over`).
- - `endpointLabelSide`: Side for port labels in endpoint strings such as `router:eth0` (`over` or `under`, default: `over`).
- - `labelFontSize`: Legacy font-size field for `label`.
- - `connectionLabelFontSize`: Diagram-wide default overridden by connection `labelFontSize` or an individual `labels[].fontSize`.
- - `lineStyle`: Optional canned line style: `solid` (default), `dashed`, `dotted`, `dashDot`, or `double`. `double` draws two rails around the existing center path, so curves and labels keep their current geometry.
- - `stroke`: (default: orange) The line color for the connection.
- - `strokeDashArray`: Optional custom dash pattern in px, overriding the canned dash pattern for the selected `lineStyle`.
- - `strokeWidth`: Line thickness in px; `double` defaults to 4px overall.
- Curve definitions are directly from d3.js: https://github.com/d3/d3-shape (only a subset are implemented.)
- ### Notes
- See the example call 'Notes' for examples of these attributes.
- `notes`:
- - `alignItems`: (default: flex-start) This defines the default behaviour for how flex items are laid out along the cross axis on the current line. Think of it as the justify-content version for the cross-axis (perpendicular to the main-axis).
- - `flex-start`: cross-start margin edge of the items is placed on the cross-start line
- - `flex-end`: cross-end margin edge of the items is placed on the cross-end line
- - `center`: items are centered in the cross-axis
- - `baseline`: items are aligned such as their baselines align
- - `stretch`: stretch to fill the container (still respect min-width/max-width)
- - `color`: (default: orange) The note text color.
- - `fill`: (default: orange) The fill color for the note bounding box.
- - `flexDirection`: (defualt: column) The direction of the note.
- - `row`: left to right
- - `row-reverse`: right to left
- - `column`: stop to bottom
- - `column-reverse`: same as row-reverse but bottom to top
- - `h`: (default: 1) The height of the note.
- - `justifyContent`: (default: flex-start) This defines the alignment along the main axis.
- - `flex-start`: items are packed toward the start line
- - `flex-end`: items are packed toward to end line
- - `center`: items are centered along the line
- - `space-between`: items are evenly distributed in the line; first item is on the start line, last item on the end line
- - `space-around`: items are evenly distributed in the line with equal space around them. Note that visually the spaces aren't equal, since all the items have equal space on both sides. The first item will have one unit of space against the container edge, but two units of space between the next item because that next item has its own spacing that applies.
- - `stroke`: (default: orange) The color of the note bounding box line.
- - `strokeDashArray`: (default [0,0]) The stroke dash size in px and the spacing between the dashes in px.
- - `text`: The text for the note, can be plain or markdown.
- - `textAlign`: (default: left) The text-align property specifies the horizontal alignment of text in an element.
- - `left`: Aligns the text to the left
- - `right`: Aligns the text to the right
- - `center`: Centers the text
- - `justify`: Stretches the lines so that each line has equal width (like in newspapers and magazines)
- - `w`: (default: 1) The width of the note.
- - `x`: (default: none) The x-coordinate location of the note.
- - `n`: An absolute position.
- - `"+n"`: A value added from the previous note's x value.
- - `"-n"`: A value subtracted from the previous note's x value.
- - Example: `{x: "+5", y: 0}`
- - `xAlign`: (default: left) Positions the text along the x axis.
- - `left`: Align the text to the left side of the note's bounding box.
- - Note: This sets `textAlign: "left", alignItems: "flex-start"`
- - `right`: Align the text to the right side of the note's bounding box.
- - Note: This sets `textAlign: "right", alignItems: "flex-end"`
- - `center`: Align the text in the middle of the note's bounding box along the x axis.
- - Note: This sets `textAlign: "center", alignItems: "center"`
- - `y`: (default: none) The y-coordinate location of the note.
- - `n`: An absolute position.
- - `"+n"`: A value added from the previous note's x value.
- - `"-n"`: A value subtracted from the previous note's x value.
- - Example: `{x: 0, y: "+5"}`
- - `yAlign`: (default: top) Positions the text along the y axis.
- - `top`: Align the text to the top of the note's bounding box.
- - Note: This sets `justifyContent: "flex-start"`
- - `bottom`: Align the text to the bottom side of the note's bounding box.
- - Note: This sets `justifyContent: "flex-end"`
- - `center`: Align the text in the middle of the note's bounding box along the y axis.
- - Note: This sets `justifyContent: "center"`
- Each note is an html flexbox. For a good explanation of flex-boxes: https://css-tricks.com/snippets/css/a-guide-to-flexbox/
- Notes can also contain markdown converted by: Showdown.js https://github.com/showdownjs/showdown/wiki/Showdown's-Markdown-syntax
- ## Built with great open source software
- - **Vite:** https://vite.dev
- - **TypeScript:** https://www.typescriptlang.org
- - **Monaco Editor:** https://microsoft.github.io/monaco-editor/
- - **D3.js:** https://d3js.org
- - **js-yaml:** https://github.com/nodeca/js-yaml
- - **Showdown:** https://github.com/showdownjs/showdown
- - **Prettify:** https://github.com/google/code-prettify
- - **Bootstrap:** https://getbootstrap.com
- ## Contributing
- Please do.
- ## Versioning
- 1.0 Initial release.
- ## Authors
- * **Bradley Thornton** - *Initial work* - [cidrblock](https://github.com/cidrblock)
- ## License
- This project is licensed under the MIT License. [MIT License](http://www.opensource.org/licenses/MIT).
- ### Icon licensing
- The MIT License above covers this project's own code. It does not cover the third-party icon
- sets bundled under `public/images/`. Each icon family is provided by its respective vendor
- under that vendor's own usage terms, which are not all identical - some permit recoloring,
- some explicitly prohibit altering the icon, some restrict use to specific contexts (e.g.
- architecture diagrams only).
- This tool's `iconFill`, `iconStroke`, `iconStrokeWidth`, and `preserveWhite` diagram attributes
- will recolor/restyle any icon from any family on request - the tool does not know or enforce
- what each vendor's license permits. **Determining whether a given use (including recoloring,
- redistribution, or publishing a rendered diagram) complies with the applicable icon set's
- license is the user's responsibility.** When in doubt, consult the vendor's current published
- terms for that icon family before redistributing or publishing diagrams built with it.
- ### Icon set provenance
- | Family | Source | Retrieved | Notes |
- | --- | --- | --- | --- |
- | `azure2026` | [Azure architecture icons](https://learn.microsoft.com/en-us/azure/architecture/icons/) (`Azure_Public_Service_Icons` package) | 2026-09 | Bundled Terms of Use PDF permits use in architectural diagrams/training/documentation; don't crop/flip/rotate/distort shape; don't use Microsoft product icons to represent your own product. |
- | `aws2026` | [AWS architecture icons](https://aws.amazon.com/architecture/icons/) ("Icon package", Architecture-Service-Icons, 48px tier) | 2026-09 | AWS's page states the icons are for building architecture diagrams; a machine-readable terms/license file was not bundled in this release and full current wording was not independently verified - review AWS's current published guidance yourself before relying on this family. |
- | `cisco2026` | [Cisco network topology icons](https://www.cisco.com/c/en/us/about/brand-center/network-topology-icons.html) (PMS 3015 color EPS package) | 2026-09 | Cisco's page states "You may use them freely, but you may not alter them" - this is the same underlying icon set as the original `cisco` family (which this project already recolors via `iconFill`/`iconStroke`); see the general disclaimer above. EPS source converted to SVG via Inkscape. |
- Both `azure2026` and `aws2026` are added as new, additional families - the original `aws`,
- `azureCloud`, `azureEnterprise`, and `cisco` families are untouched, so existing diagrams keep
- rendering identically. `cisco2026` refreshes the same Cisco network topology icon set to its
- current (2026) revision, converted from EPS via Inkscape.
- ------------------------
- ### Additional development information
- #### Converting icons (legacy manual process - `aws`, `azureCloud`, `azureEnterprise`, `cisco`)
- 1. copy the icons into a public/images/xxxx directory
- 2. clean up the names a little
- 3. convert from svg to eps and back to svg (this sizes the svg to the bounding window of the icon)
- 4. use svgo to cleaup the svg files
- 5. run `npm run icons:list` to regenerate `public/images/iconFamilies.json`
- azure-cloud
- ```
- cd public/images/azureCloud
- cp ~/Downloads/Microsoft_CloudnEnterprise_Symbols_v2.5_PUBLIC/Symbols/CnE_Cloud/SVG/*.svg .
- rename 's/[^a-zA-Z0-9_.]//g' *.svg
- rename -f 'y/A-Z/a-z/' *.svg
- rename 's/^Azure//g' *.svg
- for i in `pwd`/*.svg; do inkscape $i -E ${i%.svg}.eps; done
- rm *.svg
- for i in `pwd`/*.eps; do inkscape $i -l ${i%.eps}.svg; done
- rm *.eps
- svgo .
- cd ../.. && npm run icons:list
- ```
- AWS
- ```
- mkdir aws && cd aws
- find ~/Downloads/AWS_Simple_Icons_EPS-SVG_v16.2.22/ -type f -name \*.eps -exec cp \{\} . \;
- for i in `pwd`/*.eps; do inkscape $i -l ${i%.eps}.svg; done
- rm *.eps
- rename 's/Amazon//g' *.svg
- rename 's/AWS//g' *.svg
- rename 's/^Analytics/anlt/g' *.svg
- rename 's/^Application-Services/app/g' *.svg
- rename 's/^Compute/cmpt/g' *.svg
- rename 's/^Database/db/g' *.svg
- rename 's/^Developer/dev/g' *.svg
- rename 's/^Enterprise/ent/g' *.svg
- rename 's/^General/gen/g' *.svg
- rename 's/^Internet-Of-Things_IoT/iot_/g' *.svg
- rename 's/^Management-Tools/mgmt/g' *.svg
- rename 's/^Mobile-Services/mbl/g' *.svg
- rename 's/^Networking/net/g' *.svg
- rename 's/^On-Demand-Workforce_MechanicalTurk/odwmt/g' *.svg
- rename 's/^Security-Identity/sec/g' *.svg
- rename 's/^Storage-Content-Delivery/stor/g' *.svg
- rename 's/[^a-zA-Z0-9_.]//g' *.svg
- rename -f 'y/A-Z/a-z/' *.svg
- svgo .
- ```
- #### Refreshing icons (current process - `aws2026`, `azure2026`, `cisco2026`)
- `scripts/icons/refresh-icon-family.ts` replaces the manual steps above with a repeatable pipeline:
- download and unzip the vendor's current icon package yourself (see the provenance table above for
- links), then run:
- ```
- npx tsx scripts/icons/refresh-icon-family.ts azure2026 --source /path/to/extracted/Icons
- npx tsx scripts/icons/refresh-icon-family.ts aws2026 --source /path/to/extracted
- npx tsx scripts/icons/refresh-icon-family.ts cisco2026 --source /path/to/extracted
- npm run icons:list
- ```
- This dedupes icons that vendors repeat across category folders, strips vendor ID/size-suffix
- cruft from filenames into the `icon:` key used in YAML, and runs everything through svgo. Families
- configured with `sourceExt: "eps"` (e.g. `cisco2026`) are first converted to SVG via Inkscape
- (`inkscape <file> -o <file>.svg`), which must be installed and on `PATH`. Vendor packages are not
- committed to the repo - only the resulting normalized SVGs under `public/images/<family>/`. To add
- another family, add a `FamilyConfig` entry to `scripts/icons/refresh-icon-family.ts`.
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.