How to Customize Accent Colors and Focal Elements in Instagit Diagrams

Instagit's diagram-design system enforces a strict one-accent rule where a single focal element per diagram receives the accent color defined in style-guide.md, controlled by setting focal: true in the JSON data.

The cathrynlavery/diagram-design repository implements a token-based design system that standardizes visual emphasis across all diagram types. Understanding how to customize accent colors and focal elements allows you to maintain brand consistency while highlighting critical data points. This guide explains the centralized token architecture and the JSON schema patterns that drive visual hierarchy.

Understanding the One-Accent Rule

The repository follows a strict one-accent design contract: every diagram may contain at most a single accent token that highlights the editorially focal element. This constraint ensures visual clarity and prevents cognitive overload in data storytelling.

The accent token is defined centrally in [style-guide.md](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md) and comprises two variants:

• accent: The primary color value
• accent-tint: A translucent variant (typically 20% opacity) for fills and backgrounds

When an element is marked as focal in the source data, the rendering pipeline automatically applies these tokens to the element's SVG properties—specifically accent-tint for fill and accent for stroke.

Editing Accent Colors in the Style Guide

All color definitions live in the markdown table at the top of style-guide.md. To customize the accent color, modify the HEX or RGBA values for both light and dark skins.

Token Structure in style-guide.md

The style guide defines tokens using a table format that maps semantic names to color values:

| Token        | Light skin | Dark skin |
|--------------|------------|-----------|
| **accent**   | #eb6c36    | #f08a59   |
| accent-tint | rgba(235,108,54,0.20) | rgba(240,138,89,0.20) |
| ink          | #2a2a2a    | #e5e5e5   |
| muted        | #777777   | #bbbbbb  |

To change the accent color globally, update the HEX values for the accent row and adjust the RGBA alpha channels in accent-tint to match your new base color. Because all diagram types reference these tokens by name rather than hardcoded values, the change propagates immediately to waterfall charts, Wardley maps, Venn diagrams, and all other supported visualizations.

Marking Focal Elements in Diagram Data

Every diagram type uses a JSON schema that supports a boolean focal flag (or shorthand focal in array contexts). When set to true, the rendering engine applies the accent token to that specific element.

Declaring Focal Elements in Waterfall Charts

In a waterfall diagram, add focal: true to the specific bar object you want to highlight:

{
  "type": "waterfall",
  "bars": [
    { "label": "Revenue", "value": 120 },
    { "label": "Cost",    "value": -30 },
    { "label": "Profit",  "value":  90, "focal": true }
  ]
}

When rendered, the Profit bar receives:

• fill: rgba(235,108,54,0.12) (accent-tint)
• stroke: accent (the primary accent color)

Focal Flag Locations by Diagram Type

Different diagram types expose the focal flag in different schema locations, but all follow the same accent application logic:

• Waterfall: bars[].focal — applies accent-tint fill and accent stroke
• Wardley: components[].focal — applies accent-tint fill and accent stroke on dots and arrows
• Venn: intersections[].focal — applies coral accent fill and stroke
• UML Class: classes[].focal — applies accent-tint fill and accent stroke
• Treemap: cells[].focal — applies accent-tint fill and 1.5px accent stroke
• Sankey: paths[].focal — applies accent-tint fill and accent stroke on ribbons
• Scatter: points[].focal — applies accent fill and stroke
• Process: steps[] or nodes[] with focal: true — applies accent fill or border
• Polar: categories[].focal — applies accent stroke on value rays
• Kanban: cards[].blocked && focal — applies accent bar on left edge
• Journey: dots[].focal — applies accent dot and segment coloring

Reference documentation for each type resides in skills/diagram-design/references/type-*.md (e.g., [type-waterfall.md](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/type-waterfall.md)), which specifies exact SVG attributes and contrast requirements.

Enforcing Design Contracts with Verification Scripts

The repository includes Python verification scripts in the scripts/ directory that enforce the one-accent rule during CI. These scripts prevent merging diagrams that violate contrast requirements or contain multiple focal elements.

For example, scripts/verify-waterfall.py performs the following checks:

• Validates that exactly one bar has focal: true
• Confirms the focal bar uses only the accent token for highlighting
• Verifies stroke widths and fill opacities match the style guide specifications

Run the verification locally before committing changes:

python scripts/verify-waterfall.py path/to/diagram.json

If the script reports errors, the CI pipeline will block the merge until you correct the accent usage or focal element count.

Practical Customization Workflow

Follow this sequence to safely customize accent colors and focal elements:

1. Update the style guide — Edit style-guide.md to change the accent and accent-tint values for your target skin (light or dark).

2. Verify contrast requirements — Execute the relevant verification script for your diagram type to ensure the new accent color maintains accessibility standards:

   python scripts/verify-waterfall.py sample-diagram.json

3. Assign focal elements — Add focal: true to the JSON object representing the data point you want to emphasize.

4. Commit and push — The rendering pipeline will automatically apply the updated accent token to all focal elements across the documentation set.

Summary

• Centralized tokens: All accent colors are defined in style-guide.md using the accent and accent-tint tokens, ensuring consistent color application across every diagram type.
• One-accent enforcement: The design system permits only one focal element per diagram, marked by the focal: true boolean flag in the JSON schema.
• Automatic rendering: When focal: true is present, the system automatically applies accent-tint fills and accent strokes to the element's SVG representation.
• CI validation: Verification scripts in scripts/verify-*.py enforce compliance with the one-accent rule and contrast requirements before code merges.

Frequently Asked Questions

How do I change the accent color for all diagrams in the repository?

Edit the accent token values in style-guide.md. Update the HEX codes for both light and dark skins, and adjust the RGBA values in accent-tint to maintain the correct opacity levels. Because diagrams reference these tokens by name, the change applies globally without modifying individual chart files.

Can I have multiple focal elements in a single diagram?

No. The system enforces a strict one-accent rule that permits only one focal: true flag per diagram. If you add multiple focal flags, verification scripts like scripts/verify-waterfall.py will fail the CI check, preventing the merge. This constraint ensures visual hierarchy remains clear and uncluttered.

Where can I find the specific accent application rules for Venn diagrams or Wardley maps?

Consult the reference documentation in skills/diagram-design/references/. Files like type-venn.md and type-wardley.md specify exactly which SVG attributes receive the accent treatment (fill, stroke, or marker colors) and any special conditions—for example, Wardley maps apply accent styling to both dots and connecting arrows when components[].focal is true.

What happens if my new accent color fails the verification script?

The script checks that accent colors meet contrast ratio requirements against background skins. If your new color fails, the script outputs a contrast error and exits with a non-zero status. You must adjust the HEX values in style-guide.md to achieve sufficient contrast before the CI pipeline will accept the change.

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