# Drawio

> Apply when creating or reviewing architecture diagrams, Mermaid diagrams, or draw.io files.

- Skill: `sordi-ai/drawio` (Agent Skill)
- Install (CLI): `npx skillmds@latest add sordi-ai/drawio`
- Raw SKILL.md: https://api.skillmd.com/api/skills/sordi-ai/drawio/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- License: MIT
- Author: sordi-ai (https://skillmd.com/u/sordi-ai)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/sordi-ai/drawio

---


# Sub-Skill: Diagrams (draw.io / Mermaid)

**Purpose:** Ensure diagrams are version-controlled as source, rendered consistently, and kept in sync with the system they describe.

---

## Rules

### Source Control

1. **Commit source, not just exports.** Always commit diagram source files (`.drawio`, `.mmd`, `.puml`) alongside or instead of rendered image exports. Reference: ERR-2026-027
2. **No binary-only diagrams.** Never commit only a PNG or SVG export without the editable source; reviewers cannot diff or modify a raster image.
3. **One source file per diagram.** Use a single canonical source file per diagram; avoid duplicating the same diagram in multiple formats.

### Format Selection

4. **Prefer diagram-as-code.** Prefer Mermaid or PlantUML over draw.io XML when the diagram fits a supported diagram type; text diffs are reviewable.
5. **Match diagram type to content.** Use `sequenceDiagram` for request flows, `flowchart` for decision logic, `C4Context`/`C4Container` for architecture, `erDiagram` for data models.
6. **Set layout direction explicitly.** Always declare layout direction (`LR`, `TD`) in Mermaid flowcharts; never rely on the default, which varies by renderer.

### Rendering Pipeline

7. **Document the render command.** Always include the render command or CI step in the repo README or Makefile so any contributor can regenerate exports.
8. **Regenerate exports in CI.** Ensure CI regenerates diagram exports from source and fails if the committed export differs from the generated one.
9. **Pin renderer version.** Always pin the Mermaid CLI or draw.io CLI version in CI to prevent silent rendering changes across upgrades.

### Quality & Consistency

10. **Use consistent node naming.** Always use the same label for the same system component across all diagrams in the repo; divergent names cause confusion.
11. **Add alt text to exported images.** Always add descriptive alt text to diagram images embedded in documentation for accessibility.
12. **Review diagrams in PRs.** Before merging, verify that any diagram change accurately reflects the system change described in the PR.

---

## See also

- `skills/svg-check/SKILL.md`
- `skills/error-log/SKILL.md`