How Backend, API, and Step Nodes Are Styled in Diagram Design: A Complete Guide

Backend, API, and step nodes in Diagram Design are styled through a semantic token system defined in style-guide.md and type-process.md, with each node type mapping to specific fill and stroke color tokens rather than hard-coded values.

This system ensures visual consistency across all diagram types in the cathrynlavery/diagram-design repository. Rather than scattering hex codes throughout the codebase, every styling decision flows from a centralized token table that enforces brand alignment and accessibility compliance.

How the Semantic Token System Works

The Diagram Design framework treats color as semantic meaning. Each node category receives a named token that translates to concrete colors at render time.

• backend token → white fill (#ffffff) with ink stroke
• external token → light tint of ink fill (ink @ 0.03) with muted ink stroke (ink @ 0.30)
• step headers → default gray or accent-tinted fill depending on focal state

This abstraction layer means designers can adjust the entire palette by modifying token values in style-guide.md without touching individual diagram definitions.

Backend Node Styling

Backend nodes represent internal services, databases, and infrastructure components. According to the canonical token table in [style-guide.md](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/style-guide.md#L13-L16), these nodes use:

Property	Value	Token
Fill	#ffffff (white)	backend
Stroke	ink (primary text color)	backend

The white fill intentionally signals internal, trusted systems against the diagram's paper background. The ink stroke ensures sufficient contrast for WCAG AA compliance.

# Backend node declaration

nodes:
  - lane: "BCK"
    step: 0
    title: "DB-Import"
    sub: "raw → table"
    chips: { in: null, out: "CSV" }
    color: "#ffffff"  # Resolved from backend token

API and External Node Styling

External integration points—APIs, third-party services, and outbound connectors—use the external token. Per [style-guide.md](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/style-guide.md#L15-L17):

Property	Value	Token
Fill	ink @ 0.03	external
Stroke	ink @ 0.30	external

The subtle tinting visually distinguishes external dependencies from internal backend systems without introducing competing accent colors. This follows the repository's one-accent rule: only a single focal accent may appear per diagram.

# API/external node declaration

nodes:
  - lane: "API"
    step: 1
    title: "REST-Call"
    sub: "GET /data"
    chips: { in: "JSON", out: null }
    color: "#e0e0e0"  # Approximation of ink @ 0.03

Step Header Chip Styling

Step headers appear as pill-shaped chips above each column in process diagrams. Their styling bifurcates based on focal state, defined in [type-process.md](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/type-process.md#L12-L33):

State	Fill	Number Text
Default	rgba(45,49,66,0.12) (light gray)	ink
Focal step	rgba(235,108,54,0.20) (accent-tint)	accent

The focal step override draws visual attention to the diagram's primary action or decision point. The 20% opacity accent fill provides sufficient presence without overwhelming adjacent nodes.

steps:
  - { number: "1", label: "Ingest" }           # Default styling

  - { number: "2", label: "Transform", focal: true }  # Accent-tint header

Key Source Files

The complete styling pipeline spans three reference documents:

• style-guide.md — Token definitions for backend, external, ink, accent, and paper; contrast constraints; one-accent rule enforcement
• type-process.md — Step header geometry, focal state overrides, and node layout algorithms
• type-architecture.md — Backend tier grouping patterns for system topology diagrams

Complete Working Example

This YAML demonstrates all three node types in a single process diagram:

lanes:
  - { name: ["BACKEND"], key: "BCK" }
  - { name: ["API"], key: "API" }

steps:
  - { number: "1", label: "Ingest" }
  - { number: "2", label: "Transform", focal: true }

nodes:
  # Backend: backend token → white fill, ink stroke

  - lane: "BCK"
    step: 0
    title: "DB-Import"
    sub: "raw → table"
    chips: { in: null, out: "CSV" }

  # API/external: external token → light ink fill, muted ink stroke

  - lane: "API"
    step: 1
    title: "REST-Call"
    sub: "GET /data"
    chips: { in: "JSON", out: null }

The generator resolves tokens through style-guide.md, then applies step header styling per type-process.md.

Summary

• Backend nodes use the backend token with white fill and ink stroke, defined in style-guide.md lines 13-16
• API/external nodes use the external token with tinted ink fill and muted stroke, defined in style-guide.md lines 15-17
• Step headers automatically render with gray fills or accent-tinted focal states per type-process.md lines 12-33
• All styling flows through semantic tokens, ensuring consistent branding and WCAG AA contrast compliance
• The one-accent rule preserves clear visual hierarchy by limiting accent usage to a single focal element

Frequently Asked Questions

How do I change the color of all backend nodes in my diagrams?

Modify the backend token value in style-guide.md. Because the generator resolves this token at render time, updating one line propagates the change across every backend node in every diagram type.

What is the difference between ink @ 0.03 and ink @ 0.30 in external nodes?

These are opacity-modified tokens. ink @ 0.03 produces a nearly transparent fill (3% opacity) for subtle background presence, while ink @ 0.30 at 30% opacity provides visible but muted stroke definition. This progression creates depth without introducing new hues.

Why does the focal step use an accent tint instead of solid accent color?

Per the contrast constraints in style-guide.md, solid accent (#EB6C36) on paper backgrounds passes WCAG AA for large text but risks vibration at small sizes. The 20% opacity tint (rgba(235,108,54,0.20)) maintains accessibility while creating appropriate figure-ground separation for header chips.

Can I create custom node types with their own tokens?

The repository's token system is extensible, but adding tokens requires updating style-guide.md and verifying contrast relationships against the paper background. The backend and external tokens represent the two established semantic categories for nodes: internal systems and external integrations.

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