diff --git a/docs/README.instructions.md b/docs/README.instructions.md index 612846ec..082e37d0 100644 --- a/docs/README.instructions.md +++ b/docs/README.instructions.md @@ -89,6 +89,7 @@ See [CONTRIBUTING.md](../CONTRIBUTING.md#adding-instructions) for guidelines on | [Dev Box image definitions](../instructions/devbox-image-definition.instructions.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fdevbox-image-definition.instructions.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fdevbox-image-definition.instructions.md) | Authoring recommendations for creating YAML based image definition files for use with Microsoft Dev Box Team Customizations | | [DevOps Core Principles](../instructions/devops-core-principles.instructions.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fdevops-core-principles.instructions.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fdevops-core-principles.instructions.md) | Foundational instructions covering core DevOps principles, culture (CALMS), and key metrics (DORA) to guide GitHub Copilot in understanding and promoting effective software delivery. | | [Dotnet Wpf](../instructions/dotnet-wpf.instructions.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fdotnet-wpf.instructions.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fdotnet-wpf.instructions.md) | .NET WPF component and application patterns | +| [draw.io Diagram Standards](../instructions/draw-io.instructions.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fdraw-io.instructions.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fdraw-io.instructions.md) | Use when creating, editing, or reviewing draw.io diagrams and mxGraph XML in .drawio, .drawio.svg, or .drawio.png files. | | [Fedora Administration Guidelines](../instructions/fedora-linux.instructions.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Ffedora-linux.instructions.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Ffedora-linux.instructions.md) | Guidance for Fedora (Red Hat family) systems, dnf workflows, SELinux, and modern systemd practices. | | [Genaiscript](../instructions/genaiscript.instructions.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fgenaiscript.instructions.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fgenaiscript.instructions.md) | AI-powered script generation guidelines | | [Generate Modern Terraform Code For Azure](../instructions/generate-modern-terraform-code-for-azure.instructions.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fgenerate-modern-terraform-code-for-azure.instructions.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fgenerate-modern-terraform-code-for-azure.instructions.md) | Guidelines for generating modern Terraform code for Azure | diff --git a/docs/README.skills.md b/docs/README.skills.md index 1e759d94..68376e60 100644 --- a/docs/README.skills.md +++ b/docs/README.skills.md @@ -114,6 +114,7 @@ See [CONTRIBUTING.md](../CONTRIBUTING.md#adding-skills) for guidelines on how to | [dotnet-timezone](../skills/dotnet-timezone/SKILL.md) | .NET timezone handling guidance for C# applications. Use when working with TimeZoneInfo, DateTimeOffset, NodaTime, UTC conversion, daylight saving time, scheduling across timezones, cross-platform Windows/IANA timezone IDs, or when a .NET user needs the timezone for a city, address, region, or country and copy-paste-ready C# code. | `references/code-patterns.md`
`references/timezone-index.md` | | [dotnet-upgrade](../skills/dotnet-upgrade/SKILL.md) | Ready-to-use prompts for comprehensive .NET framework upgrade analysis and execution | None | | [doublecheck](../skills/doublecheck/SKILL.md) | Three-layer verification pipeline for AI output. Extracts verifiable claims, finds supporting or contradicting sources via web search, runs adversarial review for hallucination patterns, and produces a structured verification report with source links for human review. | `assets/verification-report-template.md` | +| [draw-io-diagram-generator](../skills/draw-io-diagram-generator/SKILL.md) | Use when creating, editing, or generating draw.io diagram files (.drawio, .drawio.svg, .drawio.png). Covers mxGraph XML authoring, shape libraries, style strings, flowcharts, system architecture, sequence diagrams, ER diagrams, UML class diagrams, network topology, layout strategy, the hediet.vscode-drawio VS Code extension, and the full agent workflow from request to a ready-to-open file. | `assets/templates`
`references/drawio-xml-schema.md`
`references/shape-libraries.md`
`references/style-reference.md`
`scripts/.gitignore`
`scripts/README.md`
`scripts/add-shape.py`
`scripts/validate-drawio.py` | | [editorconfig](../skills/editorconfig/SKILL.md) | Generates a comprehensive and best-practice-oriented .editorconfig file based on project analysis and user preferences. | None | | [ef-core](../skills/ef-core/SKILL.md) | Get best practices for Entity Framework Core | None | | [email-drafter](../skills/email-drafter/SKILL.md) | Draft and review professional emails that match your personal writing style. Analyzes your sent emails for tone, greeting, structure, and sign-off patterns via WorkIQ, then generates context-aware drafts for any recipient. USE FOR: draft email, write email, compose email, reply email, follow-up email, analyze email tone, email style. | None | diff --git a/instructions/draw-io.instructions.md b/instructions/draw-io.instructions.md new file mode 100644 index 00000000..684faa05 --- /dev/null +++ b/instructions/draw-io.instructions.md @@ -0,0 +1,144 @@ +--- +description: "Use when creating, editing, or reviewing draw.io diagrams and mxGraph XML in .drawio, .drawio.svg, or .drawio.png files." +applyTo: "**/*.drawio,**/*.drawio.svg,**/*.drawio.png" +--- + +# draw.io Diagram Standards + +> **Skill**: Load `.github/skills/draw-io/SKILL.md` for full workflow, XML recipes, and troubleshooting before generating or editing any `.drawio` file. + +--- + +## Required Workflow + +Follow these steps for every draw.io task: + +1. **Identify** the diagram type (flowchart / architecture / sequence / ER / UML / network / BPMN) +2. **Select** the matching template from `.github/skills/draw-io/templates/` and adapt it, or start from the minimal skeleton +3. **Plan** the layout on paper before writing XML — define tiers, actors, or entities first +4. **Generate** valid mxGraph XML following the rules below +5. **Validate** using `python .github/skills/draw-io/scripts/validate-drawio.py ` +6. **Confirm** the file renders by opening it in VS Code with the draw.io extension (`hediet.vscode-drawio`) + +--- + +## XML Structure Rules (Non-Negotiable) + +```xml + + + + + + + + + + + + +``` + +- `id="0"` and `id="1"` **must** be present and must be the first two cells — no exceptions +- Every cell `id` must be **unique** within the diagram +- Every vertex (`vertex="1"`) must have a child `` +- Every edge (`edge="1"`) must have `source`/`target` pointing to existing vertex ids — **exception**: floating edges (sequence diagram lifelines) use `` and `` inside `` instead of `source`/`target` attributes +- Every cell except id=0 must have `parent` pointing to an existing id +- Children of a container (swimlane) use **coordinates relative to their parent**, not the canvas + +--- + +## Mandatory Style Conventions + +### Semantic Color Palette — Use consistently across the project + +| Role | fillColor | strokeColor | +|---|---|---| +| Primary / Info (default) | `#dae8fc` | `#6c8ebf` | +| Success / Start / Positive | `#d5e8d4` | `#82b366` | +| Warning / Decision | `#fff2cc` | `#d6b656` | +| Error / End / Danger | `#f8cecc` | `#b85450` | +| Neutral / Interface | `#f5f5f5` | `#666666` | +| External / Partner | `#e1d5e7` | `#9673a6` | + +### Always include on vertex shapes + +``` +whiteSpace=wrap;html=1; +``` + +### Use `html=1` whenever a label contains HTML tags (``, ``, `
`) + +### Standard connectors + +``` +edgeStyle=orthogonalEdgeStyle;html=1; +``` + +--- + +## Diagram-Type Quick Reference + +| Type | Container | Key shapes | Connector style | +|---|---|---|---| +| Flowchart | None | `ellipse` (start/end), `rounded=1` (process), `rhombus` (decision) | `orthogonalEdgeStyle` | +| Architecture | `swimlane` per tier | `rounded=1` services, cloud/DB shapes | `orthogonalEdgeStyle` with labels | +| Sequence | None | `mxgraph.uml.actor`, dashed lifeline edges | `endArrow=block` (sync), `endArrow=open;dashed=1` (return) | +| ER Diagram | `shape=table;childLayout=tableLayout` | `shape=tableRow`, `shape=partialRectangle` | `entityRelationEdgeStyle;endArrow=ERmany;startArrow=ERone` | +| UML Class | `swimlane` per class | text rows for attributes/methods | `endArrow=block;endFill=0` (inherit), `dashed=1` (realize) | + +--- + +## Layout Best Practices + +- Align all coordinates to the **10 px grid** (values divisible by 10) +- **Horizontal**: 40–60 px gap between same-row shapes +- **Vertical**: 80–120 px gap between tier rows +- Standard shape size: `120 × 60` px (process), `200 × 100` px (decision diamond) +- Default canvas: A4 landscape `1169 × 827` px +- Maximum **40 cells per page** — split into multiple pages for larger diagrams +- Add a **title text cell** at top of every page: + ``` + style="text;strokeColor=none;fillColor=none;fontSize=18;fontStyle=1;align=center;" + ``` + +--- + +## File and Naming Conventions + +- Extension: `.drawio` for version-controlled diagrams, `.drawio.svg` for files embedded in Markdown +- Naming: `kebab-case` — e.g. `order-flow.drawio`, `database-schema.drawio` +- Location: `docs/` or `architecture/` alongside the code they document +- Multi-page: use one `` element per logical view within the same `` + +--- + +## Validation Checklist (run before every commit) + +- [ ] `` and `` are the first two cells +- [ ] All cell ids are unique within their diagram +- [ ] All edge `source`/`target` ids resolve to existing vertices +- [ ] All vertex cells have `` +- [ ] All cells (except id=0) have a valid `parent` +- [ ] XML is well-formed — no unclosed tags, no bare `&`, `<`, `>` in attribute values +- [ ] Semantic color palette used consistently +- [ ] Title cell present on every page + +```bash +# Run automated validation +python .github/skills/draw-io/scripts/validate-drawio.py +``` + +--- + +## Reference Files + +| File | Use For | +|---|---| +| `.github/skills/draw-io/SKILL.md` | Full agent workflow, recipes, troubleshooting | +| `.github/skills/draw-io/references/drawio-xml-schema.md` | Complete mxCell attribute reference | +| `.github/skills/draw-io/references/style-reference.md` | All style keys, shape names, edge types | +| `.github/skills/draw-io/references/shape-libraries.md` | Shape library catalog with style strings | +| `.github/skills/draw-io/templates/` | Ready-to-use `.drawio` templates per diagram type | +| `.github/skills/draw-io/scripts/validate-drawio.py` | XML structure validator | +| `.github/skills/draw-io/scripts/add-shape.py` | CLI: add a shape to an existing diagram | diff --git a/skills/draw-io-diagram-generator/SKILL.md b/skills/draw-io-diagram-generator/SKILL.md new file mode 100644 index 00000000..b39b6493 --- /dev/null +++ b/skills/draw-io-diagram-generator/SKILL.md @@ -0,0 +1,462 @@ +--- +name: draw-io-diagram-generator +description: Use when creating, editing, or generating draw.io diagram files (.drawio, .drawio.svg, .drawio.png). Covers mxGraph XML authoring, shape libraries, style strings, flowcharts, system architecture, sequence diagrams, ER diagrams, UML class diagrams, network topology, layout strategy, the hediet.vscode-drawio VS Code extension, and the full agent workflow from request to a ready-to-open file. +--- + +# Draw.io Diagram Generator + +This skill enables you to generate, edit, and validate draw.io (`.drawio`) diagram files with +correct mxGraph XML structure. All generated files open immediately in the +[Draw.io VS Code extension](https://marketplace.visualstudio.com/items?itemName=hediet.vscode-drawio) +(`hediet.vscode-drawio`) without any manual fixes required. You can also open the files in the draw.io web app or desktop app if you prefer. + +--- + +## 1. When to Use This Skill + +**Trigger phrases (load this skill when you see these)** + +- "create a diagram", "draw a flowchart", "generate an architecture diagram" +- "design a sequence diagram", "make a UML class diagram", "build an ER diagram" +- "add a .drawio file", "update the diagram", "visualise the flow" +- "document the architecture", "show the data model", "diagram the service interactions" +- Any request to produce or modify a `.drawio`, `.drawio.svg`, or `.drawio.png` file + +**Supported diagram types** + +| Diagram Type | Template Available | Description | +|---|---|---| +| Flowchart | `assets/templates/flowchart.drawio` | Process flows with decisions and branches | +| System Architecture | `assets/templates/architecture.drawio` | Multi-tier / layered service architecture | +| Sequence Diagram | `assets/templates/sequence.drawio` | Actor lifelines and timed message flows | +| ER Diagram | `assets/templates/er-diagram.drawio` | Database tables with relationships | +| UML Class Diagram | `assets/templates/uml-class.drawio` | Classes, interfaces, enums, relationships | +| Network Topology | (use shape library) | Routers, servers, firewalls, subnets | +| BPMN Workflow | (use shape library) | Business process events, tasks, gateways | +| Mind Map | (manual) | Central topic with radiating branches | + +--- + +## 2. Prerequisites + +- If running with VS Code integration enabled, Install the drawio extension: **draw.io VS Code extension** — `hediet.vscode-drawio` (extension id). Install with: + ``` + ext install hediet.vscode-drawio + ``` +- **Supported file extensions**: `.drawio`, `.drawio.svg`, `.drawio.png` +- **Python 3.8+** (optional) — for the validation and shape-insertion scripts in `scripts/` + +--- + +## 3. Step-by-Step Agent Workflow + +Follow these steps in order for every diagram generation task. + +### Step 1 — Understand the Request + +Ask or infer: +1. **Diagram type** — What kind of diagram? (flowchart, architecture, UML, ER, sequence, network...) +2. **Entities / actors** — What are the main components, actors, classes, or tables? +3. **Relationships** — How are they connected? What direction? What cardinality? +4. **Output path** — Where should the `.drawio` file be saved? +5. **Existing file** — Are we creating new or editing an existing file? + +If the request is ambiguous, infer the most sensible diagram type from context (e.g. "show the tables" → ER diagram, "show how the API call flows" → sequence diagram). + +### Step 2 — Select a Template or Start Fresh + +- **Use a template** when the diagram type matches one in `assets/templates/`. Copy the template structure and replace placeholder values. +- **Start fresh** for novel layouts. Begin with the minimal valid skeleton: + +```xml + + + + + + + + + + + + +``` + +> **Rule**: ids `0` and `1` are ALWAYS required and must be the first two cells. Never reuse them. + +### Step 3 — Plan the Layout + +Before generating XML, sketch the logical placement: +- Organise into **rows** or **tiers** (use swimlanes for layers) +- **Horizontal spacing**: 40–60px between same-row shapes +- **Vertical spacing**: 80–120px between tier rows +- Standard shape size: `120x60` px for process boxes, `160x80` px for swimlanes +- Default canvas: A4 landscape = `1169 x 827` px + +### Step 4 — Generate the mxGraph XML + +**Vertex cell** (every shape): +```xml + + + +``` + +**Edge cell** (every connector): +```xml + + + +``` + +**Critical rules**: +- Every cell id must be **globally unique** within the file +- Every vertex must have an `mxGeometry` child with `x`, `y`, `width`, `height`, `as="geometry"` +- Every edge must have `source` and `target` matching existing vertex ids — **exception**: floating edges (e.g. sequence diagram lifelines) use `sourcePoint`/`targetPoint` inside `` instead; see §4 Sequence Diagram +- Every cell's `parent` must reference an existing cell id +- Use `html=1` in style when the label contains HTML (``, ``, `
`) +- Escape XML special characters in labels: `&` => `&`, `<` => `<`, `>` => `>` + +### Step 5 — Apply Correct Styles + +Use the standard semantic color palette for consistency: + +| Purpose | fillColor | strokeColor | +|---|---|---| +| Primary / Info | `#dae8fc` | `#6c8ebf` | +| Success / Start | `#d5e8d4` | `#82b366` | +| Warning / Decision | `#fff2cc` | `#d6b656` | +| Error / End | `#f8cecc` | `#b85450` | +| Neutral | `#f5f5f5` | `#666666` | +| External / Partner | `#e1d5e7` | `#9673a6` | + +Common style strings by diagram type: + +``` +# Rounded process box (flowchart) +rounded=1;whiteSpace=wrap;html=1;fillColor=#dae8fc;strokeColor=#6c8ebf; + +# Decision diamond +rhombus;whiteSpace=wrap;html=1;fillColor=#fff2cc;strokeColor=#d6b656; + +# Start/End terminal +ellipse;whiteSpace=wrap;html=1;fillColor=#d5e8d4;strokeColor=#82b366; + +# Database cylinder +shape=mxgraph.flowchart.database;whiteSpace=wrap;html=1;fillColor=#f8cecc;strokeColor=#b85450; + +# Swimlane container (tier) +swimlane;startSize=30;fillColor=#dae8fc;strokeColor=#6c8ebf;fontStyle=1; + +# UML class box +swimlane;fontStyle=1;align=center;startSize=40;fillColor=#dae8fc;strokeColor=#6c8ebf; + +# Interface / stereotype box +swimlane;fontStyle=3;align=center;startSize=40;fillColor=#f5f5f5;strokeColor=#666666; + +# ER table container +shape=table;startSize=30;container=1;collapsible=1;childLayout=tableLayout; + +# Orthogonal connector +edgeStyle=orthogonalEdgeStyle;html=1; + +# ER relationship (crow's foot) +edgeStyle=entityRelationEdgeStyle;html=1;endArrow=ERmany;startArrow=ERone; +``` + +> See `references/style-reference.md` for the complete style key catalog and `references/shape-libraries.md` for all shape library names. + +### Step 6 — Save and Validate + +1. **Write the file** to the requested path with `.drawio` extension +2. **Run the validator** (optional but recommended): + ```bash + python .github/skills/draw-io-diagram-generator/scripts/validate-drawio.py + ``` +3. **Tell the user** how to open the file: + > "Open `` in VS Code — it will render automatically with the draw.io extension. You can use draw.io's web app or desktop app as well if you prefer." +4. **Provide a brief description** of what is in the diagram so the user knows what to expect. + +--- + +## 4. Diagram-Type Recipes + +### Flowchart + +Key elements: Start (ellipse) => Process (rounded rectangle) => Decision (diamond) => End (ellipse) + +```xml + + + + + + + + + + + + + + + + + + + +``` + +### Architecture Diagram (3-tier) + +Use **swimlane containers** for each tier. All service boxes are children of their swimlane. + +```xml + + + + + + + + + +``` + +> Connectors between tiers use absolute coordinates with `parent="1"`. + +### Sequence Diagram + +Key elements: Actors (top), Lifelines (dashed vertical lines), Activation boxes, Message arrows. + +- Lifelines: `edge="1"` with `endArrow=none` and `dashed=1`, no source/target — use `sourcePoint`/`targetPoint` in geometry +- Synchronous message: `endArrow=block;endFill=1` +- Return message: `endArrow=open;endFill=0;dashed=1` +- Self-call: loop the edge via two Array points to the right and back + +**Minimal XML snippet:** + +```xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +``` + +> **Note:** Lifelines are floating edges that use `sourcePoint`/`targetPoint` in `` instead of `source`/`target` attributes. This is the standard draw.io pattern for sequence diagrams. + +### ER Diagram + +Use `shape=table` containers with `childLayout=tableLayout`. Rows are `shape=tableRow` cells with `portConstraint=eastwest`. Columns inside each row are `shape=partialRectangle`. + +Relationship arrows use `edgeStyle=entityRelationEdgeStyle`: +- One-to-One: `startArrow=ERone;endArrow=ERone` +- One-to-Many: `startArrow=ERone;endArrow=ERmany` +- Many-to-Many: `startArrow=ERmany;endArrow=ERmany` +- Mandatory: `ERmandOne`, Optional: `ERzeroToOne` + +### UML Class Diagram + +Class boxes are swimlane containers. Attributes and methods are plain text cells. Dividers are zero-height swimlane children. + +Arrow styles by relationship type: + +| Relationship | Style String | +|---|---| +| Inheritance (extends) | `edgeStyle=orthogonalEdgeStyle;html=1;endArrow=block;endFill=0;` | +| Realization (implements) | `edgeStyle=orthogonalEdgeStyle;dashed=1;html=1;endArrow=block;endFill=0;` | +| Composition | `edgeStyle=orthogonalEdgeStyle;html=1;startArrow=diamond;startFill=1;endArrow=none;` | +| Aggregation | `edgeStyle=orthogonalEdgeStyle;html=1;startArrow=diamond;startFill=0;endArrow=none;` | +| Dependency | `edgeStyle=orthogonalEdgeStyle;dashed=1;html=1;endArrow=open;endFill=0;` | +| Association | `edgeStyle=orthogonalEdgeStyle;html=1;endArrow=open;endFill=0;` | + +--- + +## 5. Multi-Page Diagrams + +Add multiple `` elements for complex systems: + +```xml + + + + + + + + +``` + +Each page has its own independent cell id namespace. The same id value can appear in different pages without conflict. + +--- + +## 6. Editing Existing Diagrams + +When modifying an existing `.drawio` file: + +1. **Read** the file first to understand existing cell ids, positions, and parent hierarchy +2. **Identify the target diagram page** — by index or `name` attribute +3. **Assign new unique ids** that do not collide with existing ids +4. **Respect the container hierarchy** — children of a swimlane use coordinates relative to their parent +5. **Verify edges** — after repositioning nodes, confirm edge source/target ids remain valid + +Use `scripts/add-shape.py` to safely add a single shape without editing raw XML: +```bash +python .github/skills/draw-io-diagram-generator/scripts/add-shape.py docs/arch.drawio "New Service" 700 380 +``` + +--- + +## 7. Best Practices + +**Layout** +- Align shapes to the 10px grid (all coordinates divisible by 10) +- Group related shapes inside swimlane containers +- One diagram topic per page; use multi-page files for complex systems +- Aim for 40 or fewer cells per page for readability + +**Labels** +- Add a title text cell (`text;strokeColor=none;fillColor=none;fontSize=18;fontStyle=1`) at top of every page +- Always set `whiteSpace=wrap;html=1` on vertex shapes +- Keep labels concise — 3 words or fewer per shape where possible + +**Style consistency** +- Use the semantic color palette from Section 3 Step 5 consistently across a project +- Prefer `edgeStyle=orthogonalEdgeStyle` for clean right-angle connectors +- Do not inline arbitrary HTML in labels unless necessary + +**File naming** +- Use kebab-case: `order-service-flow.drawio`, `database-schema.drawio` +- Place diagrams alongside the code they document: `docs/` or `architecture/` + +--- + +## 8. Troubleshooting + +| Problem | Likely Cause | Fix | +|---|---|---| +| File opens blank in VS Code | Missing id=0 or id=1 cell | Add both root cells before any other cells | +| Shape at wrong position | Child inside container — coords are relative | Check `parent`; adjust x/y relative to container | +| Edge not visible | source or target id does not match any vertex | Verify both ids exist exactly as written | +| Diagram shows "Compressed" | mxGraphModel is base64-encoded | Open in draw.io web, File > Export > XML (uncompressed) | +| Shape style not rendering | Typo in shape= name | Check `references/shape-libraries.md` for exact style string | +| Label shows escaped HTML | html=0 on a cell with HTML label | Add `html=1;` to the cell style | +| Container children overlap container edge | Container height too small | Increase container height in mxGeometry | + +--- + +## 9. Validation Checklist + +Before delivering any generated `.drawio` file, verify: + +- [ ] File starts with `` root element +- [ ] Every `` has a non-empty `id` attribute +- [ ] `` is the first cell in every diagram +- [ ] `` is the second cell in every diagram +- [ ] All cell `id` values are unique within each diagram +- [ ] Every vertex cell has `vertex="1"` and a child `` +- [ ] Every edge cell has `edge="1"` and either: (a) `source`/`target` pointing to existing vertex ids, or (b) `` and `` in its `` (floating edge — used for sequence diagram lifelines) +- [ ] Every cell (except id=0) has a `parent` pointing to an existing id +- [ ] `html=1` is in the style for any label containing HTML tags +- [ ] XML is well-formed (no unclosed tags, no unescaped `&`, `<`, `>` in attribute values) +- [ ] A title label cell exists at the top of each page + +Run the automated validator: +```bash +python .github/skills/draw-io-diagram-generator/scripts/validate-drawio.py +``` + +--- + +## 10. Output Format + +When delivering a diagram, always provide: + +1. **The `.drawio` file** written to the requested path +2. **A one-sentence summary** of what the diagram shows +3. **How to open it**: + > "Open `` in VS Code — the draw.io extension will render it automatically. Or you can open it in the draw.io web app or desktop app if you prefer." +4. **How to edit it** (if the user is likely to customise): + > "Click any shape to select it. Double-click to edit the label. Drag to reposition." +5. **Validation status** — whether the validator script was run and passed + +--- + +## 11. References + +All companion files are in `.github/skills/draw-io-diagram-generator/`: + +| File | Contents | +|---|---| +| `references/drawio-xml-schema.md` | Complete mxfile / mxGraphModel / mxCell attribute reference, coordinate system, reserved cells, validation rules | +| `references/style-reference.md` | All style keys with allowed values, vertex and edge style keys, shape catalog, semantic color palette | +| `references/shape-libraries.md` | All shape library categories (General, Flowchart, UML, ER, Network, BPMN, Mockup, K8s) with style strings | +| `assets/templates/flowchart.drawio` | Ready-to-use flowchart template | +| `assets/templates/architecture.drawio` | 4-tier system architecture template | +| `assets/templates/sequence.drawio` | 3-actor sequence diagram template | +| `assets/templates/er-diagram.drawio` | 3-table ER diagram with crow's foot relationships | +| `assets/templates/uml-class.drawio` | Interface + 2 classes + enum with relationship arrows | +| `scripts/validate-drawio.py` | Python script to validate XML structure of any .drawio file | +| `scripts/add-shape.py` | Python CLI to add a new shape to an existing diagram | +| `scripts/README.md` | How to use the scripts with examples | diff --git a/skills/draw-io-diagram-generator/assets/templates/architecture.drawio b/skills/draw-io-diagram-generator/assets/templates/architecture.drawio new file mode 100644 index 00000000..46c94b32 --- /dev/null +++ b/skills/draw-io-diagram-generator/assets/templates/architecture.drawio @@ -0,0 +1,160 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/skills/draw-io-diagram-generator/assets/templates/er-diagram.drawio b/skills/draw-io-diagram-generator/assets/templates/er-diagram.drawio new file mode 100644 index 00000000..f535fd9f --- /dev/null +++ b/skills/draw-io-diagram-generator/assets/templates/er-diagram.drawio @@ -0,0 +1,375 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/skills/draw-io-diagram-generator/assets/templates/flowchart.drawio b/skills/draw-io-diagram-generator/assets/templates/flowchart.drawio new file mode 100644 index 00000000..632c5a3c --- /dev/null +++ b/skills/draw-io-diagram-generator/assets/templates/flowchart.drawio @@ -0,0 +1,63 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/skills/draw-io-diagram-generator/assets/templates/sequence.drawio b/skills/draw-io-diagram-generator/assets/templates/sequence.drawio new file mode 100644 index 00000000..85b54b1e --- /dev/null +++ b/skills/draw-io-diagram-generator/assets/templates/sequence.drawio @@ -0,0 +1,169 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/skills/draw-io-diagram-generator/assets/templates/uml-class.drawio b/skills/draw-io-diagram-generator/assets/templates/uml-class.drawio new file mode 100644 index 00000000..b69315a7 --- /dev/null +++ b/skills/draw-io-diagram-generator/assets/templates/uml-class.drawio @@ -0,0 +1,224 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/skills/draw-io-diagram-generator/references/drawio-xml-schema.md b/skills/draw-io-diagram-generator/references/drawio-xml-schema.md new file mode 100644 index 00000000..f321927e --- /dev/null +++ b/skills/draw-io-diagram-generator/references/drawio-xml-schema.md @@ -0,0 +1,379 @@ +# draw.io XML Schema Reference + +Complete reference for the `.drawio` file format (mxGraph XML). Use this when generating, parsing, or validating diagram files. + +--- + +## Top-Level Structure + +Every `.drawio` file is XML with this root structure: + +```xml + + + + + + + + + + + + +``` + +### `` Attributes + +| Attribute | Required | Default | Description | +| ----------- | ---------- | --------- | ------------- | +| `host` | No | `"app.diagrams.net"` | Origin editor (`"Electron"` for desktop/VS Code) | +| `modified` | No | — | ISO 8601 timestamp | +| `agent` | No | — | User agent string | +| `version` | No | — | draw.io version | +| `type` | No | `"device"` | Storage type | + +### `` Attributes + +| Attribute | Required | Description | +| ----------- | ---------- | ------------- | +| `id` | Yes | Unique page identifier (any string) | +| `name` | Yes | Tab label shown in editor | + +### `` Attributes + +| Attribute | Type | Default | Description | +| ----------- | ------ | --------- | ------------- | +| `dx` | int | `1422` | Scroll X offset | +| `dy` | int | `762` | Scroll Y offset | +| `grid` | `0`/`1` | `1` | Show grid | +| `gridSize` | int | `10` | Grid snap size in px | +| `guides` | `0`/`1` | `1` | Show alignment guides | +| `tooltips` | `0`/`1` | `1` | Enable tooltips | +| `connect` | `0`/`1` | `1` | Enable connection arrows on hover | +| `arrows` | `0`/`1` | `1` | Show directional arrows | +| `fold` | `0`/`1` | `1` | Enable group fold/collapse | +| `page` | `0`/`1` | `1` | Show page boundary | +| `pageScale` | float | `1` | Page zoom scale | +| `pageWidth` | int | `1169` | Page width in px (A4 landscape) | +| `pageHeight` | int | `827` | Page height in px (A4 landscape) | +| `math` | `0`/`1` | `0` | Enable LaTeX math rendering | +| `shadow` | `0`/`1` | `0` | Global shadow on shapes | + +**Common page sizes (px at 96dpi):** + +| Format | Width | Height | +| -------- | ------- | -------- | +| A4 landscape | `1169` | `827` | +| A4 portrait | `827` | `1169` | +| A3 landscape | `1654` | `1169` | +| Letter landscape | `1100` | `850` | +| Letter portrait | `850` | `1100` | +| Screen (16:9) | `1654` | `931` | + +--- + +## Reserved Cells (Always Required) + +```xml + + +``` + +These two cells MUST be the first entries inside ``. IDs `0` and `1` are reserved and must not be used for any other cell. + +--- + +## Vertex (Shape) Element + +```xml + + + +``` + +### `` Vertex Attributes + +| Attribute | Required | Type | Description | +| ----------- | ---------- | ------ | ------------- | +| `id` | Yes | string | Unique identifier within this diagram | +| `value` | Yes | string | Label text (HTML allowed if style has `html=1`) | +| `style` | Yes | string | Semicolon-delimited key=value style string | +| `vertex` | Yes | `"1"` | Must be `"1"` to declare this as a shape | +| `parent` | Yes | string | Parent cell ID (`"1"` for default layer) | + +### `` Vertex Attributes + +| Attribute | Required | Type | Description | +| ----------- | ---------- | ------ | ------------- | +| `x` | Yes | float | Left edge of shape (px from canvas origin) | +| `y` | Yes | float | Top edge of shape (px from canvas origin) | +| `width` | Yes | float | Shape width in px | +| `height` | Yes | float | Shape height in px | +| `as` | Yes | `"geometry"` | Always `"geometry"` | + +--- + +## Edge (Connector) Element + +```xml + + + +``` + +### `` Edge Attributes + +| Attribute | Required | Type | Description | +| ----------- | ---------- | ------ | ------------- | +| `id` | Yes | string | Unique identifier | +| `value` | Yes | string | Connector label (empty string for no label) | +| `style` | Yes | string | Style string (see Edge Styles) | +| `edge` | Yes | `"1"` | Must be `"1"` to declare as connector | +| `source` | No | string | ID of source vertex | +| `target` | No | string | ID of target vertex | +| `parent` | Yes | string | Parent cell ID (usually `"1"`) | + +### `` Edge Attributes + +| Attribute | Required | Type | Description | +| ----------- | ---------- | ------ | ------------- | +| `relative` | No | `"1"` | Always `"1"` for edges | +| `as` | Yes | `"geometry"` | Always `"geometry"` | + +### Edge with Label Offset + +```xml + + + +``` + +The `x` on relative geometry moves the label along the edge (-1 to 1). `y` is perpendicular offset in px. + +### Edge with Manual Waypoints (Control Points) + +```xml + + + + + + +``` + +--- + +## Multi-Page Diagrams + +```xml + + + ... + + + ... + + +``` + +Each `` is a separate page/tab. Cell IDs are scoped to their own `` — the same ID value can appear in different pages without conflict. + +--- + +## Layer Cells + +Layers replace the default `id="1"` layer. Cells are assigned to a layer via `parent`: + +```xml + + + + + + + + + +``` + +Toggle layer visibility: + +```xml + +``` + +--- + +## Swimlane Container + +```xml + + + + + + + + + + + + + + +``` + +> **Key**: Cells inside a swimlane have `parent` set to the **lane's ID**, not `"1"`. +> Coordinates inside lanes are **relative to the lane origin**. + +--- + +## Group Cells + +```xml + + + + + + + + + +``` + +--- + +## HTML Labels + +When `html=1` is in the style, `value` can contain HTML: + +```xml + + + +``` + +HTML must be XML-escaped: + +- `<` → `<` +- `>` → `>` +- `&` → `&` +- `"` → `"` + +Common HTML tags supported: ``, ``, ``, `
`, ``, ``, `
` + +--- + +## Tooltip / Metadata + +```xml + + + +``` + +--- + +## ID Generation Rules + +| Rule | Detail | +| ------ | -------- | +| IDs `0` and `1` | Reserved — always the root and default layer | +| All other IDs | Must be unique within their `` | +| Safe pattern | Sequential integers starting at `2`, or UUID strings | +| Cross-page | IDs do not need to be unique across different `` pages | + +**Safe sequential ID example:** + +```text +id="2", id="3", id="4", ... +``` + +**UUID-style example:** + +```text +id="a1b2c3d4-e5f6-7890-abcd-ef1234567890" +``` + +--- + +## Coordinate System + +- Origin `(0, 0)` is **top-left** of the canvas +- `x` increases **rightward** +- `y` increases **downward** +- All units are **pixels** + +--- + +## Recommended Spacing + +| Context | Value | +| --------- | ------- | +| Minimum gap between shapes | `40px` | +| Comfortable gap | `80px` | +| Swimlane inner padding | `20px` | +| Page margin from edge | `40px` | +| Connector routing clearance | `10px` | + +--- + +## Minimal Valid `.drawio` File + +```xml + + + + + + + + + + +``` + +--- + +## Validation Rules + +### Must Pass + +- [ ] `id="0"` and `id="1"` cells always present as first two children of `` +- [ ] No other cell uses `id="0"` or `id="1"` +- [ ] All `id` values are unique within each `` +- [ ] Every `` has exactly one `` child +- [ ] `` has `as="geometry"` attribute +- [ ] Vertex cells have `vertex="1"`, edge cells have `edge="1"` +- [ ] Edge `source`/`target` IDs reference existing vertex IDs in the same diagram +- [ ] Swimlane children have `parent` set to the swimlane/lane ID, not `"1"` +- [ ] HTML in `value` attributes is XML-escaped + +### Recommended + +- [ ] Shapes do not overlap unless intentional (use ≥40px gap) +- [ ] Edge labels are short (≤4 words) +- [ ] Layer cells have descriptive `value` names +- [ ] All shapes fit within `pageWidth` × `pageHeight` bounds diff --git a/skills/draw-io-diagram-generator/references/shape-libraries.md b/skills/draw-io-diagram-generator/references/shape-libraries.md new file mode 100644 index 00000000..5fe74751 --- /dev/null +++ b/skills/draw-io-diagram-generator/references/shape-libraries.md @@ -0,0 +1,334 @@ +# draw.io Shape Libraries + +Reference guide for all built-in shape libraries. Enable via `View > Shapes` in the draw.io editor (or VS Code extension shape panel). + +--- + +## Library Catalog + +### General + +**Enable**: Always active by default + +Common shapes for any diagram type. + +| Shape | Style Key | Use For | +| ------- | ----------- | --------- | +| Rectangle | *(default)* | Boxes, steps, components | +| Rounded Rectangle | `rounded=1;` | Softer process boxes | +| Ellipse | `ellipse;` | States, start/end | +| Triangle | `triangle;` | Arrows, gates | +| Diamond | `rhombus;` | Decisions | +| Hexagon | `shape=hexagon;` | Labels, tech icons | +| Cloud | `shape=cloud;` | Cloud services | +| Cylinder | `shape=cylinder3;` | Databases | +| Note | `shape=note;` | Annotations | +| Document | `shape=document;` | Files | +| Arrow shapes | Various `mxgraph.arrows2.*` | Flow directions | +| Callouts | `shape=callout;` | Speech bubbles | + +--- + +### Flowchart + +**Enable**: `View > Shapes > Flowchart` +**Shape prefix**: `mxgraph.flowchart.` + +Standard ANSI/ISO flowchart symbols. + +| Symbol | Style String | ANSI Name | +| -------- | ------------- | ----------- | +| Start / End | `ellipse;` | Terminal | +| Process (rectangle) | `rounded=1;` | Process | +| Decision | `rhombus;` | Decision | +| I/O (parallelogram) | `shape=mxgraph.flowchart.io;` | Data | +| Predefined Process | `shape=mxgraph.flowchart.predefined_process;` | Predefined Process | +| Manual Operation | `shape=mxgraph.flowchart.manual_operation;` | Manual Operation | +| Manual Input | `shape=mxgraph.flowchart.manual_input;` | Manual Input | +| Database | `shape=mxgraph.flowchart.database;` | Direct Access Storage | +| Document | `shape=mxgraph.flowchart.document;` | Document | +| Multiple Documents | `shape=mxgraph.flowchart.multi-document;` | Multiple Documents | +| On-page Connector | `ellipse;` (small, 30×30) | Connector | +| Off-page Connector | `shape=mxgraph.flowchart.off_page_connector;` | Off-page Connector | +| Preparation | `shape=mxgraph.flowchart.preparation;` | Preparation | +| Delay | `shape=mxgraph.flowchart.delay;` | Delay | +| Display | `shape=mxgraph.flowchart.display;` | Display | +| Internal Storage | `shape=mxgraph.flowchart.internal_storage;` | Internal Storage | +| Sort | `shape=mxgraph.flowchart.sort;` | Sort | +| Extract | `shape=mxgraph.flowchart.extract;` | Extract | +| Merge | `shape=mxgraph.flowchart.merge;` | Merge | +| Or | `shape=mxgraph.flowchart.or;` | Or | +| Annotation | `shape=mxgraph.flowchart.annotation;` | Annotation | +| Card | `shape=mxgraph.flowchart.card;` | Punched Card | + +**Complete flowchart example style strings:** + +```text +Process: rounded=1;whiteSpace=wrap;html=1; +Decision: rhombus;whiteSpace=wrap;html=1; +Start/End: ellipse;whiteSpace=wrap;html=1; +Database: shape=mxgraph.flowchart.database;whiteSpace=wrap;html=1; +Document: shape=mxgraph.flowchart.document;whiteSpace=wrap;html=1; +I/O (Data): shape=mxgraph.flowchart.io;whiteSpace=wrap;html=1; +``` + +--- + +### UML + +**Enable**: `View > Shapes > UML` + +#### Use Case Diagrams + +| Shape | Style String | +| ------- | ------------- | +| Actor | `shape=mxgraph.uml.actor;whiteSpace=wrap;html=1;` | +| Use Case (ellipse) | `ellipse;whiteSpace=wrap;html=1;` | +| System Boundary | `swimlane;startSize=30;whiteSpace=wrap;html=1;` | + +#### Class Diagrams + +Use swimlane containers for class boxes: + +```xml + + + + + + + + + + + + + + + + + + + +``` + +#### UML Relationship Arrows + +| Relationship | Style String | +| ------------- | ------------- | +| Inheritance (extends) | `edgeStyle=orthogonalEdgeStyle;html=1;endArrow=block;endFill=0;` | +| Implementation (implements) | `edgeStyle=orthogonalEdgeStyle;dashed=1;html=1;endArrow=block;endFill=0;` | +| Association | `edgeStyle=orthogonalEdgeStyle;html=1;endArrow=open;endFill=0;` | +| Dependency | `edgeStyle=orthogonalEdgeStyle;dashed=1;html=1;endArrow=open;endFill=0;` | +| Aggregation | `edgeStyle=orthogonalEdgeStyle;html=1;startArrow=diamond;startFill=0;endArrow=none;` | +| Composition | `edgeStyle=orthogonalEdgeStyle;html=1;startArrow=diamond;startFill=1;endArrow=none;` | + +#### Component Diagram + +| Shape | Style String | +| ------- | ------------- | +| Component | `shape=component;align=left;spacingLeft=36;whiteSpace=wrap;html=1;` | +| Interface (lollipop) | `ellipse;whiteSpace=wrap;html=1;aspect=fixed;` (small circle) | +| Port | `shape=mxgraph.uml.port;` | +| Node | `shape=mxgraph.uml.node;whiteSpace=wrap;html=1;` | +| Artifact | `shape=mxgraph.uml.artifact;whiteSpace=wrap;html=1;` | + +#### Sequence Diagrams + +| Shape | Style String | +| ------- | ------------- | +| Actor | `shape=mxgraph.uml.actor;whiteSpace=wrap;html=1;` | +| Lifeline (object) | `shape=umlLifeline;startSize=40;whiteSpace=wrap;html=1;` | +| Activation box | `shape=umlActivation;whiteSpace=wrap;html=1;` | +| Sync message | `edgeStyle=elbowEdgeStyle;elbow=vertical;html=1;endArrow=block;endFill=1;` | +| Async message | `edgeStyle=elbowEdgeStyle;elbow=vertical;html=1;endArrow=open;endFill=0;` | +| Return | `edgeStyle=elbowEdgeStyle;elbow=vertical;dashed=1;html=1;endArrow=open;endFill=0;` | +| Self-call | `edgeStyle=elbowEdgeStyle;elbow=vertical;exitX=1;exitY=0.3;entryX=1;entryY=0.5;html=1;` | + +#### State Diagrams + +| Shape | Style String | +| ------- | ------------- | +| Initial state (solid circle) | `ellipse;html=1;aspect=fixed;fillColor=#000000;strokeColor=#000000;` | +| State | `rounded=1;whiteSpace=wrap;html=1;arcSize=50;` | +| Final state | `shape=doubleEllipse;fillColor=#000000;strokeColor=#000000;` | +| Transition | `edgeStyle=orthogonalEdgeStyle;html=1;endArrow=block;endFill=1;` | +| Fork/Join | `shape=mxgraph.uml.fork_or_join;html=1;fillColor=#000000;` | + +--- + +### Entity Relationship (ER Diagrams) + +**Enable**: `View > Shapes > Entity Relation` + +#### Modern ER Tables (crow's foot notation) + +```xml + + + + + + + + + + + + + + + + + + + + + + + + +``` + +#### ER Relationship Connectors (crow's foot) + +| Cardinality | Style String | +| ------------- | ------------- | +| One-to-one | `edgeStyle=entityRelationEdgeStyle;html=1;startArrow=ERmandOne;endArrow=ERmandOne;startFill=1;endFill=1;` | +| One-to-many | `edgeStyle=entityRelationEdgeStyle;html=1;startArrow=ERmandOne;endArrow=ERmany;startFill=1;endFill=1;` | +| Zero-to-many | `edgeStyle=entityRelationEdgeStyle;html=1;startArrow=ERmandOne;endArrow=ERzeroToMany;startFill=1;endFill=0;` | +| Zero-to-one | `edgeStyle=entityRelationEdgeStyle;html=1;startArrow=ERmandOne;endArrow=ERzeroToOne;startFill=1;endFill=0;` | +| Many-to-many | `edgeStyle=entityRelationEdgeStyle;html=1;startArrow=ERmany;endArrow=ERmany;startFill=1;endFill=1;` | + +--- + +### Network / Infrastructure + +**Enable**: `View > Shapes > Networking` + +| Shape | Style String | +| ------- | ------------- | +| Generic server | `shape=server;html=1;whiteSpace=wrap;` | +| Web server | `shape=mxgraph.network.web_server;` | +| Database server | `shape=mxgraph.network.database;` | +| Laptop | `shape=mxgraph.network.laptop;` | +| Desktop | `shape=mxgraph.network.desktop;` | +| Mobile phone | `shape=mxgraph.network.mobile;` | +| Router | `shape=mxgraph.cisco.routers.router;` | +| Switch | `shape=mxgraph.cisco.switches.workgroup_switch;` | +| Firewall | `shape=mxgraph.cisco.firewalls.firewall;` | +| Cloud (generic) | `shape=cloud;` | +| Internet | `shape=mxgraph.network.internet;` | +| Load balancer | `shape=mxgraph.network.load_balancer;` | + +--- + +### BPMN 2.0 + +**Enable**: `View > Shapes > BPMN` +**Shape prefix**: `shape=mxgraph.bpmn.*` + +| Shape | Style String | +| ------- | ------------- | +| Start event | `shape=mxgraph.bpmn.shape;perimeter=mxPerimeter.ellipsePerimeter;symbol=general;verticalLabelPosition=bottom;` | +| End event | `shape=mxgraph.bpmn.shape;perimeter=mxPerimeter.ellipsePerimeter;symbol=terminate;verticalLabelPosition=bottom;` | +| Task | `shape=mxgraph.bpmn.shape;perimeter=mxPerimeter.rectanglePerimeter;symbol=task;` | +| Exclusive gateway | `shape=mxgraph.bpmn.shape;perimeter=mxPerimeter.rhombusPerimeter;symbol=exclusiveGw;` | +| Parallel gateway | `shape=mxgraph.bpmn.shape;perimeter=mxPerimeter.rhombusPerimeter;symbol=parallelGw;` | +| Sub-process | `shape=mxgraph.bpmn.shape;perimeter=mxPerimeter.rectanglePerimeter;symbol=subProcess;` | +| Sequence flow | `edgeStyle=orthogonalEdgeStyle;html=1;endArrow=block;endFill=1;` | +| Message flow | `edgeStyle=orthogonalEdgeStyle;dashed=1;html=1;endArrow=block;endFill=0;` | +| Pool | `shape=pool;startSize=30;horizontal=1;` | +| Lane | `swimlane;startSize=30;` | + +--- + +### Mockup / Wireframe + +**Enable**: `View > Shapes > Mockup` + +| Shape | Style String | +| ------- | ------------- | +| Button | `shape=mxgraph.mockup.forms.button;` | +| Input field | `shape=mxgraph.mockup.forms.text1;` | +| Checkbox | `shape=mxgraph.mockup.forms.checkbox;` | +| Dropdown | `shape=mxgraph.mockup.forms.comboBox;` | +| Browser window | `shape=mxgraph.mockup.containers.browser;` | +| Mobile screen | `shape=mxgraph.mockup.containers.smartphone;` | +| List | `shape=mxgraph.mockup.containers.list;` | +| Table | `shape=mxgraph.mockup.containers.table;` | + +--- + +### Kubernetes + +**Enable**: `View > Shapes > Kubernetes` + +| Resource | Style String | +| ---------- | ------------- | +| Pod | `shape=mxgraph.kubernetes.pod;` | +| Deployment | `shape=mxgraph.kubernetes.deploy;` | +| Service | `shape=mxgraph.kubernetes.svc;` | +| Ingress | `shape=mxgraph.kubernetes.ing;` | +| ConfigMap | `shape=mxgraph.kubernetes.cm;` | +| Secret | `shape=mxgraph.kubernetes.secret;` | +| PersistentVolume | `shape=mxgraph.kubernetes.pv;` | +| Namespace | `shape=mxgraph.kubernetes.ns;` | +| Node | `shape=mxgraph.kubernetes.node;` | + +--- + +## Enabling Libraries in VS Code + +Libraries are enabled inside the draw.io editor (which VS Code embeds): + +1. Open any `.drawio` or `.drawio.svg` file in VS Code +2. Click the `+` icon in the shape panel (left sidebar) →`Search Shapes` or `More Shapes` +3. Check the library you want to activate +4. Shapes appear in the panel for drag-and-drop + +Libraries are stored per-user in draw.io settings (not per-project). + +--- + +## Custom Shape Library Creation + +A custom library is an XML file with `.xml` extension loaded via `File > Open Library`: + +```xml + + [ + { + "xml": "<mxCell value=\"Component\" style=\"rounded=1;whiteSpace=wrap;html=1;fillColor=#dae8fc;\" vertex=\"1\"><mxGeometry width=\"120\" height=\"60\" as=\"geometry\" /></mxCell>", + "w": 120, + "h": 60, + "aspect": "fixed", + "title": "My Component" + } + ] + +``` + +Each shape entry contains: +- `xml`: XML-escaped cell definition +- `w` / `h`: Default width/height +- `aspect`: `"fixed"` to lock ratio +- `title`: Name shown in panel + + } + ] + +``` diff --git a/skills/draw-io-diagram-generator/references/style-reference.md b/skills/draw-io-diagram-generator/references/style-reference.md new file mode 100644 index 00000000..a4093a3f --- /dev/null +++ b/skills/draw-io-diagram-generator/references/style-reference.md @@ -0,0 +1,410 @@ +# draw.io Style Reference + +Complete reference for the `style` attribute on `` elements. Styles are semicolon-delimited `key=value` pairs. + +--- + +## Style Format + +```text +style="key1=value1;key2=value2;key3=value3;" +``` + +- Keys and values are case-sensitive +- Trailing semicolon is optional but recommended +- Unknown keys are silently ignored +- Missing keys use draw.io defaults + +--- + +## Universal Style Keys + +Apply to all shapes and edges. + +| Key | Values | Default | Description | +| ----- | -------- | --------- | ------------- | +| `fillColor` | `#hex` / `none` | `#FFFFFF` | Shape fill color (draw.io default; use semantic palette for project diagrams) | +| `strokeColor` | `#hex` / `none` | `#000000` | Border/line color (draw.io default; use semantic palette for project diagrams) | +| `fontColor` | `#hex` | `#000000` | Text color | +| `fontSize` | integer | `11` | Font size in pt | +| `fontStyle` | bitmask (see below) | `0` | Bold/italic/underline | +| `fontFamily` | string | `Helvetica` | Font family name | +| `align` | `left`/`center`/`right` | `center` | Horizontal text alignment | +| `verticalAlign` | `top`/`middle`/`bottom` | `middle` | Vertical text alignment | +| `opacity` | 0–100 | `100` | Shape opacity (%) | +| `shadow` | `0`/`1` | `0` | Drop shadow | +| `dashed` | `0`/`1` | `0` | Dashed border | +| `dashPattern` | e.g. `8 8` | — | Custom dash/gap pattern (px) | +| `strokeWidth` | float | `2` | Border/line width in px | +| `spacing` | integer | `2` | Padding around text (px) | +| `spacingTop` | integer | `0` | Top text padding | +| `spacingBottom` | integer | `0` | Bottom text padding | +| `spacingLeft` | integer | `4` | Left text padding | +| `spacingRight` | integer | `4` | Right text padding | +| `html` | `0`/`1` | `0` | Allow HTML in label | +| `whiteSpace` | `wrap`/`nowrap` | `nowrap` | Text wrapping | +| `overflow` | `visible`/`hidden`/`fill` | `visible` | Text overflow behaviour | +| `rotatable` | `0`/`1` | `1` | Allow rotation in editor | +| `movable` | `0`/`1` | `1` | Allow move in editor | +| `resizable` | `0`/`1` | `1` | Allow resize in editor | +| `deletable` | `0`/`1` | `1` | Allow delete in editor | +| `editable` | `0`/`1` | `1` | Allow label edit in editor | +| `locked` | `0`/`1` | `0` | Lock all editing | +| `nolabel` | `0`/`1` | `0` | Hide label entirely | +| `noLabel` | `0`/`1` | `0` | Alias of `nolabel` | +| `labelPosition` | `left`/`center`/`right` | `center` | Label anchor horizontal | +| `verticalLabelPosition` | `top`/`middle`/`bottom` | `middle` | Label anchor vertical | +| `imageAlign` | `left`/`center`/`right` | `center` | Image alignment | + +### `fontStyle` Bitmask Values + +| Value | Effect | +| ------- | -------- | +| `0` | Normal | +| `1` | Bold | +| `2` | Italic | +| `4` | Underline | +| `8` | Strikethrough | + +Combine by addition: `3` = bold + italic, `5` = bold + underline, `7` = bold + italic + underline. + +--- + +## Shape Keys (Vertex Only) + +| Key | Values | Description | +| ----- | -------- | ------------- | +| `shape` | see Shape Catalog | Override default rectangle shape | +| `rounded` | `0`/`1` | Rounded corners on rectangle | +| `arcSize` | 0–50 | Corner radius % (when `rounded=1`) | +| `perimeter` | function name | Connection perimeter type | +| `aspect` | `fixed` | Lock aspect ratio on resize | +| `rotation` | float | Rotation in degrees | +| `fixedSize` | `0`/`1` | Prevent auto-size when editing label | +| `container` | `0`/`1` | Treat shape as container for children | +| `collapsible` | `0`/`1` | Allow collapse/expand toggle | +| `startSize` | integer | Header size in swimlane/container (px) | +| `swimlaneHead` | `0`/`1` | Show swimlane header | +| `swimlaneBody` | `0`/`1` | Show swimlane body | +| `fillOpacity` | 0–100 | Fill-only opacity (independent of `opacity`) | +| `strokeOpacity` | 0–100 | Stroke-only opacity | +| `gradientColor` | `#hex` / `none` | Gradient end color | +| `gradientDirection` | `north`/`south`/`east`/`west` | Gradient direction | +| `sketch` | `0`/`1` | Rough hand-drawn style | +| `comic` | `0`/`1` | Comic/cartoon line style | +| `glass` | `0`/`1` | Glass reflection effect | + +--- + +## Shape Catalog + +### Basic Shapes + +| Shape | Style String | Visual | +| ------- | ------------- | -------- | +| Rectangle (default) | *(no shape key needed)* | □ | +| Rounded rectangle | `rounded=1;` | ▢ | +| Ellipse / Circle | `ellipse;` | ○ | +| Diamond | `rhombus;` | ◇ | +| Triangle | `triangle;` | △ | +| Hexagon | `shape=hexagon;` | ⬡ | +| Pentagon | `shape=mxgraph.basic.pentagon;` | ⬠ | +| Star | `shape=mxgraph.basic.star;` | ★ | +| Cross | `shape=mxgraph.basic.x;` | ✕ | +| Cloud | `shape=cloud;` | ☁ | +| Note / Callout | `shape=note;folded=1;` | 📝 | +| Document | `shape=document;` | 📄 | +| Cylinder (database) | `shape=cylinder3;` | 🗄 | +| Tape | `shape=tape;` | — | +| Parallelogram | `shape=parallelogram;perimeter=parallelogramPerimeter;` | ▱ | + +### Flowchart Shapes (`mxgraph.flowchart.*`) + +| Shape | Style String | Used For | +| ------- | ------------- | ---------- | +| Process | `shape=mxgraph.flowchart.process;` | Standard process | +| Start/End (terminal) | `ellipse;` or `shape=mxgraph.flowchart.terminate;` | Flow start/end | +| Decision | `rhombus;` | Yes/No branch | +| Data (I/O) | `shape=mxgraph.flowchart.io;` | Input/Output | +| Predefined Process | `shape=mxgraph.flowchart.predefined_process;` | Subroutine | +| Manual Input | `shape=mxgraph.flowchart.manual_input;` | Manual entry | +| Manual Operation | `shape=mxgraph.flowchart.manual_operation;` | Manual step | +| Database | `shape=mxgraph.flowchart.database;` | Data store | +| Internal Storage | `shape=mxgraph.flowchart.internal_storage;` | Internal data | +| Direct Data | `shape=mxgraph.flowchart.direct_data;` | Drum storage | +| Document | `shape=mxgraph.flowchart.document;` | Document | +| Multi-document | `shape=mxgraph.flowchart.multi-document;` | Multiple docs | +| On-page Connector | `ellipse;` (small) | Page connector | +| Off-page Connector | `shape=mxgraph.flowchart.off_page_connector;` | Off-page ref | +| Preparation | `shape=mxgraph.flowchart.preparation;` | Initialization | +| Delay | `shape=mxgraph.flowchart.delay;` | Wait state | +| Display | `shape=mxgraph.flowchart.display;` | Output display | +| Sort | `shape=mxgraph.flowchart.sort;` | Sort operation | +| Extract | `shape=mxgraph.flowchart.extract;` | Extract operation | +| Merge | `shape=mxgraph.flowchart.merge;` | Merge paths | +| Or | `shape=mxgraph.flowchart.or;` | OR gate | +| And | `shape=mxgraph.flowchart.and;` | AND gate | +| Annotation | `shape=mxgraph.flowchart.annotation;` | Comment/note | + +### UML Shapes (`mxgraph.uml.*`) + +| Shape | Style String | Used For | +| ------- | ------------- | ---------- | +| Actor | `shape=mxgraph.uml.actor;` | Use-case actor | +| Boundary | `shape=mxgraph.uml.boundary;` | System boundary | +| Control | `shape=mxgraph.uml.control;` | Controller object | +| Entity | `shape=mxgraph.uml.entity;` | Entity object | +| Component | `shape=component;` | Component box | +| Package | `shape=mxgraph.uml.package;` | Package | +| Note | `shape=note;` | UML note | +| Lifeline | `shape=umlLifeline;startSize=40;` | Sequence lifeline | +| Activation | `shape=umlActivation;` | Activation box | +| Destroy | `shape=mxgraph.uml.destroy;` | Destroy marker | +| State | `ellipse;` | State node | +| Initial State | `ellipse;fillColor=#000000;` | UML initial state | +| Final State | `shape=doubleEllipse;fillColor=#000000;` | UML final state | +| Fork/Join | `shape=mxgraph.uml.fork_or_join;` | Fork/join bar | + +### Network Shapes (`mxgraph.network.*`) + +| Shape | Style String | +| ------- | ------------- | +| Server | `shape=server;` | +| Database server | `shape=mxgraph.network.database;` | +| Firewall | `shape=mxgraph.cisco.firewalls.firewall;` | +| Router | `shape=mxgraph.cisco.routers.router;` | +| Switch | `shape=mxgraph.cisco.switches.workgroup_switch;` | +| Cloud | `shape=cloud;` | +| Internet | `shape=mxgraph.network.internet;` | +| Laptop | `shape=mxgraph.network.laptop;` | +| Desktop | `shape=mxgraph.network.desktop;` | +| Mobile | `shape=mxgraph.network.mobile;` | + +### AWS Shapes (`mxgraph.aws4.*`) + +Use the AWS4 library. Common shapes: + +| Shape | Style String | +| ------- | ------------- | +| EC2 | `shape=mxgraph.aws4.resourceIcon;resIcon=mxgraph.aws4.ec2;` | +| Lambda | `shape=mxgraph.aws4.resourceIcon;resIcon=mxgraph.aws4.lambda;` | +| S3 | `shape=mxgraph.aws4.resourceIcon;resIcon=mxgraph.aws4.s3;` | +| RDS | `shape=mxgraph.aws4.resourceIcon;resIcon=mxgraph.aws4.rds;` | +| API Gateway | `shape=mxgraph.aws4.resourceIcon;resIcon=mxgraph.aws4.api_gateway;` | +| CloudFront | `shape=mxgraph.aws4.resourceIcon;resIcon=mxgraph.aws4.cloudfront;` | +| Load Balancer | `shape=mxgraph.aws4.resourceIcon;resIcon=mxgraph.aws4.elb;` | +| SQS | `shape=mxgraph.aws4.resourceIcon;resIcon=mxgraph.aws4.sqs;` | +| SNS | `shape=mxgraph.aws4.resourceIcon;resIcon=mxgraph.aws4.sns;` | +| DynamoDB | `shape=mxgraph.aws4.resourceIcon;resIcon=mxgraph.aws4.dynamodb;` | +| ECS | `shape=mxgraph.aws4.resourceIcon;resIcon=mxgraph.aws4.ecs;` | +| EKS | `shape=mxgraph.aws4.resourceIcon;resIcon=mxgraph.aws4.eks;` | +| VPC | `shape=mxgraph.aws4.group;grIcon=mxgraph.aws4.group_vpc;` | +| Region | `shape=mxgraph.aws4.group;grIcon=mxgraph.aws4.group_region;` | + +### Azure Shapes (`mxgraph.azure.*`) + +| Shape | Style String | +| ------- | ------------- | +| App Service | `shape=mxgraph.azure.app_service;` | +| Function App | `shape=mxgraph.azure.function_apps;` | +| SQL Database | `shape=mxgraph.azure.sql_database;` | +| Blob Storage | `shape=mxgraph.azure.blob_storage;` | +| API Management | `shape=mxgraph.azure.api_management;` | +| Service Bus | `shape=mxgraph.azure.service_bus;` | +| AKS | `shape=mxgraph.azure.aks;` | +| Container Registry | `shape=mxgraph.azure.container_registry_registries;` | + +### GCP Shapes (`mxgraph.gcp2.*`) + +| Shape | Style String | +| ------- | ------------- | +| Cloud Run | `shape=mxgraph.gcp2.cloud_run;` | +| Cloud Functions | `shape=mxgraph.gcp2.cloud_functions;` | +| Cloud SQL | `shape=mxgraph.gcp2.cloud_sql;` | +| Cloud Storage | `shape=mxgraph.gcp2.cloud_storage;` | +| GKE | `shape=mxgraph.gcp2.container_engine;` | +| Pub/Sub | `shape=mxgraph.gcp2.cloud_pubsub;` | +| BigQuery | `shape=mxgraph.gcp2.bigquery;` | + +--- + +## Edge Style Keys + +| Key | Values | Description | +| ----- | -------- | ------------- | +| `edgeStyle` | see below | Connection routing algorithm | +| `rounded` | `0`/`1` | Rounded corners on orthogonal edges | +| `curved` | `0`/`1` | Curved line segments | +| `orthogonal` | `0`/`1` | Force orthogonal routing | +| `jettySize` | `auto`/integer | Source/target jet size | +| `exitX` | 0.0–1.0 | Source exit point X (0=left, 0.5=center, 1=right) | +| `exitY` | 0.0–1.0 | Source exit point Y (0=top, 0.5=center, 1=bottom) | +| `exitDx` | float | Source exit X offset (px) | +| `exitDy` | float | Source exit Y offset (px) | +| `entryX` | 0.0–1.0 | Target entry point X | +| `entryY` | 0.0–1.0 | Target entry point Y | +| `entryDx` | float | Target entry X offset (px) | +| `entryDy` | float | Target entry Y offset (px) | +| `endArrow` | see Arrow Types | Arrow head at target | +| `startArrow` | see Arrow Types | Arrow tail at source | +| `endFill` | `0`/`1` | Filled end arrow head | +| `startFill` | `0`/`1` | Filled start arrow head | +| `endSize` | integer | End arrow head size (px) | +| `startSize` | integer | Start arrow head size (px) | +| `labelBackgroundColor` | `#hex`/`none` | Label background fill | +| `labelBorderColor` | `#hex`/`none` | Label border color | + +### `edgeStyle` Values + +| Value | Routing | Use When | +| ------- | --------- | ---------- | +| `none` | Straight line | Simple direct connections | +| `orthogonalEdgeStyle` | Right-angle turns | Flowcharts, architecture | +| `elbowEdgeStyle` | Single elbow | Clean directional diagrams | +| `entityRelationEdgeStyle` | ER-style routing | ER diagrams | +| `segmentEdgeStyle` | Segmented with handles | Fine-tuned routing | +| `isometricEdgeStyle` | Isometric grid | Isometric diagrams | + +### Arrow Types (`endArrow` / `startArrow`) + +| Value | Shape | Use For | +| ------- | ------- | --------- | +| `block` | Filled triangle | Standard directed arrow | +| `open` | Open chevron → | Open/light arrow | +| `classic` | Classic arrow | Default draw.io arrow | +| `classicThin` | Thin classic | Compact diagrams | +| `none` | No arrowhead | Undirected lines | +| `oval` | Circle dot | Aggregation start | +| `diamond` | Hollow diamond | Aggregation | +| `diamondThin` | Thin diamond | Slim diagrams | +| `ERone` | `\|` bar | ER cardinality "one" | +| `ERmany` | Crow's foot | ER cardinality "many" | +| `ERmandOne` | `\|\|` | ER mandatory one | +| `ERzeroToOne` | `o\|` | ER zero-or-one | +| `ERzeroToMany` | `o<` | ER zero-or-many | +| `ERoneToMany` | `\|<` | ER one-or-many | + +--- + +## Color Palette + +### Semantic Colors (Recommended for Consistent Diagrams) + +| Meaning | Fill | Stroke | Usage | +| --------- | ------ | -------- | ------- | +| User / Client | `#dae8fc` | `#6c8ebf` | Browser, client apps | +| Service / Process | `#d5e8d4` | `#82b366` | Backend services | +| Database / Storage | `#f5f5f5` | `#666666` | Databases, files | +| Decision / Warning | `#fff2cc` | `#d6b656` | Decision nodes, alerts | +| Error / Critical | `#f8cecc` | `#b85450` | Error paths, critical | +| External / Partner | `#e1d5e7` | `#9673a6` | 3rd party, external | +| Queue / Async | `#ffe6cc` | `#d79b00` | Message queues | +| Gateway / Proxy | `#dae8fc` | `#0050ef` | API gateways, proxies | + +### Dark Background Shapes + +For dark-themed diagrams, swap to: + +- Fill: `#1e4d78` (dark blue), `#1a4731` (dark green) +- Stroke: `#4aa3df`, `#67ab9f` +- Font: `#ffffff` + +--- + +## Complete Style Examples + +### Rounded Blue Box + +```text +rounded=1;whiteSpace=wrap;html=1;fillColor=#dae8fc;strokeColor=#6c8ebf; +``` + +### Green Process Step + +```text +rounded=1;whiteSpace=wrap;html=1;fillColor=#d5e8d4;strokeColor=#82b366; +``` + +### Yellow Decision Diamond + +```text +rhombus;whiteSpace=wrap;html=1;fillColor=#fff2cc;strokeColor=#d6b656; +``` + +### Red Error Box + +```text +rounded=1;whiteSpace=wrap;html=1;fillColor=#f8cecc;strokeColor=#b85450; +``` + +### Database Cylinder + +```text +shape=cylinder3;whiteSpace=wrap;html=1;boundedLbl=1;backgroundOutline=1;fillColor=#f5f5f5;strokeColor=#666666; +``` + +### Swimlane Container + +```text +shape=pool;startSize=30;horizontal=1;fillColor=#f5f5f5;strokeColor=#999999; +``` + +### Swimlane Lane + +```text +swimlane;startSize=30;fillColor=#ffffff;strokeColor=#999999; +``` + +### Orthogonal Connector + +```text +edgeStyle=orthogonalEdgeStyle;rounded=0;html=1; +``` + +### Directed Arrow (bold) + +```text +edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;endArrow=block;endFill=1;strokeWidth=2; +``` + +### Dashed Dependency Line + +```text +edgeStyle=orthogonalEdgeStyle;dashed=1;endArrow=open;endFill=0;strokeColor=#666666; +``` + +### ER Relationship Line (one-to-many) + +```text +edgeStyle=entityRelationEdgeStyle;html=1;endArrow=ERmany;startArrow=ERmandOne;endFill=1;startFill=1; +``` + +### UML Inheritance Arrow (hollow triangle) + +```text +edgeStyle=orthogonalEdgeStyle;html=1;endArrow=block;endFill=0; +``` + +### UML Composition (filled diamond) + +```text +edgeStyle=orthogonalEdgeStyle;html=1;startArrow=diamond;startFill=1;endArrow=none; +``` + +### UML Aggregation (open diamond) + +```text +edgeStyle=orthogonalEdgeStyle;html=1;startArrow=diamond;startFill=0;endArrow=none; +``` + +### UML Dependency (dashed arrow) + +```text +edgeStyle=orthogonalEdgeStyle;dashed=1;html=1;endArrow=open;endFill=0; +``` + +### Invisible connector (for alignment) + +```text +edgeStyle=none;strokeColor=none;endArrow=none; +``` diff --git a/skills/draw-io-diagram-generator/scripts/.gitignore b/skills/draw-io-diagram-generator/scripts/.gitignore new file mode 100644 index 00000000..ba8af63e --- /dev/null +++ b/skills/draw-io-diagram-generator/scripts/.gitignore @@ -0,0 +1,5 @@ +__pycache__/ +*.pyc +*.pyo +*.pyd +.Python diff --git a/skills/draw-io-diagram-generator/scripts/README.md b/skills/draw-io-diagram-generator/scripts/README.md new file mode 100644 index 00000000..a2df542b --- /dev/null +++ b/skills/draw-io-diagram-generator/scripts/README.md @@ -0,0 +1,124 @@ +# draw-io Scripts + +Utility scripts for working with `.drawio` diagram files in the cxp-bu-order-ms project. + +## Requirements + +- Python 3.8+ +- No external dependencies (uses standard library only: `xml.etree.ElementTree`, `argparse`, `json`, `sys`, `pathlib`) + +## Scripts + +### `validate-drawio.py` + +Validates the XML structure of a `.drawio` file against required constraints. + +**Usage** + +```bash +python scripts/validate-drawio.py +``` + +**Examples** + +```bash +# Validate a single file +python scripts/validate-drawio.py docs/architecture.drawio + +# Validate all drawio files in a directory +for f in docs/**/*.drawio; do python scripts/validate-drawio.py "$f"; done +``` + +**Checks performed** + +| Check | Description | +|-------|-------------| +| Root cells | Verifies id="0" and id="1" cells are present in every diagram page | +| Unique IDs | All `mxCell` id values are unique within a diagram | +| Edge connectivity | Every edge has valid `source` and `target` attributes pointing to existing cells | +| Geometry | Every vertex cell has an `mxGeometry` child element | +| Parent chain | Every cell's `parent` attribute references an existing cell id | +| XML well-formedness | File is valid XML | + +**Exit codes** + +- `0` — Validation passed +- `1` — One or more validation errors found (errors printed to stdout) + +--- + +### `add-shape.py` + +Adds a new shape (vertex cell) to an existing `.drawio` diagram file. + +**Usage** + +```bash +python scripts/add-shape.py