How to Customize Diagram Appearance in Diagram Design: A Complete Schema Reference

Customize diagram appearance in Diagram Design using a declarative JSON schema with component color overrides, style tokens for connectors, and focal element rules, then export via the /export-diagram command.

Diagram Design provides a structured, code-driven approach to visual customization through its declarative schema system. Every diagram type supports granular control over colors, connector styles, and export formats while maintaining visual consistency through enforced design constraints. This guide covers the complete customization surface based on the cathrynlavery/diagram-design source code.

Component Color Overrides

Each diagram type exposes a "Component color override" section in its reference documentation. These overrides allow per-element color assignment using hex values in the diagram's input JSON.

Supported Elements

• Nodes — individual steps or entities
• Lanes — horizontal or vertical swimlanes
• Tiers — hierarchical layers (in Wardley maps)
• Paths — routed connection sequences

Color Override Syntax

{
  "nodes": [
    { "id": "node1", "label": "Ingest", "color": "#5a7d9a" },
    { "id": "node2", "label": "Validate", "color": "#b85450" }
  ],
  "lanes": [
    { "id": "lane1", "label": "Data Quality", "color": "#5a7d9a" }
  ]
}

The hex string applies to both fill and label color. All colors draw from a shared palette across diagram types to ensure consistency.

Palette Limits

The validator enforces strict limits per diagram type. In skills/diagram-design/references/type-process.md (lines 256-259), the framework allows:

• Maximum 3 custom-colored nodes per process diagram
• Maximum 2 custom-colored tiers per Wardley map

These constraints prevent visual fragmentation while preserving design system integrity.

Style Tokens for Connectors

Connectors use semantic style tokens rather than raw colors, enabling adaptive theming. The style attribute accepts three values:

| Token | Visual Treatment | Use Case | |-------|----------------|----------| | neutral | Muted ink color | Background or secondary flows | | link | Distinct accent color | Regular process flows | | accent | Highlighted emphasis color | Focal or editorial paths |

Connector Style Example

{
  "connectors": [
    { "from": "node1", "to": "node2", "style": "link" },
    { "from": "node2", "to": "node3", "style": "accent" }
  ]
}

These tokens drive stroke color, width, and arrowhead marker selection as defined in each type reference's Style guide entries.

Focal Element Rules

Every diagram type designates a focal node, step, or tier that receives automatic accent styling. This creates visual hierarchy without manual configuration.

Critical Constraint

As documented in skills/diagram-design/references/type-process.md (lines 383-384), any explicit color on a focal element is ignored. The accent style always takes precedence, ensuring the visual hierarchy remains intact regardless of custom color assignments.

Export Customization

The /export-diagram command in commands/export-diagram.md provides fine-grained control over output generation.

Command Syntax

/export-diagram path/to/diagram.html [options]

Available Flags

• --svg-only — Generate only SVG output
• --png-only — Generate only PNG output
• --scale=<1|2|3> — Set device scale for PNG rendering
• --output=<path> — Custom output directory and base filename

Export Examples

High-resolution PNG export:

/export-diagram docs/architecture.html --png-only --scale=3 --output=dist/architecture

Dual-format export to custom path:

/export-diagram src/diagram.html --output=assets/diagrams/flow

This creates both assets/diagrams/flow.svg and assets/diagrams/flow.png.

Complete Customization Example

The following process diagram demonstrates all customization layers working together:

{
  "type": "process",
  "nodes": [
    { "id": "n1", "label": "Collect data", "color": "#5a7d9a" },
    { "id": "n2", "label": "Clean data",   "color": "#b85450" },
    { "id": "n3", "label": "Analyze",      "color": "#7a8c47" }
  ],
  "lanes": [
    { "id": "l1", "label": "Data Quality", "color": "#5a7d9a" }
  ],
  "connectors": [
    { "from": "n1", "to": "n2", "style": "link" },
    { "from": "n2", "to": "n3", "style": "accent" }
  ]
}

Validation notes:

• 3 nodes with custom colors (at limit for process diagrams)
• Focal node will render with accent style regardless of any color value
• Lane color matches first node for visual grouping

Key Reference Files

File Path	Customization Domain
commands/export-diagram.md	Export flags, output formats, validation rules
skills/diagram-design/references/type-process.md	Node/step colors, palette limits (≤3), focal rules
skills/diagram-design/references/type-wardley.md	Tier colors, evolution axis styling
skills/diagram-design/references/type-venn.md	Stroke colors, intersection opacity
skills/diagram-design/references/type-sankey.md	Ribbon fills, flow color inheritance
skills/diagram-design/references/export.md	Export workflow and integration patterns

Summary

• Component color overrides use hex values in JSON, limited to 3 nodes or 2 tiers per diagram
• Style tokens (neutral, link, accent) control connector appearance semantically
• Focal elements automatically receive accent style, ignoring explicit color values
• Export flags (--scale, --output, format selectors) fine-tune output generation
• Reference files in skills/diagram-design/references/ document type-specific rules

Frequently Asked Questions

What happens if I specify more than 3 custom colors in a process diagram?

The validator rejects the input. According to type-process.md (lines 256-259), the framework enforces a hard limit of 3 custom-colored nodes to maintain visual coherence. Reduce custom colors or rely on the default palette.

Can I override the color of a focal node?

No. As implemented in type-process.md (lines 383-384), focal nodes always render with the accent style regardless of any color property. This preserves the visual hierarchy that makes focal elements immediately recognizable.

How do I export a diagram at print resolution?

Use the --scale=3 flag with PNG output: /export-diagram file.html --png-only --scale=3. This renders at 3× device scale, producing 300 DPI equivalent output suitable for print materials.

Where are style token colors defined?

Style token colors are defined in each type reference's Style guide section, not in individual diagram files. The tokens (neutral, link, accent) map to theme values that adapt to light/dark contexts while maintaining consistent semantics across diagram types.

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