# How to Integrate Diagram Design with CI/CD Pipelines: A Complete Automation Guide

> Automate diagram design with CI/CD pipelines. Install the skill, generate diagrams as build artifacts, and export production-ready visuals for seamless integration.

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

---

**Install the Diagram Design skill in your CI environment, generate source diagrams as build artifacts, and export production-ready visuals using built-in verification gates.**

The **Diagram Design** skill—distributed via the `cathrynlavery/diagram-design` repository—transforms raw diagram sources into editorial-grade HTML, SVG, and PNG assets. Because it lives in a standard Git repository, you can pull it into any CI/CD pipeline just like any other dependency. This guide walks through the exact integration steps using the project's own CI implementation as the reference architecture.

## CI/CD Integration Architecture

The Diagram Design skill follows a five-phase pipeline pattern that mirrors software build workflows:

- **Install** the skill into the CI environment
- **Generate** diagram sources from `.drawio`, `.mmd`, or JSON files
- **Redraw** using the skill's extraction scripts to produce structured HTML
- **Export** final artifacts via `/export-diagram` with format-specific flags
- **Verify** using the repository's gate scripts to enforce contracts and accessibility

Each phase maps to specific files in the `cathrynlavery/diagram-design` source tree.

## Phase 1: Installing Diagram Design in CI

The skill installs into any supported agent (Claude Code, Codex, or **Pi**). In CI, you have two options:

**Option A: Direct install via Pi CLI**

```bash
pi install https://github.com/cathrynlavery/diagram-design

```

**Option B: Symlink the skill directory**

```bash
git clone https://github.com/cathrynlavery/diagram-design.git /tmp/diagram-design
pi install /tmp/diagram-design

```

The repository's [`README.md`](https://github.com/cathrynlavery/diagram-design/blob/main/README.md) documents both approaches. For containerized CI environments, Option B ensures reproducible builds by pinning to a specific commit.

## Phase 2: Generating Source Diagrams

Diagram Design consumes three source formats. Commit these alongside your codebase:

| Format | File Extension | Import Command |
|--------|---------------|----------------|
| draw.io | `.drawio` | `/import-drawio` |
| Mermaid | `.mmd` | `/import-mermaid` |
| Raw JSON | `.json` | Direct template binding |

The import commands are documented in [`commands/import-drawio.md`](https://github.com/cathrynlavery/diagram-design/blob/main/commands/import-drawio.md) and [`commands/import-mermaid.md`](https://github.com/cathrynlavery/diagram-design/blob/main/commands/import-mermaid.md). Both support flags for detail level and sizing:

- `--detail=simplified|balanced|comprehensive`
- `--size=slide-16x9|doc-wide|social-square`

## Phase 3: Redrawing with Extraction Scripts

Behind the import commands, the skill runs Python extraction scripts to parse source files into an internal representation, then binds them to HTML templates.

Key implementation files:

- [`skills/diagram-design/scripts/drawio_extract.py`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/scripts/drawio_extract.py) — Parses draw.io XML into structured data
- [`skills/diagram-design/scripts/mermaid_extract.py`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/scripts/mermaid_extract.py) — Translates Mermaid AST to the skill's IR

These scripts produce `template*.html` files that serve as the editorial-grade intermediate format.

## Phase 4: Exporting Production Artifacts

The `/export-diagram` command (documented in [`commands/export-diagram.md`](https://github.com/cathrynlavery/diagram-design/blob/main/commands/export-diagram.md)) renders final assets:

```bash

# SVG export (headless, fast)

pi -c "export-diagram assets/diagram.html --svg-only"

# PNG export (requires Playwright/Chromium)

pi -c "export-diagram assets/diagram.html --png-only --scale=3"

```

**Critical CI requirement:** PNG export depends on Playwright. Install it before running exports:

```bash
pip install playwright
playwright install chromium

```

The `--scale` parameter controls resolution—use `2` for standard displays, `3` for high-DPI or print.

## Phase 5: Running Verification Gates

The repository ships purpose-built verification scripts that enforce diagram quality contracts. Run these in CI to prevent regressions:

| Script | Purpose | Source File |
|--------|---------|-------------|
| [`verify-drawio-import.py`](https://github.com/cathrynlavery/diagram-design/blob/main/verify-drawio-import.py) | Validates draw.io import correctness and schema compliance | [`scripts/verify-drawio-import.py`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/verify-drawio-import.py) |
| [`verify-mermaid-import.py`](https://github.com/cathrynlavery/diagram-design/blob/main/verify-mermaid-import.py) | Validates Mermaid import and AST transformation | [`scripts/verify-mermaid-import.py`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/verify-mermaid-import.py) |
| [`verify-docs-sync.py`](https://github.com/cathrynlavery/diagram-design/blob/main/verify-docs-sync.py) | Ensures documentation, examples, and skill references remain synchronized | [`scripts/verify-docs-sync.py`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/verify-docs-sync.py) |

These scripts exit non-zero on failure, making them ideal CI gates.

## Complete GitHub Actions Example

The repository's own [`.github/workflows/ci.yml`](https://github.com/cathrynlavery/diagram-design/blob/main/.github/workflows/ci.yml) demonstrates production-grade integration. Adapt this pattern for your pipeline:

```yaml
name: Diagram CI

on: [push, pull_request]

jobs:
  build-diagrams:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Setup Python
        uses: actions/setup-python@v4
        with:
          python-version: '3.11'
      
      - name: Install Diagram Design
        run: |
          pip install pi-cli
          pi install https://github.com/cathrynlavery/diagram-design
      
      - name: Install Playwright
        run: |
          pip install playwright
          playwright install chromium
      
      - name: Import Mermaid source
        run: |
          pi -c "import-mermaid docs/architecture.mmd --detail=balanced --size=doc-wide"
      
      - name: Export artifacts
        run: |
          pi -c "export-diagram assets/architecture.html --svg-only"
          pi -c "export-diagram assets/architecture.html --png-only --scale=2"
      
      - name: Run verification gates
        run: |
          python scripts/verify-mermaid-import.py
          python scripts/verify-docs-sync.py

```

## Verification Script Integration

For existing pipelines, add verification as a final stage:

```bash
#!/usr/bin/env bash
set -euo pipefail

echo "Running Diagram Design verification suite..."

python scripts/verify-drawio-import.py
python scripts/verify-mermaid-import.py
python scripts/verify-docs-sync.py

echo "All diagram verification gates passed"

```

The `-e` flag ensures the build fails on any script exit code, matching the behavior in `cathrynlavery/diagram-design`'s own CI.

## Additional CI Automation: Icon Regeneration

When your diagram icon set changes, regenerate assets in CI using:

```bash
python scripts/build-icons.py

```

This script ([`scripts/build-icons.py`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/build-icons.py)) rebuilds the icon collection used by diagram templates. Run it when `icons/` directory contents change to ensure visual consistency.

## Summary

Integrating **Diagram Design with CI/CD pipelines** requires five coordinated steps:

- Install the skill via Pi CLI or filesystem symlink
- Commit `.drawio`, `.mmd`, or JSON diagram sources to version control
- Run import commands to generate HTML intermediates using [`drawio_extract.py`](https://github.com/cathrynlavery/diagram-design/blob/main/drawio_extract.py) or [`mermaid_extract.py`](https://github.com/cathrynlavery/diagram-design/blob/main/mermaid_extract.py)
- Export production artifacts with `/export-diagram`, installing Playwright for PNG output
- Gate every build with [`verify-drawio-import.py`](https://github.com/cathrynlavery/diagram-design/blob/main/verify-drawio-import.py), [`verify-mermaid-import.py`](https://github.com/cathrynlavery/diagram-design/blob/main/verify-mermaid-import.py), and [`verify-docs-sync.py`](https://github.com/cathrynlavery/diagram-design/blob/main/verify-docs-sync.py)

The `cathrynlavery/diagram-design` repository's [`.github/workflows/ci.yml`](https://github.com/cathrynlavery/diagram-design/blob/main/.github/workflows/ci.yml) provides a working reference implementation that validates the entire pipeline on every push.

## Frequently Asked Questions

### What agents support the Diagram Design skill?

Claude Code, Codex, and Pi all support the skill installation model. The examples in this guide use **Pi** syntax (`pi install`, `pi -c`), but equivalent commands exist for other agents. The skill structure in `skills/diagram-design/` follows a standard layout that any plugin-capable agent can load.

### Why does PNG export require Playwright?

PNG generation renders HTML templates through a headless browser to capture exact styling, fonts, and responsive layout. The `/export-diagram` command with `--png-only` invokes Playwright/Chromium to perform this rendering. SVG export does not require Playwright and completes faster, making it preferable for validation stages.

### How do I pin to a specific Diagram Design version?

Clone the repository to a specific commit or tag instead of using `pi install` with a remote URL:

```bash
git clone --depth 1 --branch v1.2.3 \
  https://github.com/cathrynlavery/diagram-design.git /tmp/dd-fixed
pi install /tmp/dd-fixed

```

This guarantees reproducible builds and prevents upstream changes from breaking your pipeline.

### What happens if verification scripts fail?

Each verification script ([`verify-drawio-import.py`](https://github.com/cathrynlavery/diagram-design/blob/main/verify-drawio-import.py), [`verify-mermaid-import.py`](https://github.com/cathrynlavery/diagram-design/blob/main/verify-mermaid-import.py), [`verify-docs-sync.py`](https://github.com/cathrynlavery/diagram-design/blob/main/verify-docs-sync.py)) exits with code 1 and prints diagnostic output when checks fail. Typical failures include: malformed source files, broken internal links, accessibility regressions (missing alt text), or documentation drift. Fix the reported issue and re-run the pipeline.