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

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 and 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, 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 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, 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 specification defines treatments for hierarchical data cells:

Standard Cells:

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

Focal Cells:

<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, 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 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), 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 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, 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: Asserts that focal cells use rgba(235,108,54,0.16) fill and #eb6c36 stroke.
• 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, 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, 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.

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