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

> Learn how backend, API, and step nodes are styled in Diagram Design. Discover the semantic token system that defines node colors for a consistent visual experience.

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

---

**Backend, API, and step nodes in Diagram Design are styled through a semantic token system defined in [`style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md) and [`type-process.md`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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/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.

```yaml

# 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/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.

```yaml

# 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/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.

```yaml
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`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md)** — Token definitions for `backend`, `external`, `ink`, `accent`, and `paper`; contrast constraints; one-accent rule enforcement
- **[`type-process.md`](https://github.com/cathrynlavery/diagram-design/blob/main/type-process.md)** — Step header geometry, focal state overrides, and node layout algorithms
- **[`type-architecture.md`](https://github.com/cathrynlavery/diagram-design/blob/main/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:

```yaml
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`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md), then applies step header styling per [`type-process.md`](https://github.com/cathrynlavery/diagram-design/blob/main/type-process.md).

## Summary

- **Backend nodes** use the `backend` token with white fill and `ink` stroke, defined in [`style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md) lines 15-17
- **Step headers** automatically render with gray fills or accent-tinted focal states per [`type-process.md`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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.