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

> Troubleshoot common diagram design issues. Use verification scripts to pinpoint failures in command parsing, reference loading, or rendering, and fix source files or templates for smoother development.

- Repository: [Cathryn Lavery/diagram-design](https://github.com/cathrynlavery/diagram-design)
- Tags: how-to-guide
- Published: 2026-08-20

---

**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)](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)](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`](https://github.com/cathrynlavery/diagram-design/tree/main/skills/diagram-design/references), [[`references/style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/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/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/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/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/type-flowchart.md)).

**Diagnostic steps:**

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

```bash
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:

```bash
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:

```bash
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:

```bash
pip install playwright
playwright install chromium

```

**Fix:** Re‑run the export command and verify the Playwright version matches any [`requirements.txt`](https://github.com/cathrynlavery/diagram-design/blob/main/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:

```bash
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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/style-guide.md) for missing tokens.

**Fix:** Rerun the onboarding flow or manually edit [`style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/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:**

```bash
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:**

```bash
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`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/verify-drawio-import.py) | Validates draw.io import pipeline |
| [`scripts/verify-mermaid-import.py`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/verify-mermaid-import.py) | Validates Mermaid import pipeline |
| [`scripts/lint-skin.py`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/lint-skin.py) | Checks accessibility and motion‑safety compliance |
| [`scripts/self_check.py`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/self_check.py) | Verifies generated HTML integrity |
| [`scripts/verify-treemap.py`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/verify-treemap.py) | Ensures treemap data satisfies area constraints |
| [`scripts/verify-docs-sync.py`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/verify-docs-sync.py) | Catches broken links in documentation |
| [`scripts/export.py`](https://github.com/cathrynlavery/diagram-design/blob/main/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)](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)](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)](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)](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)](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)](https://github.com/cathrynlavery/diagram-design/blob/main/commands/export-diagram.md) | Slash‑command specification for export operations |

## Code Examples for Common Fixes

```bash

# 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`](https://github.com/cathrynlavery/diagram-design/blob/main/verify-drawio-import.py) for draw.io failures, [`verify-mermaid-import.py`](https://github.com/cathrynlavery/diagram-design/blob/main/verify-mermaid-import.py) for Mermaid issues, [`lint-skin.py`](https://github.com/cathrynlavery/diagram-design/blob/main/lint-skin.py) for accessibility warnings, and [`self_check.py`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/style-guide.md) with compliant hex codes, then rerun onboarding.