Penpen header illustration for draw-io-skill

draw-io-skill

English · 日本語

Native .drawio authoring, cross-platform export helpers, and SVG linting for Codex, Claude Code, and repository workflows.

✨ Overview

draw-io-skill packages the most useful parts of three diagram workflows into one repository:

native .drawio editing for assistant-driven diagram generation
export helpers for png, svg, pdf, and jpg
SVG linting for crossings, box or frame border overlap, supported non-rect shape border overlap, box penetration, short arrowhead terminal runs, label intrusions, label-box collisions, weak text contrast, dark-card text hierarchy, and text overflow

It is meant to be practical in a real repository: editable source stays in .drawio, exports stay reproducible, and routing defects can be caught before a diagram lands in docs or a PR.

🚀 Quick Start

Install the local tooling, export a bundled fixture, then run the linter:

npm ci
npm run verify
node scripts/export-drawio.mjs fixtures/basic/basic.drawio --format svg
node scripts/check-drawio-svg-overlaps.mjs fixtures/basic/basic.drawio.svg
uv run python scripts/find_aws_icon.py lambda

npm run verify runs the syntax checks, every bundled lint regression fixture, and the docs build, so it is the fastest way to confirm that edge-terminal, edge-label, label-rect, text-contrast, text-emphasis, and text-overflow coverage still works end to end.

If you only want to rebuild the documentation site:

npm ci
npm run docs:build

🧭 Workflow

Create or update the native .drawio source.
Keep .drawio as the editable source of truth.
Export with embedded XML when you need png, svg, or pdf.
Run SVG lint when routing density or label fit matters.
Visually verify the final result before publishing.

Repository structure diagram for draw-io-skill

The repository also ships a Japanese-localized companion diagram:
assets/draw-io-skill-structure.ja.drawio,
assets/draw-io-skill-structure.ja.drawio.png,
and assets/draw-io-skill-structure.ja.drawio.svg.

🖼️ Showcase Samples

If you want the repository to read more like a showcase, these bundled samples are the best starting points:

assets/draw-io-skill-structure.drawio* for repository structure onboarding
assets/draw-io-skill-structure-shapes.drawio* for lint and visual review of non-rect shapes
assets/draw-io-skill-structure-icons.drawio* for icon-rich presentation blocks that pair well with the AWS icon guide and uv run python scripts/find_aws_icon.py

External Example Links

For a public AWS architecture example from another repository, see onizuka-game-agi-co:

onizuka-game-agi-aws-architecture.drawio for the editable source
onizuka-game-agi-aws-architecture.drawio.svg for the published SVG example

Short Prompt

Create a native draw.io diagram in an AWS reference-style icon view: light theme, dark navy title bar, cyan accents, white cards, official AWS icons, Noto Sans JP, orthogonal routing, and a note that AWS icons are visual references only for local/GitHub/workflow concepts.

The guided walkthrough lives in docs/guide/showcase.md.

🛠️ What You Get

Native draw.io workflow

real mxGraphModel XML editing
consistent .drawio.<format> naming
embedded XML exports where draw.io supports it

Export helper

node scripts/export-drawio.mjs architecture.drawio --format png --open
node scripts/export-drawio.mjs architecture.drawio --format svg
node scripts/export-drawio.mjs architecture.drawio --output architecture.drawio.pdf

The helper locates the draw.io CLI across Windows, macOS, and Linux, defaults PNG export to transparent 2x output, and supports optional --delete-source cleanup only when requested explicitly.

SVG linting

node scripts/check-drawio-svg-overlaps.mjs fixtures/basic/basic.drawio.svg
node scripts/check-drawio-svg-overlaps.mjs fixtures/border-overlap/border-overlap.drawio.svg
node scripts/check-drawio-svg-overlaps.mjs fixtures/large-frame-border-overlap/large-frame-border-overlap.drawio.svg
node scripts/check-drawio-svg-overlaps.mjs fixtures/shape-border-overlap/shape-border-overlap.drawio.svg
node scripts/check-drawio-svg-overlaps.mjs fixtures/label-rect-overlap/label-rect-overlap.drawio
node scripts/check-drawio-svg-overlaps.mjs fixtures/text-cell-overflow/text-cell-overflow.drawio
node scripts/check-drawio-svg-overlaps.mjs fixtures/text-contrast/text-contrast.drawio
node scripts/check-drawio-svg-overlaps.mjs fixtures/text-emphasis/text-emphasis.drawio

The linter checks:

edge-edge
edge-rect-border for lines that run along or visibly overlap a box or large frame border
edge-shape-border for lines that run along supported non-rect shape borders such as document, hexagon, parallelogram, and trapezoid
edge-rect
edge-terminal for final arrow runs that become too short after the last bend
edge-label for routed lines that cross label text boxes
label-rect for label text boxes that collide with another box or card
rect-shape-border for box or frame borders that run along those supported non-rect shape borders
text-contrast for text whose explicit font color is too close to its fill color
text-emphasis for compact dark cards whose title and body copy are still flattened into one dense block
text-overflow(width)
text-overflow(height)

The checker accepts either .drawio or .drawio.svg input. When you point it at a .drawio source, it reads the companion draw.io geometry as well, which keeps label-rect and text-fit checks aligned with the editable source instead of relying only on exported SVG bounds.

The repository includes dedicated regression fixtures for simple box-border overlap, large frame-border overlap, supported non-rect shape border overlap, label-box collisions, text-cell overflow, low-contrast copy, dark-card hierarchy, and shape-aware text overflow so routing regressions can be caught in CI before a diagram lands in docs. edge-terminal, edge-label, label-rect, and text-emphasis are additional heuristics aimed at the common "tiny arrow tail", "line through label", "note card covering a label", and "dark card title/body blending together" failures that often need a second pass after export.

For a repository-local lint and visual review sample, use
assets/draw-io-skill-structure-shapes.drawio,
assets/draw-io-skill-structure-shapes.drawio.png,
and assets/draw-io-skill-structure-shapes.drawio.svg.

For a more presentation-oriented sample, use
assets/draw-io-skill-structure-icons.drawio,
assets/draw-io-skill-structure-icons.drawio.png,
and assets/draw-io-skill-structure-icons.drawio.svg.

When text-contrast fires, treat it like a legibility bug: increase the actual foreground/background delta instead of relying on texture, glow, or outlines.

When text-emphasis fires, treat it like a hierarchy bug: split the title from the body with a chip, independent text cell, stronger spacing, or a clearer surface split.

📦 Installation

Codex

git clone https://github.com/Sunwood-ai-labs/draw-io-skill.git D:\Prj\draw-io-skill
cmd /c mklink /J C:\Users\YOUR_NAME\.codex\skills\draw-io D:\Prj\draw-io-skill

Claude Code

git clone https://github.com/Sunwood-ai-labs/draw-io-skill.git ~/.claude/skills/drawio

📚 Documentation

🗂️ Repository Layout

draw-io-skill/
├── README.md
├── README.ja.md
├── SKILL.md
├── LICENSE
├── assets/
│   ├── draw-io-skill-hero.svg
│   ├── draw-io-skill-icon.svg
│   ├── draw-io-skill-penpen-header.webp
│   ├── draw-io-skill-structure.drawio
│   ├── draw-io-skill-structure.drawio.png
│   ├── draw-io-skill-structure.drawio.svg
│   ├── draw-io-skill-structure-icons.drawio
│   ├── draw-io-skill-structure-icons.drawio.png
│   ├── draw-io-skill-structure-icons.drawio.svg
│   ├── draw-io-skill-structure-icons.ja.drawio
│   ├── draw-io-skill-structure-icons.ja.drawio.png
│   ├── draw-io-skill-structure-icons.ja.drawio.svg
│   ├── draw-io-skill-structure-shapes.drawio
│   ├── draw-io-skill-structure-shapes.drawio.png
│   ├── draw-io-skill-structure-shapes.drawio.svg
│   ├── draw-io-skill-structure.ja.drawio
│   ├── draw-io-skill-structure.ja.drawio.png
│   └── draw-io-skill-structure.ja.drawio.svg
├── docs/
│   ├── .vitepress/
│   ├── guide/
│   ├── ja/
│   └── public/
├── fixtures/
│   ├── basic/
│   ├── border-overlap/
│   ├── label-rect-overlap/
│   ├── large-frame-border-overlap/
│   ├── shape-border-overlap/
│   ├── shape-text-overflow/
│   └── text-cell-overflow/
├── references/
│   ├── aws-icons.en.md
│   ├── aws-icons.md
│   ├── layout-guidelines.en.md
│   └── layout-guidelines.md
└── scripts/
    ├── check-drawio-svg-overlaps.mjs
    ├── convert-drawio-to-png.sh
    ├── export-drawio.mjs
    ├── find_aws_icon.py
    ├── verify-border-overlap-fixture.mjs
    ├── verify-label-rect-fixture.mjs
    └── verify-text-cell-overflow-fixture.mjs

🙏 References And Credits

This repository blends ideas from:

softaworks/agent-toolkit for layout and editing guidance
jgraph/drawio-mcp for native draw.io assistant workflows
repository-focused linting and export tooling added here

Referenced sources:

📄 License

MIT