How to Troubleshoot Common Issues in Diagram Design: A Developer’s Guide

Run the appropriate verification script in scripts/ to isolate failures to specific layers—command parsing, reference loading, or runtime rendering—then apply targeted fixes to the source files or templates.

Diagram Design is a modular skill that generates editorial‑quality diagrams using a lightweight, self‑contained HTML + SVG pipeline. Located in the cathrynlavery/diagram-design repository, it employs progressive disclosure to load only the components needed for each request. This architecture makes troubleshooting straightforward once you understand which layer is failing and which verification scripts to run.

Architecture Overview

The skill is organized under skills/diagram-design/ into three distinct layers:

Layer	Purpose	Primary Files
Command layer	Parses slash commands like /diagram-design:import-drawio and /export-diagram	[commands/import-drawio.md](https://github.com/cathrynlavery/diagram-design/blob/main/commands/import-drawio.md), [commands/export-diagram.md](https://github.com/cathrynlavery/diagram-design/blob/main/commands/export-diagram.md)
Reference layer	Lazy‑loads type definitions, semantic patterns, and animation specifications	references/type-*.md, [references/style-guide.md](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/style-guide.md), [references/animation.md](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/animation.md)
Runtime layer	Builds final HTML, injects fonts, and rasterizes to PNG via Playwright	[scripts/drawio_extract.py](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/scripts/drawio_extract.py), [scripts/self_check.py](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/scripts/self_check.py)

When processing a request, the agent loads only SKILL.md plus the specific references required. Failures typically surface during verification, not at runtime, because malformed inputs are caught by dedicated lint and validation scripts.

Common Failure Points and Fixes

Diagram Does Not Render or Appears Blank

Likely cause: Missing or corrupted reference file (e.g., type-flowchart.md).

Diagnostic steps:

1. Run the self‑check on the generated HTML:

python3 skills/diagram-design/scripts/self_check.py path/to/diagram.html

2. Look for "missing type reference" errors in the output.

Fix: Re‑install the skill or copy the missing reference file from the repository.

---

Exported SVG Missing Fonts

Likely cause: Font‑injection step failed due to Google Fonts being unreachable.

Diagnostic steps:

Run the export with SVG‑only mode and inspect the <style> block:

python3 scripts/export.py --svg-only path/to/diagram.html

Check for @font-face rules in the output.

Fix: Ensure network access to fonts.googleapis.com or use the offline fallback:

pip install fonttools
python -m fonttools.ttx ...

---

PNG Export Garbled or Empty

Likely cause: Playwright not installed or Chromium missing.

Diagnostic steps:

Verify Playwright installation:

pip install playwright
playwright install chromium

Fix: Re‑run the export command and verify the Playwright version matches any requirements.txt in the repository.

---

Import-drawio or Import-mermaid Fails

Likely cause: Parser scripts raised exceptions due to malformed XML or unsupported Mermaid grammar.

Diagnostic steps:

Run the parser directly on the source file:

python3 skills/diagram-design/scripts/drawio_extract.py sample.drawio
python3 skills/diagram-design/scripts/mermaid_extract.py sample.mmd

Fix: Correct the source file (close tags, remove unsupported directives) or upgrade the parser by pulling the latest scripts/ files from the repository.

---

Brand Onboarding Does Not Apply

Likely cause: style-guide.md unchanged or tokens not written due to contrast failure.

Diagnostic steps:

Inspect ~/.diagram-design/profiles/*.md and skills/diagram-design/references/style-guide.md for missing tokens.

Fix: Rerun the onboarding flow or manually edit style-guide.md, ensuring WCAG AA contrast—the skill will suggest adjusted values if contrast is insufficient.

---

Accessibility Warnings

Likely cause: SVG elements lack role="img" or missing <title>/<desc>.

Diagnostic steps:

python3 scripts/lint-skin.py --all

Fix: Add required attributes in the template (template-*.html) or fix the offending example file.

---

Treemap Verification Reports Mismatched Area

Likely cause: Cell area does not correspond to label value; violates fixed‑size ladder constraints.

Diagnostic steps:

python3 scripts/verify-treemap.py --all

Fix: Adjust the input data or edit the generated treemap to respect the constraints: ≤ 24 nodes, balanced ≤ 12, simplified ≤ 7.

Debugging Workflow

Follow this sequence to systematically troubleshoot issues in Diagram Design:

1. Reproduce the failure — Use the exact command (e.g., /diagram-design:import-drawio myfile.drawio).
2. Run the appropriate verification script — All scripts reside in scripts/ at the repository root.
3. Read error output — Scripts emit line‑numbered diagnostics pointing to offending references or templates.
4. Apply the fix — Edit the source file, then re‑run the original command.
5. Validate — Execute the self‑check or lint script again to confirm resolution.

Essential Verification Scripts

Script	Purpose
scripts/verify-drawio-import.py	Validates draw.io import pipeline
scripts/verify-mermaid-import.py	Validates Mermaid import pipeline
scripts/lint-skin.py	Checks accessibility and motion‑safety compliance
scripts/self_check.py	Verifies generated HTML integrity
scripts/verify-treemap.py	Ensures treemap data satisfies area constraints
scripts/verify-docs-sync.py	Catches broken links in documentation
scripts/export.py	PNG/SVG export utilities (requires Playwright)

Key Files for Troubleshooting

Path	Role
[skills/diagram-design/SKILL.md](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/SKILL.md)	Core skill description and type selection logic
[skills/diagram-design/references/style-guide.md](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/style-guide.md)	Central source of colors, fonts, and design tokens
[skills/diagram-design/references/semantic-patterns.md](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/semantic-patterns.md)	Behaviour‑centric patterns driving optional motion
[skills/diagram-design/references/animation.md](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/animation.md)	Motion modes (none, reveal, step, loop) and accessibility contract
[commands/import-drawio.md](https://github.com/cathrynlavery/diagram-design/blob/main/commands/import-drawio.md)	Slash‑command specification for draw.io imports
[commands/export-diagram.md](https://github.com/cathrynlavery/diagram-design/blob/main/commands/export-diagram.md)	Slash‑command specification for export operations

Code Examples for Common Fixes

# Verify a draw.io import and see detailed diagnostics

python3 skills/diagram-design/scripts/drawio_extract.py path/to/file.drawio

# Run self-check on generated diagram HTML

python3 skills/diagram-design/scripts/self_check.py output/diagram.html

# Lint all examples for accessibility and motion compliance

python3 scripts/lint-skin.py --all

# Export diagram to PNG at 3x scale (requires Playwright)

python3 scripts/export.py --png-only output/diagram.html --scale=3

# Verify documentation links are intact after adding new type

python3 scripts/verify-docs-sync.py

Summary

• Layered architecture—command, reference, runtime—isolates failures to specific components.
• Progressive disclosure means most bugs surface in verification scripts, not at runtime.
• Always run the relevant verification script first to get line‑numbered diagnostics.
• Keep the verification suite green (python3 scripts/... --all) to guarantee reliable operation across Claude Code, Codex, Factory Droid, and Pi environments.
• Key fix patterns: reinstall missing references, ensure network/font access, validate source file syntax, maintain WCAG AA contrast, and respect treemap size constraints.

Frequently Asked Questions

How do I know which verification script to run?

Match your symptom to the script name: use verify-drawio-import.py for draw.io failures, verify-mermaid-import.py for Mermaid issues, lint-skin.py for accessibility warnings, and self_check.py for blank or malformed renders. All scripts accept --help for full option listings.

Why does my diagram fail only in PNG export but work in SVG?

The runtime layer uses Playwright for PNG rasterization. If SVG renders correctly but PNG is garbled, Playwright or its Chromium browser is likely missing or misconfigured. Run playwright install chromium and verify network access for font fetching.

What causes "missing type reference" errors?

The reference layer lazy‑loads only the type-*.md files specified by SKILL.md for each diagram category. If a reference file is deleted, renamed, or corrupted, the self‑check will flag it. Copy the missing file from the repository or reinstall the skill.

How do I fix contrast warnings during brand onboarding?

The style guide validator enforces WCAG AA contrast ratios. If your brand colors fail, the skill suggests adjusted values. Accept the suggestions or manually edit skills/diagram-design/references/style-guide.md with compliant hex codes, then rerun onboarding.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}