@littledragon_wxl/drawio-style-graph 1.0.0

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@littledragon_wxl/drawio-style-graph",
+  "version": "1.0.0",
+  "description": "Generate .drawio diagrams with 8 professional visual styles. Self-contained — no external skill dependencies.",
+  "main": "SKILL.md",
+  "keywords": [
+    "drawio",
+    "diagram",
+    "flowchart",
+    "architecture",
+    "visualization",
+    "uml",
+    "svg",
+    "style-preset",
+    "skill",
+    "claude-code"
+  ],
+  "author": "littledragon_wxl",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Littledragon-wxl/drawio-style-graph.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Littledragon-wxl/drawio-style-graph/issues"
+  },
+  "homepage": "https://github.com/Littledragon-wxl/drawio-style-graph#readme",
+  "files": [
+    "SKILL.md",
+    "README.md",
+    "README_zh.md",
+    "LICENSE",
+    "CHANGELOG.md",
+    "scripts/",
+    "data/",
+    "references/",
+    "styles/"
+  ],
+  "engines": {
+    "node": ">=14.0.0"
+  }
+}
+

package/references/autolayout.md

@@ -0,0 +1,125 @@
+# Auto-layout (Graphviz)
+
+Read this when a diagram is **large or layout-heavy** — dependency/call graphs, code/module structure, or roughly **more than ~15 nodes** — where hand-placing `x`/`y` coordinates is slow, error-prone, and overlap-prone.
+
+Instead of computing coordinates by hand in the Generate step, describe the graph as JSON and let `scripts/autolayout.py` place the nodes and route the edges with Graphviz, then continue the normal workflow (Export draft → Self-check → …) on the produced `.drawio`.
+
+For small or carefully-styled diagrams, keep hand-placing — auto-layout trades fine control for scale.
+
+## Dependency
+
+Requires Graphviz `dot` on PATH:
+
+```bash
+# macOS
+brew install graphviz
+# Debian/Ubuntu
+sudo apt install graphviz
+```
+
+The script exits with a clear message if `dot` is missing — fall back to hand-placed coordinates in that case.
+
+## Usage
+
+```bash
+python3 <this-skill-dir>/scripts/autolayout.py graph.json -o diagram.drawio
+```
+
+It prints `wrote diagram.drawio (N nodes, M edges)` to stderr and writes a normal `.drawio` file. From there, continue at the **Export draft** step of the main workflow (preview PNG with `--width 2000`, self-check, review loop, final export with `-e` + `repair_png.py`).
+
+## Input format
+
+```json
+{
+  "direction": "TB",
+  "nodes": [
+    {"id": "client", "label": "Web Client", "style": "rounded=1;whiteSpace=wrap;html=1;fillColor=#d5e8d4;strokeColor=#82b366;"},
+    {"id": "gw", "label": "API Gateway", "group": "edge", "groupLabel": "Edge tier"},
+    {"id": "db", "label": "User DB", "style": "shape=cylinder3;whiteSpace=wrap;html=1;", "width": 120, "height": 80, "group": "data"}
+  ],
+  "edges": [
+    {"source": "client", "target": "gw", "label": "HTTPS"},
+    {"source": "gw", "target": "db"}
+  ]
+}
+```
+
+**Fields**
+
+| Field | Required | Default | Notes |
+|---|---|---|---|
+| `direction` | no | `TB` | `TB` (top→bottom) or `LR` (left→right) — the layout rank direction |
+| `nodes[].id` | **yes** | — | Unique; must not be `0` or `1` (reserved for draw.io root cells) |
+| `nodes[].label` | no | the `id` | Display text; auto XML-escaped |
+| `nodes[].style` | no | group colour, else blue | Any draw.io style string — reuse the role/shape styles from `diagram-types.md` and the active preset. A styleless node is tinted by its group (see **Containers / grouping**); an explicit style always wins |
+| `nodes[].width` / `height` | no | `120` / `60` | Pixels; dot lays out at this real size |
+| `nodes[].group` | no | none | Group key, or a `/`-delimited path (`"core/db"`) for **nested** containers — nodes sharing a path are boxed together (see **Containers / grouping**) |
+| `nodes[].groupLabel` | no | last path segment | Title shown on the node's deepest container (first node with the path wins) |
+| `edges[].source` / `target` | **yes** | — | Must match node ids |
+| `edges[].label` | no | empty | Edge text |
+
+## How it places things
+
+- Node positions come from `dot` (hierarchical layered layout), converted to draw.io pixels and snapped to the grid (multiples of 10).
+- Edges use `splines=ortho`: dot's orthogonal route is replayed as draw.io waypoints, so edges go **around** nodes instead of through them.
+- Apply the active style preset by setting each node's `style` to the preset's role/shape values before calling the script — the script does not know about presets.
+
+## Containers / grouping
+
+Give nodes a `group` key and the script wraps each group in a labeled container (a dashed box with the group title at top) and tells dot to keep that group's nodes together via a Graphviz cluster. Grouped nodes become children of their container (`parent="<container>"`, relative coordinates); ungrouped nodes stay at the top level. This turns a flat hairball into a "boxes of related modules" architecture view.
+
+**Nesting.** A `group` value with `/` separators builds nested containers: `"core/db"` puts the node inside a `db` box that itself sits inside a `core` box. Every path prefix becomes a container, so an arbitrarily deep package tree maps to nested boxes. A node can also sit *directly* in a parent box (`group: "core"`) alongside a sibling sub-box (`group: "core/db"`).
+
+- **Colour by group.** Each top-level group is assigned a colour from the skill's own palette (`styles/built-in/default.json`, cycled in role order: blue → green → orange → purple → yellow → red → grey). A node with no `style` of its own is tinted with its group's colour, and the container's border + title match — so related modules read as a coloured cluster instead of monochrome boxes. A node that carries its own `style` (e.g. from an applied preset) is left untouched. Pass `--mono` to turn colouring off (dashed grey boxes, default-blue nodes — the previous look). Ungrouped graphs are unaffected.
+- Each container box is the bounding box of its members and child boxes plus a uniform padding. The dot cluster margin is set to that same padding, so each box equals dot's cluster box — which dot keeps non-overlapping at **any nesting depth**.
+- The title sits in the top padding (`verticalAlign=top`); the box title is the path's last segment, or a member's `groupLabel`.
+- Containers are visual only (no edges of their own). Edges still connect node→node and route across containers normally.
+- If a container's top padding would cross the page origin, the whole diagram is shifted so nothing lands at a negative coordinate.
+
+## Validate before previewing
+
+`scripts/validate.py` is a deterministic structural linter — run it on the produced `.drawio` before the (slower, vision-based) self-check:
+
+```bash
+python3 <this-skill-dir>/scripts/validate.py diagram.drawio
+```
+
+It catches dangling edge endpoints, duplicate/reserved ids, broken parent references (errors), plus off-grid/negative geometry and overlapping sibling nodes (warnings) — without launching draw.io. Exit status is non-zero on any error (or any warning with `--strict`), so it can gate the workflow. Auto-layout output should always pass clean; a failure means a malformed input graph (e.g. an edge referencing a missing node id).
+
+## Importers — visualize code structure
+
+Bundled importers turn a codebase into a graph JSON ready for autolayout, so "visualize this project" is a two-step pipeline:
+
+| Language | Script | Node = | Edge = |
+|---|---|---|---|
+| Python | `scripts/pyimports.py <dir>` | module / package (`ast`) | intra-project `import` / `from` |
+| JS / TS | `scripts/jsimports.py <dir>` | source file (`.ts/.tsx/.js/.jsx/.mjs/.cjs`) | resolved relative `import`/`export from`/`require()`/`import()` |
+| Go | `scripts/goimports.py <dir>` | package (directory, via `go.mod`) | intra-module package import |
+| Rust | `scripts/rustimports.py <dir>` | module (`.rs` file / `mod`) | intra-crate `use crate::` / `super::` / `self::` |
+| Python (classes) | `scripts/pyclasses.py <dir>` | class (`ast`) | subclass → base (inheritance) |
+
+```bash
+python3 <this-skill-dir>/scripts/pyimports.py myproject -o graph.json
+python3 <this-skill-dir>/scripts/autolayout.py graph.json -o diagram.drawio
+```
+
+Each keeps only **intra-project** edges (third-party/stdlib imports are ignored), shortens node labels (drops the shared package/module/directory prefix; ids stay fully qualified), and shares the same flags: `--direction TB|LR` (default `TB`), `--group`, `--no-reduce`.
+
+- **Python** (`pyimports.py`): if the directory is itself a package (`__init__.py` present), module names are package-qualified so the project's own absolute imports resolve; nested subpackages (`pkg.sub.mod`) are handled.
+- **JS/TS** (`jsimports.py`): resolution is path-based (tries the source extensions and directory `index` files); `node_modules` and bare specifiers are skipped. Scanning is regex-based, not a full parser.
+- **Go** (`goimports.py`): reads the `module` path from `go.mod`; each directory of `.go` files is one package; `*_test.go` and `vendor/` are skipped.
+- **Rust** (`rustimports.py`): each `.rs` file is a module (`mod.rs`/`main.rs`/`lib.rs` name the enclosing module); edges come from `use` paths rooted at `crate::`/`super::`/`self::` (brace groups expanded). `std`/external crates and `target/` are skipped. Regex-based — inline `mod { … }` blocks aren't split out, and 2015-edition bare intra-crate paths aren't resolved.
+- **Python classes** (`pyclasses.py`): a finer granularity — one node per class, edges from each subclass to the project base classes it extends, so the result is an auto-generated class hierarchy. Bases are matched by name (preferring the same module); external bases (`object`, third-party) are ignored. With `--group`, classes are boxed by their module, so a deep package tree nests naturally. Inheritance only — function-level call graphs are out of scope (static call resolution in Python is unreliable).
+
+**Density reduction is on by default** — this is the key to a readable result. Real import graphs are dense (asyncio: 33 modules / ~149 edges); without reduction they render as a hairball. Every importer applies **transitive reduction** (Graphviz `tred` — drops edges already implied by a longer path), which on asyncio cuts ~149 edges to ~46 and turns the hairball into a clean, traceable diagram. Pass `--no-reduce` to keep every edge.
+
+**`--group`** assigns each node a container by its sub-package / directory path, so autolayout boxes related modules together — nested when the path has depth (see **Containers / grouping**). The fastest way to turn a large code graph into a tiered architecture view.
+
+For any other language, produce the same graph JSON from any analyzer (e.g. `dependency-cruiser` for richer JS/TS resolution, `go-callvis` for Go call graphs) and feed it to autolayout the same way.
+
+## Limitations
+
+- **Placement is topological, not semantic** — dot minimises edge crossings, which may put a node in a different column than you'd choose by hand. Re-export with the other `direction`, or hand-tune the produced XML afterwards (it's a normal `.drawio`).
+- **Import edges are static** — `pyimports`/`jsimports`/`goimports` read static import statements (not dynamic `importlib`, runtime `require`, or reflection); `pyclasses` resolves inheritance only, not method-level calls.
+- **Parallel edges** between the same `(source, target)` pair share one route.
+- **Containers don't add edges** — `group`/nesting only boxes nodes for layout; edges remain node→node. For hand-built swimlane/architecture containers with their own connections, see SKILL.md "Containers and groups".

package/references/diagram-types.md

@@ -0,0 +1,83 @@
+# Diagram Type Presets
+
+When the user requests a specific diagram type, apply the matching preset below for shapes, styles, and layout conventions. These presets set **structural** style keywords (e.g. ERD's `shape=table;childLayout=tableLayout`); a user style preset (see `references/style-presets.md`) layers color/font/edge/extras on top.
+
+Read this file when:
+- The user names one of these diagram types (ERD, UML class, sequence, architecture, ML/DL model, flowchart)
+- You're choosing shape vocabulary or layout direction for a new diagram
+
+## ERD (Entity-Relationship Diagram)
+
+| Element | Style | Notes |
+|---------|-------|-------|
+| Table | `shape=table;startSize=30;container=1;collapsible=1;childLayout=tableLayout;fixedRows=1;rowLines=0;fontStyle=1;strokeColor=#6c8ebf;fillColor=#dae8fc;` | Each table is a container |
+| Row (column) | `shape=tableRow;horizontal=0;startSize=0;swimlaneHead=0;swimlaneBody=0;fillColor=none;collapsible=0;dropTarget=0;points=[[0,0.5],[1,0.5]];portConstraint=eastwest;fontSize=12;` | Child of table, `parent=tableId` |
+| PK column | Bold text: `fontStyle=1` on the row | Mark with `PK` prefix or key icon |
+| FK relationship | Dashed edge: `dashed=1;endArrow=ERmandOne;startArrow=ERmandOne;` | Use ER notation arrows |
+| Layout | TB, tables spaced 300px apart | Group related tables vertically |
+
+## UML Class Diagram
+
+| Element | Style | Notes |
+|---------|-------|-------|
+| Class box | `swimlane;fontStyle=1;align=center;startSize=26;html=1;` | 3-section: title / attributes / methods |
+| Separator | `line;strokeWidth=1;fillColor=none;align=left;verticalAlign=middle;spacingTop=-1;spacingLeft=3;spacingRight=10;rotatable=0;labelPosition=left;points=[];portConstraint=eastwest;` | Between sections |
+| Inheritance | `endArrow=block;endFill=0;` | Hollow triangle arrow |
+| Implementation | `endArrow=block;endFill=0;dashed=1;` | Dashed + hollow triangle |
+| Composition | `endArrow=diamondThin;endFill=1;` | Filled diamond |
+| Aggregation | `endArrow=diamondThin;endFill=0;` | Hollow diamond |
+| Layout | TB, classes 250px apart | Interfaces above implementations |
+
+## Sequence Diagram
+
+| Element | Style | Notes |
+|---------|-------|-------|
+| Actor/Object | `shape=umlLifeline;perimeter=lifelinePerimeter;whiteSpace=wrap;html=1;container=1;collapsible=0;recursiveResize=0;outlineConnect=0;portConstraint=eastwest;` | Lifeline with dashed vertical line |
+| Sync message | `html=1;verticalAlign=bottom;endArrow=block;` | Solid line, filled arrowhead |
+| Async message | `html=1;verticalAlign=bottom;endArrow=open;dashed=1;` | Dashed line, open arrowhead |
+| Return message | `html=1;verticalAlign=bottom;endArrow=open;dashed=1;strokeColor=#999999;` | Grey dashed |
+| Activation box | `shape=umlFrame;whiteSpace=wrap;` on the lifeline | Narrow rectangle on lifeline |
+| Layout | LR, lifelines spaced 200px apart | Time flows top to bottom |
+
+## Architecture Diagram
+
+| Element | Style | Notes |
+|---------|-------|-------|
+| Layer/tier | `swimlane;startSize=30;` | Containers for grouping: Client / API / Service / Data |
+| Service | `rounded=1;whiteSpace=wrap;html=1;` + tier color | Use color palette by tier |
+| Database | `shape=cylinder3;whiteSpace=wrap;html=1;` | Green palette |
+| Queue/Bus | `rounded=1;whiteSpace=wrap;html=1;fillColor=#fff2cc;strokeColor=#d6b656;` | Yellow — place centrally for hub pattern |
+| Gateway/LB | `shape=mxgraph.aws4.resourceIcon;` or `rounded=1;` with orange | Orange palette |
+| External | `rounded=1;dashed=1;fillColor=#f5f5f5;strokeColor=#666666;` | Dashed border for external systems |
+| Layout | TB or LR by tier count; ≥4 tiers → TB | Hub nodes centered |
+
+## ML / Deep Learning Model Diagram
+
+For neural network architecture diagrams — ideal for papers targeting NeurIPS, ICML, ICLR.
+
+| Element | Style | Notes |
+|---------|-------|-------|
+| Layer block | `rounded=1;whiteSpace=wrap;html=1;` + type color | Main building block |
+| Input/Output | `fillColor=#d5e8d4;strokeColor=#82b366;` | Green |
+| Conv / Pooling | `fillColor=#dae8fc;strokeColor=#6c8ebf;` | Blue |
+| Attention / Transformer | `fillColor=#e1d5e7;strokeColor=#9673a6;` | Purple |
+| RNN / LSTM / GRU | `fillColor=#fff2cc;strokeColor=#d6b656;` | Yellow |
+| FC / Linear | `fillColor=#ffe6cc;strokeColor=#d79b00;` | Orange |
+| Loss / Activation | `fillColor=#f8cecc;strokeColor=#b85450;` | Red/Pink |
+| Skip connection | `dashed=1;endArrow=block;curved=1;` | Dashed curved arrow |
+| Tensor shape label | Add shape annotation as secondary label: `value="Conv2D
(B, 64, 32, 32)"` | Use `
` for multi-line |
+| Layout | TB (data flows top→bottom), layers 150px apart | Group encoder/decoder as swimlanes |
+
+**Tensor shape convention:** annotate each layer with input/output tensor dimensions in `(B, C, H, W)` or `(B, T, D)` format. Place dimensions as the second line of the label using `
`.
+
+## Flowchart (enhanced)
+
+| Element | Style | Notes |
+|---------|-------|-------|
+| Start/End | `ellipse;whiteSpace=wrap;html=1;fillColor=#d5e8d4;strokeColor=#82b366;` | Green oval |
+| Process | `rounded=0;whiteSpace=wrap;html=1;fillColor=#dae8fc;strokeColor=#6c8ebf;` | Blue rectangle |
+| Decision | `rhombus;whiteSpace=wrap;html=1;fillColor=#fff2cc;strokeColor=#d6b656;` | Yellow diamond |
+| I/O | `shape=parallelogram;perimeter=parallelogramPerimeter;whiteSpace=wrap;html=1;fillColor=#ffe6cc;strokeColor=#d79b00;` | Orange parallelogram |
+| Subprocess | `rounded=0;whiteSpace=wrap;html=1;fillColor=#e1d5e7;strokeColor=#9673a6;` + double border | Purple |
+| Yes/No labels | `value="Yes"` / `value="No"` on decision edges | Always label decision branches |
+| Layout | TB, 200px vertical gap | Decisions branch LR, merge back to center |

package/references/shapes.md

@@ -0,0 +1,151 @@
+# Shape vocabulary & search
+
+Read this when a diagram needs a **specific shape** — a cloud-provider icon
+(AWS/Azure/GCP), a network/Cisco/Kubernetes symbol, a UML/BPMN/ER element, an
+electrical or P&ID part — or any time you'd otherwise *guess* a `style=` string.
+
+There are two ways to get a style:
+
+1. **Search the official shape index** (`scripts/shapesearch.py`) — 10,446 real
+   draw.io palette shapes with their exact `style`, `w`, `h`. Use this for
+   branded/vendor icons and anything non-trivial. **Always prefer a searched
+   style over a hand-written `shape=mxgraph.*` guess** — guessed stencil names
+   silently render as a blank box if the name is wrong.
+2. **The cheatsheet below** — the common built-in shapes whose style strings are
+   short and stable enough to write by hand (rectangles, flowchart symbols,
+   UML primitives, containers, edges).
+
+## Searching shapes
+
+```bash
+python3 <this-skill-dir>/scripts/shapesearch.py "aws lambda" --limit 5
+python3 <this-skill-dir>/scripts/shapesearch.py "uml actor" --json
+```
+
+- Query is space-separated keywords; matching is tag-based with Soundex
+  fuzziness and `camelCase`/`digit` splitting (`"pid2valve"` → `pid valve`).
+- Prints each match as `Title (WxH)` followed by its full `style=` string. With
+  `--json`, emits `[{style,w,h,title}]` for programmatic use.
+- Copy the `style` verbatim into an `mxCell`, and use the reported `w`/`h` as the
+  `mxGeometry` width/height (vendor icons are drawn at a fixed aspect ratio).
+- Results are ranked by tag relevance, with shapes whose **title** contains the
+  query terms bubbled to the top of each score tier. Ranking is still a
+  heuristic, though, and many shapes share a title (three `Lambda` variants:
+  `aws3`/`aws4`/`aws3d`) — so run with `--limit 5` and pick the row whose title
+  and size match what you actually want rather than blindly taking #1.
+
+```xml
+<mxCell id="2" value="Lambda" style="<paste the searched style here>" vertex="1" parent="1">
+  <mxGeometry x="40" y="40" width="78" height="78" as="geometry"/>
+</mxCell>
+```
+
+Covered libraries: AWS (`aws3`/`aws4`), Azure, GCP, Cisco, Kubernetes, UML,
+BPMN, ER, electrical, P&ID, mockup/wireframe, flowchart, network, and the
+general/basic sets. The bundled index (`data/shape-index.json.gz`) is the
+upstream draw.io shape data — see `data/SHAPE-INDEX-NOTICE.md` for attribution.
+
+## AI / LLM brand logos
+
+draw.io's bundled libraries have **no** modern AI/LLM brand logos, so an "LLM app
+architecture" otherwise renders as generic boxes. `scripts/aiicons.py` resolves a
+brand name (OpenAI, Claude, Gemini, Mistral, Llama, HuggingFace, Ollama,
+LangChain, …321 brands) to a draw.io `image` style backed by the
+[lobe-icons](https://github.com/lobehub/lobe-icons) set (MIT).
+
+```bash
+python3 <this-skill-dir>/scripts/aiicons.py "claude" --json        # CDN reference
+python3 <this-skill-dir>/scripts/aiicons.py "openai" --embed        # self-contained
+python3 <this-skill-dir>/scripts/aiicons.py --list                  # all brands
+```
+
+- Picks the `-color` variant when it exists, else the mono logo (e.g. OpenAI is
+  mono-only). Returns a square `image` style; use the reported `--size` (default
+  48) for both width and height.
+- **Default references the icon by CDN URL** — the SVG lives on unpkg, not in
+  this repo, so **draw.io needs network access when the diagram is rendered or
+  opened**; an offline export draws a blank box. Pass `--embed` to fetch the SVG
+  once and inline it as a data URI (portable, renders offline, larger XML).
+- Logos are trademarks of their respective owners, referenced for identification
+  only — the same basis on which draw.io ships AWS/Azure icons.
+- **Data stores** common in RAG/LLM apps that lobe lacks (Qdrant, Redis,
+  Postgres, Mongo, Elasticsearch, Milvus, Supabase, Neo4j, ClickHouse, Kafka,
+  Snowflake, Databricks, …) resolve via the [simple-icons](https://simpleicons.org)
+  CDN (CC0) as an automatic fallback — same command, same output shape. A brand
+  in neither set has no logo; use a cylinder (`shape=cylinder3;`, see below) or
+  `scripts/shapesearch.py "<name> database"`.
+
+## Cheatsheet — hand-writable styles
+
+These are stable enough to write without searching. Combine with `whiteSpace=wrap;html=1;`.
+
+### Common shapes (`shape=` keyword)
+
+| Need | style |
+|---|---|
+| Rectangle / rounded box | `rounded=0;` / `rounded=1;` |
+| Circle / ellipse | `ellipse;` (`aspect=fixed;` for a true circle) |
+| Diamond (decision) | `rhombus;` |
+| Cylinder (database) | `shape=cylinder3;` |
+| Cloud | `cloud;` |
+| Cube (3D) | `shape=cube;` |
+| Sticky note | `shape=note;` |
+| Document (curled bottom) | `shape=document;` |
+| Folder | `shape=folder;` |
+| Card (cut corner) | `shape=card;` |
+| Process (double border) | `shape=process;` |
+| Step / chevron | `shape=step;` |
+| Parallelogram (I/O) | `shape=parallelogram;perimeter=parallelogramPerimeter;` |
+| Trapezoid | `shape=trapezoid;perimeter=trapezoidPerimeter;` |
+| Hexagon | `shape=hexagon;perimeter=hexagonPerimeter2;` |
+| Manual input | `shape=manualInput;` |
+| Data storage | `shape=dataStorage;` |
+| Off-page connector | `shape=offPageConnector;` |
+| Delay | `shape=delay;` |
+| OR / XOR gate | `shape=or;` / `shape=xor;` |
+| Block arrow | `shape=singleArrow;` / `shape=doubleArrow;` |
+| Callout (speech bubble) | `shape=callout;` |
+
+### UML primitives
+
+| Element | style |
+|---|---|
+| Actor (stick figure) | `shape=umlActor;verticalLabelPosition=bottom;verticalAlign=top;` |
+| Boundary | `shape=umlBoundary;` |
+| Control | `shape=umlControl;` |
+| Entity | `shape=umlEntity;` |
+| Lifeline | `shape=umlLifeline;perimeter=lifelinePerimeter;container=1;` |
+| Frame | `shape=umlFrame;` |
+| Provided interface (lollipop) | `shape=lollipop;direction=south;` |
+| Required interface | `shape=requires;direction=north;` |
+| Component | `shape=component;` |
+
+### Containers (parent-child; children use relative coords)
+
+| Type | style | When |
+|---|---|---|
+| Invisible group | `group;pointerEvents=0;` | No border, no own connections |
+| Titled swimlane | `swimlane;startSize=30;` | Visible title bar / has connections |
+| Any shape as container | append `container=1;pointerEvents=0;` | Box without own connections |
+
+### Edges
+
+| Need | add to style |
+|---|---|
+| Orthogonal routing | `edgeStyle=orthogonalEdgeStyle;rounded=1;orthogonalLoop=1;jettySize=auto;` |
+| Curved | `curved=1;` |
+| No arrowhead | `endArrow=none;` |
+| Open/thin arrow | `endArrow=open;` / `endArrow=classicThin;` |
+| Dashed | `dashed=1;` (pattern via `dashPattern=8 8;`) |
+| Flow animation | `flowAnimation=1;` |
+| Label background | `labelBackgroundColor=#ffffff;` |
+
+### Useful property knobs
+
+- `fontStyle` is a bitmask: `1`=bold, `2`=italic, `4`=underline (add to combine: `3`=bold+italic).
+- `direction=north|south|east|west` rotates a shape in 90° steps; `rotation=<deg>` for free rotation.
+- `gradientColor=#RRGGBB;` + `gradientDirection=north;` for a gradient fill.
+- `sketch=1;` gives a hand-drawn look (set globally via a style preset instead when possible).
+
+For richer per-shape detail, the upstream source is jgraph/drawio-mcp's
+`shared/style-reference.md` (Apache-2.0).

package/references/style-application-guide.md

@@ -0,0 +1,120 @@
+# Style Application Guide
+
+How to apply a visual style to a draw.io diagram generation.
+
+## Quick Reference: Style → Draw.io Tokens
+
+When a style is selected, use these mappings to construct `mxCell` style strings:
+
+### Step 1: Determine Role → Color
+
+For each node, determine its semantic role, then look up the `(fillColor, strokeColor)` pair
+from the selected style reference file:
+
+| Role | Style Reference Key | Example Use |
+|------|---------------------|-------------|
+| Service / component | `primary` | API service, microservice, worker |
+| Database / storage | `success` | PostgreSQL, Redis, S3, vector store |
+| Queue / message bus | `warning` | Kafka, RabbitMQ, SQS |
+| Gateway / API / LB | `accent` | API Gateway, Load Balancer, Proxy |
+| Error / alert | `danger` | Error handler, monitoring alert |
+| Security / auth | `secondary` | OAuth service, IAM, Vault |
+| External system | `neutral` | Third-party API, external service |
+
+### Step 2: Build Vertex Style String
+
+Template:
+```
+{shape_keyword};whiteSpace=wrap;html=1;fillColor={fillColor};strokeColor={strokeColor};strokeWidth={strokeWidth};fontFamily={fontFamily};fontSize={fontSize};fontColor={fontColor};{extras}
+```
+
+Where each variable comes from the style reference:
+
+| Variable | Style Reference Field |
+|----------|----------------------|
+| `shape_keyword` | "Shape Preferences" section (e.g., `rounded=1`) |
+| `fillColor` | Role's fillColor from palette table |
+| `strokeColor` | Role's strokeColor from palette table |
+| `strokeWidth` | Extras section (default: 1.5) |
+| `fontFamily` | Typography section |
+| `fontSize` | Typography section (labels size) |
+| `fontColor` | Typography section (primary text) |
+| `extras` | Extras section (e.g., `glass=1;shadow=1;`) |
+
+### Step 3: Build Edge Style String
+
+Template:
+```
+edgeStyle=orthogonalEdgeStyle;rounded=1;orthogonalLoop=1;jettySize=auto;html=1;strokeColor={flowColor};strokeWidth={edgeWidth};{dashPattern};exitX={exitX};exitY={exitY};entryX={entryX};entryY={entryY};
+```
+
+| Variable | Source |
+|----------|--------|
+| `flowColor` | Edge Style section, pick by flow type |
+| `edgeWidth` | Edge Style section or infer from strokeWidth |
+| `dashPattern` | `dashed=1` if flow type says dashed |
+| `exitX/Y`, `entryX/Y` | Routing rules (see SKILL.md) |
+
+### Step 4: Set Page Background
+
+For dark styles (2, 3, 5, 8), set the background on the mxGraphModel:
+
+```xml
+<mxGraphModel background="#0f0f1a">
+```
+
+For light styles (1, 4, 6, 7), use default or white:
+```xml
+<mxGraphModel background="#ffffff">
+```
+
+## Style-Specific Notes
+
+### Style 1 (Flat Icon)
+- Use `rounded=1` for all boxes
+- Colorful palette — different fill for each role
+- Default edge color: `#2563eb` (blue)
+- Arrow semantics use different colors per flow type
+
+### Style 2 (Dark Terminal)
+- Always set `background="#0f0f1a"`
+- Use monospace font for all text
+- Add `shadow=1` on primary (AI/ML) nodes
+- Edge colors match source node's theme
+
+### Style 3 (Blueprint)
+- Always set `background="#0a1628"`
+- Use `rounded=0` (sharp corners)
+- Monospace font, cyan-based text colors
+- External nodes use `fillColor=none;dashed=1`
+
+### Style 4 (Notion Clean)
+- All standard nodes share `fillColor=#f9fafb;strokeColor=#e5e7eb`
+- Only error nodes get pink tint
+- Single arrow color: `#3b82f6`
+- Uppercase type labels at 11px
+
+### Style 5 (Glassmorphism)
+- Always set `background="#0d1117"`
+- Add `glass=1;shadow=1` to all vertex styles
+- Edge colors match the source node's glow color bucket
+- Semi-transparent look in draw.io
+
+### Style 6 (Claude Official)
+- All nodes share `strokeColor=#4a4a4a;strokeWidth=2.5`
+- Warm teal/beige/blue/gray fill colors per role
+- Consistent `#5a5a5a` for all arrows
+- Bold 16px labels with `fontStyle=1`
+
+### Style 7 (OpenAI Official)
+- Almost all nodes: `fillColor=#ffffff;strokeColor=#e5e5e5`
+- Thin borders: `strokeWidth=1.5`
+- Color only in edges: `#10a37f` (green), `#71717a` (gray)
+- No shadows, no decorations
+
+### Style 8 (Dark Luxury)
+- Always set `background="#0a0a0a"`
+- All nodes: `fillColor=#111111` with colored stroke per bucket
+- Dual font: serif for titles, sans-serif for nodes
+- Gold edges (`#d4a574`) for primary flows
+- 6 semantic buckets with distinct stroke colors