# How Node Types Are Mapped to Treatments (Fill and Stroke) in Diagram Design

> Discover how node types map to treatments like fill and stroke in Diagram Design. Understand semantic node styling and reference file configurations for clear, effective diagrams.

- Repository: [Cathryn Lavery/diagram-design](https://github.com/cathrynlavery/diagram-design)
- Tags: internals
- Published: 2026-08-22

---

**Diagram Design enforces a strict mapping where each semantic node type is assigned a specific treatment—combinations of rgba fill values, stroke colors, and weights—defined in reference files under `skills/diagram-design/references/`, with focal elements using accent palettes and non-focal elements using muted or store palettes.**

The `cathrynlavery/diagram-design` repository implements a visual grammar system that translates abstract node types into concrete SVG styling attributes. Treatments are not arbitrary; they follow a five-tier palette hierarchy (paper → ink → muted → accent → store) and are validated by automated verification scripts to ensure consistent visual semantics across flowcharts, UML diagrams, Sankey plots, and treemaps.

## Treatment Fundamentals and the Palette Hierarchy

All node treatments derive from a core color system defined in the repository’s design tokens. The hierarchy governs contrast levels:

- **Paper**: Background color (high opacity for surfaces).
- **Ink**: Primary foreground color (#2d3142) for borders and solid fills.
- **Muted**: Desaturated variant (#4f5d75) at reduced opacity (0.16–0.28) for secondary elements.
- **Accent**: High-visibility highlight color (#eb6c36) used exclusively for focal nodes.
- **Store**: Low-contrast combination (ink fill at 0.04 opacity, muted stroke at 0.28 opacity) for background or non-focal cells.

**Focal nodes**—elements requiring user attention—always use **accent** fills (e.g., `rgba(235,108,54,0.16)`) and **accent** strokes (e.g., `#eb6c36`). **Non-focal nodes** use **muted** or **store** treatments to recede visually. This dichotomy is enforced by verification scripts such as [`scripts/verify-treemap.py`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/verify-treemap.py) and [`scripts/verify-sankey.py`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/verify-sankey.py), which parse generated SVG and assert that fill and stroke attributes match the specifications in the corresponding reference files.

## Per-Diagram Node Type Mappings

Each diagram type maintains its own treatment specification document in `skills/diagram-design/references/`. Below are the precise mappings from node semantics to SVG attributes.

### Flowchart Nodes

According to [`skills/diagram-design/references/type-flowchart.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/type-flowchart.md), flowchart nodes rely on **shape** to encode type (rectangles for processes, diamonds for decisions, rounded rectangles for terminators). Fill color reinforces this encoding:

- **Process nodes**: Paper fill (`#ffffff`) with ink stroke (`#2d3142`).
- **Decision nodes**: Paper fill with ink stroke, though the diamond shape provides the primary signal.
- **Start/End nodes**: Ink fill (`#2d3142`) with paper stroke or contrasting border.

The specification emphasizes that while shape carries the primary semantic load, fill opacity shifts (muted vs. ink) can indicate active versus inactive states.

### UML Class Relationship Markers

The [`skills/diagram-design/references/type-uml-class.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/type-uml-class.md) file defines treatments for relationship terminations:

| Relationship | Shape | Fill | Stroke | Specification |
|-------------|-------|------|--------|---------------|
| **Inheritance** (`extends`) | Hollow triangle | Paper (`#ffffff`) | Ink (`#2d3142`), solid, 1px | "Inheritance—solid line with large hollow triangle head, paper fill, ink stroke." |
| **Composition** (owned) | Filled diamond | Ink (`#2d3142`) | Ink (`#2d3142`) | "Composition—solid line with filled diamond at owner end, ink fill." |

These treatments ensure that inheritance (generalization) appears visually lighter (hollow) while composition appears solid and heavy, reflecting the strength of the relationship.

### Sankey Diagram Bars

In [`skills/diagram-design/references/type-sankey.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/type-sankey.md), Sankey nodes are rendered as vertical bars with rigid styling:

- **Geometry**: Width fixed at 12px.
- **Fill**: Solid **ink** (`#2d3142`), no opacity reduction.
- **Stroke**: None (explicitly `stroke="none"`).

This treatment distinguishes Sankey nodes from flowchart processes despite both using rectangular geometry—the absence of a stroke and the specific width enforcement create a distinct "bar" visual language.

### Treemap Cells

The [`skills/diagram-design/references/type-treemap.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/type-treemap.md) specification defines treatments for hierarchical data cells:

**Standard Cells**:

```svg
<rect fill="rgba(45,49,66,0.16)" stroke="rgba(45,49,66,0.30)" stroke-width="1"/>

```

**Focal Cells**:

```svg
<rect fill="rgba(235,108,54,0.16)" stroke="#eb6c36" stroke-width="1.5"/>

```

The 1.5px accent stroke and tinted orange fill (`rgba(235,108,54,0.16)`) immediately draw attention to the selected data subset, while standard cells use ink at 16% opacity fill and 30% opacity stroke to remain legible but subordinate.

### Scatter Plot Points

Per [`skills/diagram-design/references/type-scatter.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/type-scatter.md), point treatments encode focal status:

- **Standard Points**: Muted fill at 20% opacity (`rgba(79,93,117,0.20)`) with muted stroke (`#4f5d75`), 1px weight.
- **Focal Points**: Accent fill at 15% opacity (`rgba(235,108,54,0.15)`) with accent stroke (`#eb6c36`), 1.2px weight.

The slight increase in stroke width (1.0px to 1.2px) for focal points provides the "pop" necessary for data highlighting without overwhelming the chart.

### Quadrant Grid Cells

[`skills/diagram-design/references/type-quadrant.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/type-quadrant.md) maps strategic cells to treatments based on priority:

- **Non-Focal Cells**: **Store** treatment—ink fill at 4% opacity (`rgba(45,49,66,0.04)`) with muted stroke at 28% opacity (`rgba(79,93,117,0.28)`).
- **Focal Cells**: **Accent-tint** fill (`rgba(235,108,54,0.16)`) with **accent** stroke (`#eb6c36`) at 1.2px.

This creates a "spotlight" effect where the focal quadrant appears illuminated while others fade into the background grid.

### Process Step Chips

For linear process diagrams ([`skills/diagram-design/references/type-process.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/type-process.md)), step nodes use chip-style rectangles:

- **Default Step**: Muted fill (`#4f5d75`) with default text color.
- **Focal Step**: Accent fill (`#eb6c36`) with accent-colored text (`#eb6c36`).

Unlike treemaps or scatter plots that use opacity modulation, process steps use solid fills to create distinct "pills" of color that guide the eye through sequential workflows.

### Sequence Diagram Markers

[`skills/diagram-design/references/type-sequence.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/type-sequence.md) treats message markers as filled shapes to indicate synchronization:

- **Synchronous Call (Solid)**: Filled with **muted** or link-blue, never hollow. Stroke matches fill color, solid line weight.
- **Return Message (Dashed)**: Filled marker (never open) with **dashed** stroke in muted color.

The "filled" requirement ensures that arrowheads appear solid and authoritative, distinguishing them from open arrowheads used in inheritance diagrams.

### Radar Chart Vertices

Per [`skills/diagram-design/references/type-radar.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/type-radar.md), vertex treatments distinguish series importance:

- **Focal Series Vertices**: Filled circles with **accent** color at 18% opacity (`rgba(235,108,54,0.18)`), radius 4px, and accent stroke at 1.8px.
- **Non-Focal Series**: Vertices are "stroke-and-fill only"—rendered as outlines without solid fill, using muted palette colors.

This ensures that only the primary data series appears "solid" while comparative series remain as wireframe overlays.

## Programmatic Enforcement via Verification Scripts

The repository does not rely on manual compliance. Python scripts in the `scripts/` directory programmatically validate SVG output against the reference specifications:

- **[`scripts/verify-treemap.py`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/verify-treemap.py)**: Asserts that focal cells use `rgba(235,108,54,0.16)` fill and `#eb6c36` stroke.
- **[`scripts/verify-sankey.py`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/verify-sankey.py)**: Validates that node bars have `width="12"`, solid ink fill, and no stroke attribute.
- **`scripts/verify-*.py`**: Each diagram type has a corresponding validator that checks for prohibited treatments (e.g., ensuring non-focal scatter points do not use accent colors).

These scripts parse the generated XML and fail CI pipelines if node treatments deviate from the mappings defined in the reference files.

## Summary

- **Treatments combine fill rgba values, stroke colors, and stroke weights** to encode node semantics and focal priority.
- **Five-tier palette**: paper, ink, muted, accent, and store, with accent reserved strictly for focal elements.
- **Reference files** in `skills/diagram-design/references/` (e.g., [`type-treemap.md`](https://github.com/cathrynlavery/diagram-design/blob/main/type-treemap.md), [`type-uml-class.md`](https://github.com/cathrynlavery/diagram-design/blob/main/type-uml-class.md)) define exact SVG attributes for each node type.
- **Verification scripts** (`scripts/verify-*.py`) enforce compliance by checking generated SVG against specifications.
- **Shape and color collaborate**: In flowcharts, shape signals type while fill signals state; in UML, fill signals relationship strength (hollow vs. filled diamonds).

## Frequently Asked Questions

### What is the difference between "muted" and "store" treatments?

**Muted** uses medium opacity (typically 0.16–0.28) of the ink or muted hex color (#4f5d75) for secondary elements that need to remain visible but not prominent. **Store** uses extremely low opacity (0.04 for fill, 0.28 for stroke) to push elements into the background, effectively creating a "watermark" effect for grid cells or non-focal quadrants.

### How does the system distinguish focal nodes from non-focal nodes programmatically?

The system applies the **accent** palette exclusively to focal nodes—specifically `rgba(235,108,54,0.15)` to `0.18` opacity fills and `#eb6c36` strokes. Verification scripts check for these specific hex and rgba values; if a node lacks these accent attributes, it is classified as non-focal and must use muted or store treatments instead.

### Where are the node-to-treatment mappings defined in the codebase?

All mappings reside in Markdown reference files located at `skills/diagram-design/references/`. Each diagram type has its own file (e.g., [`type-sankey.md`](https://github.com/cathrynlavery/diagram-design/blob/main/type-sankey.md), [`type-scatter.md`](https://github.com/cathrynlavery/diagram-design/blob/main/type-scatter.md)) that documents the required fill colors, stroke colors, stroke widths, and opacity values for every node variant.

### Can I customize the accent color for focal nodes?

The current architecture hardcodes the accent color as `#eb6c36` (orange) with corresponding rgba tints in the reference files and verification scripts. While the source code allows modification of these constants, doing so requires updating both the reference documentation and the validation logic in `scripts/verify-*.py` to maintain consistency across the diagram generation pipeline.