# How to Create an IT Current-State Diagram Using diagram-design

> Quickly create an IT current-state diagram using diagram-design. Generate your diagram from YAML, render it, and use an HTML template. Learn how now.

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

---

**Use the built-in `it-state` type in diagram-design to generate an IT current-state diagram by writing a YAML description, running the render command, and wrapping the output in a pre-built HTML template.**

The diagram-design repository provides a **dedicated type for IT current-state diagrams** that maps your infrastructure into three visual zones: Collection, Processing, and Dissemination. This type is fully self-contained—no external design tools or services are required.

## Understanding the IT Current-State Type

The `it-state` type is defined in [`skills/diagram-design/references/type-it-state.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/type-it-state.md). This reference file specifies the required YAML schema, the three-zone layout, and optional styling parameters including light/dark skins, extended footer bars, and color overrides.

When executed, the skill validates your YAML input (geometry verification is handled by [`scripts/verify-geometry.py`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/verify-geometry.py)), renders an SVG, and injects it into one of several HTML templates located in `skills/diagram-design/assets/`. These templates include accessibility metadata (`<title>` and `<desc>` elements) for SEO and assistive technology compatibility.

## Prerequisites

Before creating your diagram, ensure you have:

- Node.js and the diagram-design CLI installed from the repository
- A working directory with write access for output files

## Step 1: Write the YAML Input

Create a YAML file that describes your IT landscape using the `it-state` schema. The file must declare `type: it-state` and include zones, components, and connectors.

```yaml

# it-state.yml – IT current-state diagram for Northwind Retail

type: it-state
title: Northwind Retail Current IT Landscape
zones:
  - name: Collection
    components:
      - name: POS Terminals
      - name: Web Front-end
  - name: Processing
    components:
      - name: Order Service
      - name: Inventory DB
  - name: Dissemination
    components:
      - name: Reporting Engine
connectors:
  - from: POS Terminals
    to: Order Service
  - from: Web Front-end
    to: Order Service
  - from: Order Service
    to: Reporting Engine
footerBars: []

```

The `zones` array defines the left-to-right flow of data through your system. The `connectors` array draws directional arrows between components. Leave `footerBars` empty for the default layout, or populate it with summary metrics for extended templates.

## Step 2: Render the SVG

Run the diagram-design render command to generate the raw SVG:

```bash
diagram-design render -i it-state.yml -t it-state -o out/it-state.svg

```

The `-t it-state` flag selects the IT current-state type. The tool validates your YAML against the schema in [`type-it-state.md`](https://github.com/cathrynlavery/diagram-design/blob/main/type-it-state.md), runs [`scripts/verify-geometry.py`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/verify-geometry.py) to check zone positioning, and outputs a standalone SVG file.

## Step 3: Wrap in an HTML Template

Choose a visual skin and wrap the SVG for presentation:

```bash

# Light theme (default)

diagram-design wrap -i out/it-state.svg -t it-state -s light -o out/it-state.html

# Dark theme

diagram-design wrap -i out/it-state.svg -t it-state -s dark -o out/it-state-dark.html

# Full-card editorial layout

diagram-design wrap -i out/it-state.svg -t it-state -s full -o out/it-state-full.html

```

Available templates in `skills/diagram-design/assets/`:

- [`template.html`](https://github.com/cathrynlavery/diagram-design/blob/main/template.html) – Light theme with clean typography
- [`template-dark.html`](https://github.com/cathrynlavery/diagram-design/blob/main/template-dark.html) – Dark theme for presentations
- [`template-full.html`](https://github.com/cathrynlavery/diagram-design/blob/main/template-full.html) – Full-card layout with extended metadata
- [`example-it-state.html`](https://github.com/cathrynlavery/diagram-design/blob/main/example-it-state.html) – Pre-rendered light example
- [`example-it-state-dark.html`](https://github.com/cathrynlavery/diagram-design/blob/main/example-it-state-dark.html) – Pre-rendered dark example
- [`example-it-state-full.html`](https://github.com/cathrynlavery/diagram-design/blob/main/example-it-state-full.html) – Pre-rendered full-card example

## Step 4: Export for Publishing

Generate a static PNG for documentation or presentations:

```bash
diagram-design export -i out/it-state.html -f png -o docs/screenshots/it-state.png

```

The export command is documented in [`commands/export-diagram.md`](https://github.com/cathrynlavery/diagram-design/blob/main/commands/export-diagram.md). It rasterizes the HTML using the bundled runtime and copies the result to your specified output path.

## Customizing Your IT Current-State Diagram

### Adding Footer Bars for Metrics

Populate `footerBars` with key-value pairs to display summary statistics below the diagram:

```yaml
footerBars:
  - label: Total Systems
    value: 12
  - label: Critical Path Latency
    value: 240ms

```

### Switching Color Schemes

Pass the `-s` flag to `wrap` with `light`, `dark`, or `full`. The templates apply CSS custom properties defined in the assets directory.

### Validating Geometry

The [`scripts/verify-geometry.py`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/verify-geometry.py) script runs automatically during render. To run manually:

```bash
python scripts/verify-geometry.py -i it-state.yml

```

This ensures zone boundaries do not overlap and connector paths remain within valid coordinates.

## Key Source Files Reference

| File | Purpose | GitHub Link |
|------|---------|-------------|
| [`skills/diagram-design/references/type-it-state.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/type-it-state.md) | Type specification and YAML schema | [View](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/type-it-state.md) |
| [`skills/diagram-design/assets/template.html`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/assets/template.html) | Light theme HTML wrapper | [View](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/assets/template.html) |
| [`skills/diagram-design/assets/template-dark.html`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/assets/template-dark.html) | Dark theme HTML wrapper | [View](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/assets/template-dark.html) |
| [`skills/diagram-design/assets/template-full.html`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/assets/template-full.html) | Full-card editorial wrapper | [View](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/assets/template-full.html) |
| [`skills/diagram-design/assets/example-it-state.html`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/assets/example-it-state.html) | Example rendered output (light) | [View](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/assets/example-it-state.html) |
| [`commands/export-diagram.md`](https://github.com/cathrynlavery/diagram-design/blob/main/commands/export-diagram.md) | Export command documentation | [View](https://github.com/cathrynlavery/diagram-design/blob/main/commands/export-diagram.md) |
| [`scripts/verify-geometry.py`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/verify-geometry.py) | Geometry validation script | [View](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/verify-geometry.py) |

## Summary

- **IT current-state diagrams** in diagram-design use the `it-state` type defined in [`type-it-state.md`](https://github.com/cathrynlavery/diagram-design/blob/main/type-it-state.md)
- **Three zones** (Collection, Processing, Dissemination) structure your infrastructure visualization
- **YAML input** drives the entire workflow—no manual drawing required
- **Three CLI commands** (`render`, `wrap`, `export`) produce publication-ready output
- **Multiple templates** (light, dark, full) adapt the diagram to different contexts
- **Built-in validation** ensures geometric correctness before rendering

## Frequently Asked Questions

### What data format does diagram-design require for IT current-state diagrams?

Diagram-design accepts **YAML files** with a specific schema defined in [`skills/diagram-design/references/type-it-state.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/type-it-state.md). The file must include `type: it-state`, a `title`, a `zones` array with three zone definitions, a `components` list per zone, and a `connectors` array for relationships.

### Can I customize the colors and styling of my IT current-state diagram?

Yes. The `wrap` command accepts a `-s` flag with values `light`, `dark`, or `full` to select from pre-built themes in `skills/diagram-design/assets/`. For deeper customization, modify the CSS custom properties in [`template.html`](https://github.com/cathrynlavery/diagram-design/blob/main/template.html) or create a custom template following the same structure.

### Does diagram-design work offline without external services?

Yes. The entire workflow—from YAML validation through SVG rendering to PNG export—runs locally using the bundled Node.js runtime and Python scripts. No internet connection or external API calls are required after initial installation.