How Component Types Are Semantically Styled in Diagram Design Nodes

Diagram Design uses the kind attribute—set to standard, focal, or external—to deterministically map every node to a specific visual style using semantic color roles, ensuring consistent semantic meaning across different diagram types and themes.

In the cathrynlavery/diagram-design repository, semantic styling separates logical component meaning from arbitrary color choices. Instead of allowing manual color pickers, the system derives SVG fill, stroke, and typography properties from a constrained vocabulary of types defined in type‑it‑state.md.

The kind Attribute as the Primary Styling Cue

Every component node carries a kind field that acts as the single source of truth for its visual treatment. The system recognizes three distinct kinds, each mapped to a deterministic set of style properties documented in the component-box table at lines 44–48 of type‑it‑state.md.

The styling contract assigns specific values for fill, stroke, stroke-width, stroke-dash pattern, name ink, and sub-label ink:

kind	Fill	Stroke	Stroke width	Stroke dash	Name ink	Sub-ink
standard	#FFFFFF (paper)	ink	1	—	ink	muted
focal	accent @ 0.07	accent	1.4	—	ink	accent (line 1) + muted (line 2)
external	#FFFFFF (paper)	muted	1	4,3	ink	muted

Semantic Meanings of Component Types

The "Reserved field semantics" section in type‑it‑state.md defines the logical intent behind each kind value.

Standard Components

A standard kind indicates a regular component within the diagram scope. It renders with a white paper fill and the default ink stroke, signaling neutral importance. This is the default state for most process elements.

Focal Components

The focal kind marks a "pain-point," bottleneck, or critical element requiring attention. According to [SKILL.md](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/SKILL.md#L65-L73), this kind always overrides any user-supplied color value, forcing the accent palette for both stroke and semi-transparent fill. The sub-label uses accent for the first line to reinforce prominence.

External Components

An external kind identifies components lying outside the diagram's boundary. It visually signals exclusion through a muted stroke and a 4,3 dash pattern, while retaining the white paper fill used by standard components. This creates immediate visual distinction from internal elements.

Type-Agnostic Style Architecture

These semantic styling rules are type-agnostic, meaning they propagate across every visual type built on the generic component model. Whether rendering a high-level architecture view—as demonstrated in type‑high‑level.md—a detailed process flow, or a medallion layout, the repository reuses the same kind-driven style mappings.

The skill guide at [SKILL.md](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/SKILL.md#L65-L73) enforces this contract, stating that a component's kind drives its visual treatment regardless of the specific diagram type. This ensures that a focal node carries the same semantic weight in a high-level overview as it does in a granular process diagram.

Semantic Color Tokens

The actual color values resolve through semantic roles defined in style‑guide.md. These roles—paper, ink, accent, and muted—abstract raw hex codes into logical meanings.

Because styles reference these tokens rather than hard-coded values, the same kind definition renders correctly across light and dark themes. The accent role might resolve to a bright orange in a light theme or a vibrant yellow in a dark theme, but the semantic intent—"this requires attention"—remains constant.

Practical Implementation Examples

When defining components in YAML input, the kind field drives the final SVG output:

# Component definitions in YAML

components:
  - id: shared-drive
    name: "Shared Drive"
    sub: "No version control"
    kind: focal          # → accent fill & stroke, accent sub‑label

  - id: analyst-mach
    name: "Analyst Machines"
    sub: "SPSS · SAS"
    kind: standard       # → white fill, ink stroke

  - id: civil-reg
    name: "Civil Registry"
    sub: "external data"
    kind: external       # → white fill, muted dashed stroke

The resulting SVG fragments apply the computed styles:

<!-- focal component -->
<rect x="…" y="…" width="…" height="…" fill="{accent @ 0.07}" stroke="{accent}" stroke-width="1.4"/>
<text class="node-name" fill="{ink}">Shared Drive</text>
<text class="sublabel" fill="{accent}">No version control</text>

<!-- standard component -->
<rect x="…" y="…" width="…" height="…" fill="#FFFFFF" stroke="{ink}" stroke-width="1"/>
<text class="node-name" fill="{ink}">Analyst Machines</text>
<text class="sublabel" fill="{muted}">SPSS · SAS</text>

<!-- external component -->
<rect x="…" y="…" width="…" height="…" fill="#FFFFFF" stroke="{muted}" stroke-width="1" stroke-dasharray="4,3"/>
<text class="node-name" fill="{ink}">Civil Registry</text>
<text class="sublabel" fill="{muted}">external data</text>

Summary

• Three semantic kinds—standard, focal, and external—control all visual styling in Diagram Design nodes.
• The kind attribute maps to deterministic SVG properties including fill opacity, stroke width, and dash patterns.
• Focal components force the accent palette and ignore user color overrides, highlighting bottlenecks consistently.
• External components use dashed muted strokes to signal out-of-scope elements.
• Semantic color roles (paper, ink, accent, muted) defined in the style guide ensure theme consistency.
• These rules apply universally across high-level, process, and medallion diagram types.

Frequently Asked Questions

What determines the visual style of a node in Diagram Design?

The visual style is determined exclusively by the kind attribute in the node's data structure. This field—set to standard, focal, or external—triggers a specific mapping to fill colors, stroke properties, and typography defined in type‑it‑state.md.

How does the focal component type differ from standard styling?

Focal components use the accent color role for both the stroke (width 1.4) and a semi-transparent fill (accent @ 0.07), whereas standard components use a white paper fill and the neutral ink stroke (width 1). Additionally, focal components display the first line of the sub-label in accent rather than muted.

Can I override the color of a focal component with a custom value?

No. According to the contract documented in [SKILL.md](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/SKILL.md#L65-L73), focal components always ignore user-supplied color values. The system enforces the accent palette to maintain consistent visual signaling for pain-points and critical bottlenecks.

Where are the semantic color roles like accent and muted defined?

The semantic color roles—including paper, ink, accent, and muted—are defined in style‑guide.md. These tokens abstract raw color values, allowing the same kind-based styles to render correctly across both light and dark themes.

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