@littledragon_wxl/drawio-style-graph 1.0.0

package/references/styles/style-2-dark-terminal.md

@@ -0,0 +1,80 @@
+# Style 2: Dark Terminal
+
+Adapted from fireworks-tech-graph Style 2. Neon-on-dark hacker aesthetic.
+
+## Color Palette → Draw.io Mapping
+
+Canvas background: `#0f0f1a` (set in mxGraphModel `background` attribute or as page background)
+
+| Role | fillColor | strokeColor | Use for |
+|------|-----------|-------------|---------|
+| primary (AI/ML) | `#1e1b4b` | `#7c3aed` | AI/ML, LLM, model nodes |
+| success (database) | `#052e16` | `#059669` | databases, storage |
+| warning (queue) | `#1c1917` | `#ea580c` | queues, async messaging |
+| accent (gateway/API) | `#1e3a5f` | `#3b82f6` | gateways, APIs, network |
+| danger (error) | `#450a0a` | `#dc2626` | errors, alerts |
+| secondary (security) | `#1e1b4b` | `#a855f7` | security, auth |
+| neutral (external) | `#0f172a` | `#334155` | external systems |
+
+## Typography → Draw.io Mapping
+
+```
+fontFamily=SF Mono,Fira Code,Cascadia Code,Courier New,Microsoft YaHei,SimHei,monospace
+fontSize=13        (labels)
+fontSize=11        (sub-labels)
+fontSize=15        (titles)
+fontStyle=1        (bold, for titles/section headers)
+fontColor=#e2e8f0  (primary text — near white)
+fontColor=#94a3b8  (secondary text — muted)
+```
+
+## Shape Preferences
+
+```
+rounded=1          (rounded corners, 6px equivalent)
+whiteSpace=wrap
+html=1
+```
+
+For AI/ML nodes (primary role): add `shadow=1;` for glow effect.
+For databases: `shape=cylinder3;whiteSpace=wrap;html=1;`
+For queues: `rounded=1;whiteSpace=wrap;html=1;`
+
+## Edge Style → Draw.io Mapping
+
+Base edge style:
+```
+edgeStyle=orthogonalEdgeStyle;rounded=1;orthogonalLoop=1;jettySize=auto;html=1;
+```
+
+Arrow colors (append to edge style):
+| Flow Type | strokeColor | Additional |
+|-----------|-------------|------------|
+| Purple (AI/ML) | `#a855f7` | — |
+| Orange (compute/API) | `#f97316` | — |
+| Blue (network/gateway) | `#3b82f6` | — |
+| Green (storage/DB) | `#10b981` | — |
+| Gold (highlight) | `#eab308` | — |
+| Async/event | `#94a3b8` | `dashed=1` |
+
+## Extras
+
+```
+strokeWidth=1.5   (on all shapes)
+shadow=1          (on primary nodes for glow)
+sketch=0
+```
+
+## Complete Vertex Style Template
+
+For an AI/ML node (primary role):
+```
+rounded=1;whiteSpace=wrap;html=1;fillColor=#1e1b4b;strokeColor=#7c3aed;strokeWidth=1.5;fontFamily=SF Mono,Fira Code,Cascadia Code,Courier New,Microsoft YaHei,SimHei,monospace;fontSize=13;fontColor=#e2e8f0;shadow=1;
+```
+
+## Page Background
+
+Set in `<mxGraphModel>` or `<diagram>`:
+```xml
+<mxGraphModel background="#0f0f1a">
+```

package/references/styles/style-3-blueprint.md

@@ -0,0 +1,84 @@
+# Style 3: Blueprint
+
+Adapted from fireworks-tech-graph Style 3. Engineering blueprint aesthetic.
+
+## Color Palette → Draw.io Mapping
+
+Canvas background: `#0a1628` (deep navy)
+
+| Role | fillColor | strokeColor | Use for |
+|------|-----------|-------------|---------|
+| primary (service) | `#0d1f3c` | `#00b4d8` | services, components |
+| success (database) | `#0d1f3c` | `#06d6a0` | databases, storage |
+| warning (queue) | `#0d1f3c` | `#f77f00` | queues, alerts |
+| accent (gateway/API) | `#0d1f3c` | `#48cae4` | gateways, APIs |
+| danger (error) | `#0d1f3c` | `#f77f00` | errors (orange) |
+| secondary (security) | `#0d1f3c` | `#00b4d8` | security |
+| neutral (external) | `none` | `#48cae4` | external (dashed, no fill) |
+
+## Typography → Draw.io Mapping
+
+```
+fontFamily=Courier New,Lucida Console,Microsoft YaHei,SimHei,monospace
+fontSize=13        (labels)
+fontSize=10        (annotations)
+fontSize=16        (titles, bold)
+fontStyle=1        (bold, for titles)
+fontColor=#caf0f8  (primary text — light cyan)
+fontColor=#90e0ef  (secondary text)
+fontColor=#00b4d8  (label accents)
+```
+
+## Shape Preferences
+
+```
+rounded=0          (sharp corners, 2px equivalent for technical feel)
+whiteSpace=wrap
+html=1
+```
+
+For databases: `shape=cylinder3;whiteSpace=wrap;html=1;`
+For external/optional: `dashed=1;` on the vertex style
+Note: draw.io does not natively support blueprint grid backgrounds. The dark navy canvas and cyan strokes evoke the blueprint feel without needing a grid pattern.
+
+## Edge Style → Draw.io Mapping
+
+Base edge style:
+```
+edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;
+```
+
+Arrow colors:
+| Flow Type | strokeColor | Additional |
+|-----------|-------------|------------|
+| Primary flow | `#00b4d8` | — |
+| Secondary | `#48cae4` | — |
+| Read/retrieval | `#06d6a0` | — |
+| Async/event | `#48cae4` | `dashed=1` |
+| Alert/warning | `#f77f00` | — |
+
+## Extras
+
+```
+strokeWidth=1     (thin lines for technical precision)
+sketch=0
+shadow=0
+```
+
+## Complete Vertex Style Template
+
+For a service node (primary role):
+```
+rounded=0;whiteSpace=wrap;html=1;fillColor=#0d1f3c;strokeColor=#00b4d8;strokeWidth=1;fontFamily=Courier New,Lucida Console,Microsoft YaHei,SimHei,monospace;fontSize=13;fontColor=#caf0f8;
+```
+
+For an external node (neutral, dashed):
+```
+rounded=0;whiteSpace=wrap;html=1;fillColor=none;strokeColor=#48cae4;strokeWidth=1;dashed=1;fontFamily=Courier New,Lucida Console,Microsoft YaHei,SimHei,monospace;fontSize=13;fontColor=#caf0f8;
+```
+
+## Page Background
+
+```xml
+<mxGraphModel background="#0a1628">
+```

package/references/styles/style-4-notion-clean.md

@@ -0,0 +1,78 @@
+# Style 4: Notion Clean
+
+Adapted from fireworks-tech-graph Style 4. Minimal, documentation-friendly.
+
+## Color Palette → Draw.io Mapping
+
+| Role | fillColor | strokeColor | Use for |
+|------|-----------|-------------|---------|
+| primary (service) | `#f9fafb` | `#e5e7eb` | services, main components |
+| success (database) | `#f9fafb` | `#e5e7eb` | databases, storage |
+| warning (queue) | `#f9fafb` | `#e5e7eb` | queues, decisions |
+| accent (gateway/API) | `#f9fafb` | `#e5e7eb` | gateways, APIs |
+| danger (error) | `#fef2f2` | `#fecaca` | errors, alerts |
+| secondary (security) | `#f9fafb` | `#e5e7eb` | security, auth |
+| neutral (external) | `#ffffff` | `#e5e7eb` | external systems |
+
+Note: This style intentionally uses minimal color variation — all standard nodes share the same fill/stroke. Only error/alert nodes get a pink tint to stand out.
+
+## Typography → Draw.io Mapping
+
+```
+fontFamily=-apple-system,BlinkMacSystemFont,Segoe UI,Helvetica Neue,Arial,PingFang SC,Microsoft YaHei,SimHei,sans-serif
+fontSize=14        (labels)
+fontSize=11        (type labels, uppercase)
+fontSize=18        (titles)
+fontStyle=1        (bold, for titles)
+fontColor=#111827  (primary text — near black)
+fontColor=#374151  (secondary text — gray-700)
+fontColor=#9ca3af  (muted — for type labels like "DATABASE")
+```
+
+## Shape Preferences
+
+```
+rounded=1          (rounded corners, 4px equivalent)
+whiteSpace=wrap
+html=1
+```
+
+For databases: `shape=cylinder3;whiteSpace=wrap;html=1;`
+Container sections: `swimlane;startSize=30;dashed=1;` with muted borders
+
+## Edge Style → Draw.io Mapping
+
+This style uses a SINGLE arrow color for all connections (clean, minimal).
+
+Base edge style:
+```
+edgeStyle=orthogonalEdgeStyle;rounded=1;orthogonalLoop=1;jettySize=auto;html=1;strokeColor=#3b82f6;strokeWidth=1.5;
+```
+
+Secondary flows (gray):
+```
+edgeStyle=orthogonalEdgeStyle;rounded=1;orthogonalLoop=1;jettySize=auto;html=1;strokeColor=#d1d5db;strokeWidth=1;dashed=1;
+```
+
+## Extras
+
+```
+strokeWidth=1     (on all shapes — thin borders)
+sketch=0
+shadow=0          (no shadows — flat design)
+```
+
+## Complete Vertex Style Template
+
+For a standard node:
+```
+rounded=1;whiteSpace=wrap;html=1;fillColor=#f9fafb;strokeColor=#e5e7eb;strokeWidth=1;fontFamily=-apple-system,BlinkMacSystemFont,Segoe UI,Helvetica Neue,Arial,PingFang SC,Microsoft YaHei,SimHei,sans-serif;fontSize=14;fontColor=#111827;
+```
+
+## Design Principles
+
+- No decorative icons — geometric shapes only
+- Generous whitespace — 24px+ padding
+- Single arrow color for all primary flows
+- Type labels in UPPERCASE 11px (e.g., "SERVICE", "DATABASE")
+- No gradients, no shadows, strictly flat

package/references/styles/style-5-glassmorphism.md

@@ -0,0 +1,85 @@
+# Style 5: Glassmorphism
+
+Adapted from fireworks-tech-graph Style 5. Frosted glass cards on dark background.
+
+## Color Palette → Draw.io Mapping
+
+Canvas background: `#0d1117` (dark, simulating the gradient base)
+
+Note: True glassmorphism (backdrop-filter blur) is not natively supported in draw.io.
+We simulate it with low-opacity fills, light borders, and shadow effects.
+
+| Role | fillColor | strokeColor | Use for |
+|------|-----------|-------------|---------|
+| primary (service) | `#1a2332` | `#58a6ff` | services, main components (blue glow) |
+| success (database) | `#1a2e1a` | `#3fb950` | databases, storage (green glow) |
+| warning (queue) | `#2e1f1a` | `#f78166` | queues (orange glow) |
+| accent (gateway/API) | `#1f1a2e` | `#bc8cff` | gateways, APIs (purple glow) |
+| danger (error) | `#2e1a1a` | `#f85149` | errors, alerts |
+| secondary (security) | `#1a2332` | `#58a6ff` | security |
+| neutral (external) | `#161b22` | `#30363d` | external systems (muted) |
+
+## Typography → Draw.io Mapping
+
+```
+fontFamily=Inter,-apple-system,SF Pro Display,PingFang SC,Microsoft YaHei,SimHei,sans-serif
+fontSize=14        (labels)
+fontSize=12        (sub-labels)
+fontSize=20        (hero titles)
+fontStyle=1        (bold, for titles)
+fontStyle=0        (semi-bold equivalent for labels)
+fontColor=#f0f6fc  (primary text — near white)
+fontColor=#8b949e  (secondary text — muted)
+```
+
+## Shape Preferences
+
+```
+rounded=1          (rounded corners, 12px equivalent)
+whiteSpace=wrap
+html=1
+glass=1            (draw.io's built-in glass effect)
+shadow=1           (simulates glow)
+```
+
+The `glass=1` style in draw.io creates a semi-transparent look that approximates the frosted glass effect.
+
+For databases: `shape=cylinder3;whiteSpace=wrap;html=1;glass=1;`
+
+## Edge Style → Draw.io Mapping
+
+Base edge style:
+```
+edgeStyle=orthogonalEdgeStyle;rounded=1;orthogonalLoop=1;jettySize=auto;html=1;
+```
+
+Arrow colors (match source node's glow color):
+| Flow Type | strokeColor | Additional |
+|-----------|-------------|------------|
+| Blue flow | `#58a6ff` | — |
+| Purple flow | `#bc8cff` | — |
+| Green flow | `#3fb950` | — |
+| Orange flow | `#f78166` | — |
+| Async/event | `#8b949e` | `dashed=1` |
+
+## Extras
+
+```
+strokeWidth=1     (thin borders for glass cards)
+glass=1           (on all shapes)
+shadow=1          (on all shapes)
+sketch=0
+```
+
+## Complete Vertex Style Template
+
+For a service node (primary, blue glow):
+```
+rounded=1;whiteSpace=wrap;html=1;fillColor=#1a2332;strokeColor=#58a6ff;strokeWidth=1;fontFamily=Inter,-apple-system,SF Pro Display,PingFang SC,Microsoft YaHei,SimHei,sans-serif;fontSize=14;fontColor=#f0f6fc;glass=1;shadow=1;
+```
+
+## Page Background
+
+```xml
+<mxGraphModel background="#0d1117">
+```

package/references/styles/style-6-claude-official.md

@@ -0,0 +1,84 @@
+# Style 6: Claude Official
+
+Adapted from fireworks-tech-graph Style 6. Warm, approachable, Anthropic-style.
+
+## Color Palette → Draw.io Mapping
+
+| Role | fillColor | strokeColor | Use for |
+|------|-----------|-------------|---------|
+| primary (service) | `#9dd4c7` | `#4a4a4a` | services, agent/process (teal-green) |
+| success (database) | `#e8e6e3` | `#4a4a4a` | databases, storage (light gray) |
+| warning (queue) | `#f4e4c1` | `#4a4a4a` | queues, bus, infrastructure (beige) |
+| accent (gateway/API) | `#a8c5e6` | `#4a4a4a` | gateways, APIs, input (soft blue) |
+| danger (error) | `#f4c1c1` | `#4a4a4a` | errors, alerts (soft pink) |
+| secondary (security) | `#9dd4c7` | `#4a4a4a` | security (reuse agent color) |
+| neutral (external) | `#f8f6f3` | `#4a4a4a` | external systems (background cream) |
+
+Note: All nodes share the same dark gray stroke (`#4a4a4a`), creating visual cohesion.
+
+## Typography → Draw.io Mapping
+
+```
+fontFamily=-apple-system,BlinkMacSystemFont,Segoe UI,Helvetica Neue,Arial,PingFang SC,Microsoft YaHei,SimHei,sans-serif
+fontSize=16        (node labels, semi-bold)
+fontSize=14        (descriptions)
+fontSize=13        (arrow labels)
+fontSize=18        (titles, bold)
+fontStyle=1        (bold for labels and titles)
+fontStyle=0        (regular for descriptions)
+fontColor=#1a1a1a  (primary text — near black)
+fontColor=#6a6a6a  (secondary text — medium gray)
+fontColor=#5a5a5a  (arrow labels)
+```
+
+## Shape Preferences
+
+```
+rounded=1          (rounded corners, 12px equivalent)
+whiteSpace=wrap
+html=1
+```
+
+All boxes use `strokeWidth=2.5` for the thick, warm border look.
+
+For databases: `shape=cylinder3;whiteSpace=wrap;html=1;`
+
+## Edge Style → Draw.io Mapping
+
+Base edge style — all arrows use the same dark gray:
+```
+edgeStyle=orthogonalEdgeStyle;rounded=1;orthogonalLoop=1;jettySize=auto;html=1;strokeColor=#5a5a5a;strokeWidth=2;
+```
+
+Arrow semantics through dash patterns only:
+| Flow Type | Additional |
+|-----------|------------|
+| Primary data flow | — (solid) |
+| Memory write | `dashed=1` |
+| Memory read | — (solid) |
+| Control/trigger | `dashed=1` |
+
+## Extras
+
+```
+strokeWidth=2.5   (thick warm borders on all shapes)
+sketch=0
+shadow=0
+```
+
+## Complete Vertex Style Template
+
+For a service/agent node (primary, teal-green):
+```
+rounded=1;whiteSpace=wrap;html=1;fillColor=#9dd4c7;strokeColor=#4a4a4a;strokeWidth=2.5;fontFamily=-apple-system,BlinkMacSystemFont,Segoe UI,Helvetica Neue,Arial,PingFang SC,Microsoft YaHei,SimHei,sans-serif;fontSize=16;fontColor=#1a1a1a;fontStyle=1;
+```
+
+For an input/source node (blue):
+```
+rounded=1;whiteSpace=wrap;html=1;fillColor=#a8c5e6;strokeColor=#4a4a4a;strokeWidth=2.5;fontFamily=-apple-system,BlinkMacSystemFont,Segoe UI,Helvetica Neue,Arial,PingFang SC,Microsoft YaHei,SimHei,sans-serif;fontSize=16;fontColor=#1a1a1a;fontStyle=1;
+```
+
+For an infrastructure/bus node (beige):
+```
+rounded=1;whiteSpace=wrap;html=1;fillColor=#f4e4c1;strokeColor=#4a4a4a;strokeWidth=2.5;fontFamily=-apple-system,BlinkMacSystemFont,Segoe UI,Helvetica Neue,Arial,PingFang SC,Microsoft YaHei,SimHei,sans-serif;fontSize=16;fontColor=#1a1a1a;fontStyle=1;
+```

package/references/styles/style-7-openai.md

@@ -0,0 +1,94 @@
+# Style 7: OpenAI Official
+
+Adapted from fireworks-tech-graph Style 7. Clean, minimal, precise.
+
+## Color Palette → Draw.io Mapping
+
+This style is extremely minimal — almost all nodes are white with light gray borders.
+Color is reserved for accents only.
+
+| Role | fillColor | strokeColor | Use for |
+|------|-----------|-------------|---------|
+| primary (service) | `#ffffff` | `#e5e5e5` | services, main components |
+| success (database) | `#ffffff` | `#e5e5e5` | databases, storage |
+| warning (queue) | `#ffffff` | `#e5e5e5` | queues |
+| accent (gateway/API) | `#ffffff` | `#e5e5e5` | gateways, APIs |
+| danger (error) | `#fef2f2` | `#fecaca` | errors, alerts |
+| secondary (security) | `#ffffff` | `#e5e5e5` | security |
+| neutral (external) | `#ffffff` | `#e5e5e5` | external systems |
+
+**Accent colors** (used for left-border accent strip or edge colors):
+- `#10a37f` — OpenAI brand green (primary accent)
+- `#1d4ed8` — blue accent (links, secondary)
+- `#f97316` — orange accent (warnings, highlights)
+- `#71717a` — gray (default edges, neutral)
+
+## Typography → Draw.io Mapping
+
+```
+fontFamily=-apple-system,BlinkMacSystemFont,Segoe UI,Roboto,Helvetica Neue,PingFang SC,Microsoft YaHei,SimHei,sans-serif
+fontSize=16        (node labels, semi-bold)
+fontSize=13        (descriptions)
+fontSize=12        (arrow labels)
+fontStyle=1        (bold, for titles — font weight 600)
+fontStyle=0        (medium equivalent for labels — font weight 500)
+fontColor=#0d0d0d  (primary text — near black)
+fontColor=#6e6e80  (secondary text — muted gray)
+```
+
+## Shape Preferences
+
+```
+rounded=1          (rounded corners, 8px equivalent)
+whiteSpace=wrap
+html=1
+```
+
+For databases: `shape=cylinder3;whiteSpace=wrap;html=1;`
+Note: In the original SVG style, accent nodes have a 4px colored left border. draw.io
+doesn't support this directly, but you can achieve a similar effect by using
+`verticalAlign=top;align=left;spacingLeft=8;` for left-aligned text with an accent
+colored `strokeColor` on the container.
+
+## Edge Style → Draw.io Mapping
+
+Base edge style — thin, precise:
+```
+edgeStyle=orthogonalEdgeStyle;rounded=1;orthogonalLoop=1;jettySize=auto;html=1;strokeWidth=1.5;
+```
+
+Arrow colors:
+| Flow Type | strokeColor | Usage |
+|-----------|-------------|-------|
+| Default connection | `#71717a` | most edges |
+| Accent/green | `#10a37f` | primary data paths |
+| Blue action | `#1d4ed8` | action/trigger |
+| Orange warning | `#f97316` | edge cases, warnings |
+
+## Extras
+
+```
+strokeWidth=1.5   (thin, precise borders on all shapes)
+sketch=0
+shadow=0
+```
+
+## Complete Vertex Style Template
+
+For a standard node:
+```
+rounded=1;whiteSpace=wrap;html=1;fillColor=#ffffff;strokeColor=#e5e5e5;strokeWidth=1.5;fontFamily=-apple-system,BlinkMacSystemFont,Segoe UI,Roboto,Helvetica Neue,PingFang SC,Microsoft YaHei,SimHei,sans-serif;fontSize=16;fontColor=#0d0d0d;fontStyle=1;
+```
+
+For an error/alert node:
+```
+rounded=1;whiteSpace=wrap;html=1;fillColor=#fef2f2;strokeColor=#fecaca;strokeWidth=1.5;fontFamily=-apple-system,BlinkMacSystemFont,Segoe UI,Roboto,Helvetica Neue,PingFang SC,Microsoft YaHei,SimHei,sans-serif;fontSize=16;fontColor=#0d0d0d;fontStyle=1;
+```
+
+## Design Principles
+
+- No gradients, no shadows, no decorative elements
+- White fill with light gray borders for all nodes
+- Color appears only in edges and accent details
+- Precision and clarity above all
+- System font stack for maximum compatibility

package/references/styles/style-8-dark-luxury.md

@@ -0,0 +1,109 @@
+# Style 8: Dark Luxury
+
+Adapted from fireworks-tech-graph Style 8. Deep black canvas with champagne-gold accents.
+Premium editorial aesthetic.
+
+## Color Palette → Draw.io Mapping
+
+Canvas background: `#0a0a0a` (deepest black, no blue tint)
+
+Six semantic color buckets:
+
+| Role | Bucket | fillColor | strokeColor | Use for |
+|------|--------|-----------|-------------|---------|
+| primary (service/API) | Service/API | `#111111` | `#a78bfa` | services, endpoints, APIs (soft violet) |
+| success (database) | Data/Storage | `#111111` | `#38bdf8` | databases, tables, caches (sky blue) |
+| warning (queue) | Infra/Config | `#111111` | `#fbbf24` | infra, pipelines, config (amber) |
+| accent (gateway/API) | Service/API | `#111111` | `#a78bfa` | gateways (same as services) |
+| danger (error) | Concept/Domain | `#111111` | `#f87171` | errors, concepts (soft rose) |
+| secondary (logic) | Code/Logic | `#111111` | `#5a9e6f` | functions, modules, algorithms (sage) |
+| neutral (external) | Meta/Doc | `#111111` | `#94a3b8` | external, docs, schemas (cool gray) |
+
+**Gold accent**: `#d4a574` for titles, section headers, primary arrows.
+**Bright gold**: `#e8c49a` for highlights.
+**Dim gold**: `#c9a96e` for secondary accents.
+
+## Typography → Draw.io Mapping
+
+Dual-font strategy: Serif for titles, Sans-serif for body.
+
+```
+Title/Section font:  fontFamily=Georgia,Times New Roman,serif
+                      fontSize=21 (diagram title), fontSize=14 (section labels)
+                      fontStyle=1 (bold)
+                      fontColor=#f5f0eb or fontColor=#c9a96e (gold for sections)
+
+Node label font:     fontFamily=-apple-system,Helvetica Neue,Arial,PingFang SC,Microsoft YaHei,sans-serif
+                      fontSize=13-14, fontStyle=1 (semi-bold 600)
+                      fontColor=<bucket's strokeColor> (use the bucket's color for the label)
+
+Sub-label font:      fontFamily=-apple-system,Helvetica Neue,Arial,PingFang SC,Microsoft YaHei,sans-serif
+                      fontSize=10-11, fontColor=#a39787 or fontColor=#6b5f53
+
+Code/path font:      fontFamily=Cascadia Code,SF Mono,Courier New,monospace
+                      fontSize=10-11, fontColor=#a39787
+```
+
+**Rule**: Use serif only for diagram titles and section/cluster labels (≥14px). All node
+names, edge labels, and fine print use sans-serif.
+
+## Shape Preferences
+
+```
+rounded=1          (rounded corners, 6px equivalent)
+whiteSpace=wrap
+html=1
+```
+
+All nodes share: `fillColor=#111111`, `strokeWidth=1.5`, stroke color from bucket.
+
+For databases: `shape=cylinder3;whiteSpace=wrap;html=1;`
+For gold-bordered containers: `strokeColor=#c9a96e;dashed=1;`
+
+## Edge Style → Draw.io Mapping
+
+Base edge style:
+```
+edgeStyle=orthogonalEdgeStyle;rounded=1;orthogonalLoop=1;jettySize=auto;html=1;
+```
+
+Arrow system:
+| Flow Type | strokeColor | strokeWidth | Additional |
+|-----------|-------------|-------------|------------|
+| Primary/structural | `#d4a574` | 2 | — (gold) |
+| Data flow | `#6ee7b7` | 1.5 | — (mint) |
+| Control/trigger | `#fdba74` | 1.5 | — (amber-orange) |
+| Reference/semantic | `#a39787` | 1 | `dashed=1` |
+| Dependency | `#a78bfa` | 1 | `dashed=1` |
+| Feedback/loop | `#d4a574` | 1.5 | `curved=1` |
+
+## Extras
+
+```
+strokeWidth=1.5   (on all shapes)
+sketch=0
+shadow=0
+```
+
+## Complete Vertex Style Templates
+
+For a service/API node (violet bucket):
+```
+rounded=1;whiteSpace=wrap;html=1;fillColor=#111111;strokeColor=#a78bfa;strokeWidth=1.5;fontFamily=-apple-system,Helvetica Neue,Arial,PingFang SC,Microsoft YaHei,sans-serif;fontSize=13;fontColor=#a78bfa;fontStyle=1;
+```
+
+For a database node (sky blue bucket):
+```
+shape=cylinder3;whiteSpace=wrap;html=1;fillColor=#111111;strokeColor=#38bdf8;strokeWidth=1.5;fontFamily=-apple-system,Helvetica Neue,Arial,PingFang SC,Microsoft YaHei,sans-serif;fontSize=13;fontColor=#38bdf8;fontStyle=1;
+```
+
+For a section title (serif, gold):
+```
+text;html=1;fontFamily=Georgia,Times New Roman,serif;fontSize=14;fontColor=#c9a96e;fontStyle=1;
+```
+
+## Page Background
+
+```xml
+<mxGraphModel background="#0a0a0a">
+```

package/references/troubleshooting.md

@@ -0,0 +1,63 @@
+# Troubleshooting — Common Mistakes
+
+Read this when something looks wrong in the output (rendering, export, layout, edges) or when a CLI invocation fails. Most rows have a one-line fix.
+
+| Mistake | Fix |
+|---------|-----|
+| Missing `id="0"` and `id="1"` root cells | Always include both at the top of `<root>` |
+| Shapes not connected | `source` and `target` on edge must match existing shape `id` values |
+| Self-closing edge `mxCell` (`<mxCell ... edge="1" />`) | Use the expanded form with `<mxGeometry relative="1" as="geometry" />` child — self-closing edges won't render |
+| `--` inside XML comments | Illegal per XML spec — use single hyphens or rephrase |
+| Special characters in `value` | Use XML entities: `&amp;` `&lt;` `&gt;` `&quot;` |
+| Literal `\n` in label text | Use `&#xa;` for line breaks in `value` attributes |
+| Overlapping shapes | Scale spacing with complexity (200–350px); leave routing corridors |
+| Edges crossing through shapes | Add waypoints, distribute entry/exit points, or increase spacing |
+| Arrowhead overlaps bend | Final edge segment before target must be ≥20px — increase spacing or add waypoints |
+| Iteration loop never ends | After 5 rounds, suggest user open .drawio in draw.io desktop for fine-tuning |
+| `command not found: draw.io` after `brew install --cask drawio` | Homebrew installs the binary as `drawio` (no dot). Use `drawio --version`, not `draw.io --version`. The dot-name only exists inside the `.app` bundle (`/Applications/draw.io.app/Contents/MacOS/draw.io`) and on Windows (`draw.io.exe`). |
+| Export command not found on macOS | Try full path `/Applications/draw.io.app/Contents/MacOS/draw.io` |
+| Vision returns "Unable to resize image — dimensions exceed the 2576x2576px limit" | The preview PNG is too large for Claude's vision API. Re-export with `--width 2000` instead of `-s 2` (the flag is `--width`; there is no short `-w` — passing `-w 2000` silently breaks input-file parsing and drawio errors with "input file/directory not found"). For very tall-narrow diagrams that still overshoot, use `--height 2000` instead. |
+| Linux: blank/error output headlessly | Prefix command with `xvfb-run -a` |
+| Linux: `--no-sandbox` placed before input file (parsed as filename) | Move `--no-sandbox` to the very end of the command (drawio-desktop#249, #1056) |
+| Linux: `Failed to get 'appData' path` / `Home directory not accessible` | `export HOME=/tmp` before invoking drawio (drawio-desktop#127) |
+| Linux server: segfault / EGL / MESA `failed to load driver` errors | Add `--disable-gpu` (suppresses Chromium GL init when no GPU available) |
+| PDF export fails | Ensure Chromium is available (draw.io bundles it on desktop) |
+| Background color wrong in CLI export | Known CLI bug; add `--transparent` flag or set background via style |
+| Vision returns 400 "Could not process image" on draft PNG | Re-export the preview without `-e` (issue #8). Root cause is a truncated IEND chunk in `-e` PNGs, not the `zTXt` chunk itself — but skipping `-e` for the preview is the simplest fix. |
+| Final `-e` PNG won't open in image viewers / vision APIs | Run `python3 <this-skill-dir>/scripts/repair_png.py <path>`. draw.io CLI emits `-e` PNGs with an 8-byte truncation at IEND. SVG/PDF unaffected. |
+| WSL2: `drawio` / `draw.io` not found | The CLI lives on the Windows side. Use the Windows desktop exe via `/mnt/c`: `"/mnt/c/Program Files/draw.io/draw.io.exe"` (or per-user `"/mnt/c/Users/<you>/AppData/Local/Programs/draw.io/draw.io.exe"`). |
+| WSL2: opening an exported file fails with a `/mnt/c/...`-style path | `cmd.exe` can't resolve WSL paths — convert first: `cmd.exe /c start "" "$(wslpath -w diagram.drawio.png)"`. The empty `""` after `start` is the (required) window title. |
+| Browser URL opens to a blank/empty diagram (Windows/WSL2) | `cmd.exe`'s `start` treats `&` as a separator and drops everything after `#` — so the `#R…`/`#create=…` fragment (the whole diagram) is lost. Never pass the URL straight to `start`. Write a `.url` shortcut file and open *that* (see "WSL2 / Windows" below). |
+
+## WSL2 / Windows specifics
+
+**Locate the CLI.** Detect WSL2 with `grep -qi microsoft /proc/version`. On WSL2 the
+export CLI is the Windows desktop exe, reached through `/mnt/c` (quote the path —
+it contains a space):
+
+```bash
+"/mnt/c/Program Files/draw.io/draw.io.exe" --version
+# per-user install fallback:
+"/mnt/c/Users/$USER/AppData/Local/Programs/draw.io/draw.io.exe" --version
+```
+
+**Open a file.** Convert the WSL path to a Windows path first; `cmd.exe` cannot
+follow `/mnt/c/...`:
+
+```bash
+cmd.exe /c start "" "$(wslpath -w diagram.drawio.png)"
+```
+
+**Open a browser-fallback URL.** `cmd.exe /c start` strips the URL fragment
+(`&` ends the command, `#…` is dropped) — and the fragment carries the entire
+diagram. Write a `.url` shortcut and open it instead, so the URL survives intact:
+
+```bash
+URL=$(python3 <this-skill-dir>/scripts/encode_drawio_url.py --edit diagram.drawio)
+TMP=$(mktemp --suffix=.url)
+printf '[InternetShortcut]\r\nURL=%s\r\n' "$URL" > "$TMP"
+cmd.exe /c start "" "$(wslpath -w "$TMP")"
+```
+
+On native Windows the same `.url`-file trick applies (`start "" "%TEMP%\d.url"`).
+On macOS/Linux just `open "$URL"` / `xdg-open "$URL"` — no workaround needed.