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

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. 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), 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.

# 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:

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, runs 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:

# 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 – Light theme with clean typography
• template-dark.html – Dark theme for presentations
• template-full.html – Full-card layout with extended metadata
• example-it-state.html – Pre-rendered light example
• example-it-state-dark.html – Pre-rendered dark example
• example-it-state-full.html – Pre-rendered full-card example

Step 4: Export for Publishing

Generate a static PNG for documentation or presentations:

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. 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:

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 script runs automatically during render. To run manually:

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	Type specification and YAML schema	View
skills/diagram-design/assets/template.html	Light theme HTML wrapper	View
skills/diagram-design/assets/template-dark.html	Dark theme HTML wrapper	View
skills/diagram-design/assets/template-full.html	Full-card editorial wrapper	View
skills/diagram-design/assets/example-it-state.html	Example rendered output (light)	View
commands/export-diagram.md	Export command documentation	View
scripts/verify-geometry.py	Geometry validation script	View

Summary

• IT current-state diagrams in diagram-design use the it-state type defined in 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. 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 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.

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