Available Process Diagram Types in Diagram-Design: Process vs Swimlane

Diagram-Design supports two distinct process diagram types—Process diagrams for detailed sequential workflows with data payloads and responsibility tracking, and Swimlane diagrams for simplified cross-functional flows emphasizing activity ordering over technical specifications.

The open-source diagram-design repository by cathrynlavery provides structured YAML-based diagramming standards for technical documentation. Understanding the available process diagram types enables teams to select the appropriate visualization for everything from responsibility audits to vendor hand-offs.

Process Diagram Type (Detailed Workflow Visualization)

Process diagrams are the comprehensive option for modeling sequential business processes across multiple actors.

When to Use Process Diagrams

Use this type when each step’s input, output, responsible team, and tools must be visible at a glance. According to skills/diagram-design/references/type-process.md, this diagram family is ideal for:

• Responsibility audits and data-quality gate reviews
• Cross-divisional hand-offs requiring payload visibility
• End-to-end workflow documentation with tool chain tracking

YAML Structure and Focal Mechanics

Process diagrams support focal steps that highlight critical path elements and chips that display data payloads flowing between stages.

lanes:
  - { name: ["PRODUCT"],    key: "PRD" }
  - { name: ["ENGINEERING"], key: "ENG" }
  - { name: ["QA"],         key: "QA" }

steps:
  - { number: "1", label: "Idea" }
  - { number: "2", label: "Build", focal: true }
  - { number: "3", label: "Validate" }
  - { number: "4", label: "Release" }

nodes:
  - { lane: "PRD", step: 0, title: "Concept", sub: "market study", tool: "Docs", chips: {in: null, out: "LS"} }
  - { lane: "ENG", step: 1, title: "Implementation", sub: "code + tests", tool: "IDE", chips: {in: "LS", out: "TB"}, color: "#5a7d9a" }
  - { lane: "QA",  step: 2, title: "Testing", sub: "regression suite", tool: "CI", chips: {in: "TB", out: "TB"}, focal: true }
  - { lane: "PRD", step: 3, title: "Ship", sub: "release notes", tool: "GitHub", chips: {in: "TB", out: "FL"} }

arrows:
  - { from: {lane: "PRD", step: 0}, to: {lane: "ENG", step: 1}, style: "normal" }
  - { from: {lane: "ENG", step: 1}, to: {lane: "QA",  step: 2}, style: "focal-in" }
  - { from: {lane: "QA",  step: 2}, to: {lane: "PRD", step: 3}, style: "focal-out" }

dark: false

The chips object defines data contracts with in and out keys, while focal: true marks steps requiring visual emphasis. Connector styles like focal-in and focal-out create visual hierarchy around critical transitions.

Swimlane Diagram Type (Simplified Cross-Functional Flows)

Swimlane diagrams provide a lighter alternative for RACI-style flows and multi-team coordination.

When to Use Swimlane Diagrams

As defined in skills/diagram-design/references/type-swimlane.md, use this type for simpler cross-functional flows where data payloads and tool details are not required. This includes:

• Vendor hand-off sequences
• Multi-team shipping workflows
• RACI matrix visualizations

YAML Contract Structure

Swimlane diagrams omit the chips property and focal styling mechanics present in Process diagrams. The contract emphasizes lane arrangement and step ordering:

lanes:
  - { name: ["PRODUCT"],    key: "PRD" }
  - { name: ["ENGINEERING"], key: "ENG" }
  - { name: ["QA"],         key: "QA" }

steps:
  - { number: "1", label: "Ideation" }
  - { number: "2", label: "Development" }
  - { number: "3", label: "Testing" }
  - { number: "4", label: "Release" }

nodes:
  - { lane: "PRD", step: 0, title: "Define scope", sub: "", tool: "Docs" }
  - { lane: "ENG", step: 1, title: "Code", sub: "", tool: "IDE" }
  - { lane: "QA",  step: 2, title: "Test", sub: "", tool: "CI" }
  - { lane: "PRD", step: 3, title: "Launch", sub: "", tool: "Release Tool" }

arrows:
  - { from: {lane: "PRD", step: 0}, to: {lane: "ENG", step: 1}, style: "normal" }
  - { from: {lane: "ENG", step: 1}, to: {lane: "QA",  step: 2}, style: "normal" }
  - { from: {lane: "QA",  step: 2}, to: {lane: "PRD", step: 3}, style: "normal" }

dark: false

This produces horizontal lane bands with simple rectangular steps and standard connector styling.

Shared Rendering Infrastructure

Both process diagram types inherit core rendering rules defined centrally in skills/diagram-design/references/type-process.md. The shared infrastructure includes:

• Connector styles: Standardized arrow rendering and path routing
• Colour-override system: Node-level color properties and theme tokens
• Dark-mode tokens: The dark: boolean flag available in both YAML contracts
• Reproducibility checklist: Validation rules ensuring diagram consistency

Swimlane diagrams reference these specifications while omitting the focal mechanics and data-payload visualizations that characterize full Process diagrams.

Summary

• Diagram-Design provides two process diagram types: Process (detailed) and Swimlane (simplified).
• Process diagrams support chips for data payloads, focal steps for emphasis, and specialized connector styles.
• Swimlane diagrams offer clean cross-functional layouts without data-detail overhead, ideal for RACI workflows.
• Both types share rendering infrastructure including dark-mode support and colour overrides defined in skills/diagram-design/references/type-process.md.
• Schema definitions reside in skills/diagram-design/references/type-process.md and skills/diagram-design/references/type-swimlane.md.

Frequently Asked Questions

What is the difference between Process and Swimlane diagrams in Diagram-Design?

Process diagrams display detailed technical metadata including data inputs/outputs via chips and support focal highlighting for critical steps. Swimlane diagrams strip away these details to show only activity ordering across functional lanes, making them ideal for high-level cross-functional reviews where data payloads are irrelevant.

How do I specify data inputs and outputs in a process diagram?

Add a chips object to any node in your YAML contract with in and out keys representing data identifiers. For example: chips: {in: "LS", out: "TB"}. These appear as visual badges on the diagram step, showing data flow between process stages as defined in skills/diagram-design/references/type-process.md.

Can I use dark mode with both diagram types?

Yes. Both Process and Swimlane diagrams support the dark: boolean property in their YAML contracts. When set to true, the diagram renders using the dark-mode token palette defined in the shared rendering system, ensuring consistent visual presentation across both diagram families.

Where are the schema specifications for process diagrams defined?

The authoritative specifications reside in skills/diagram-design/references/type-process.md (comprehensive Process diagram schema including focal mechanics and chip definitions) and skills/diagram-design/references/type-swimlane.md (simplified Swimlane layout rules). Both files are located in the diagram-design repository under the skills/diagram-design/references/ path.

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