# How to Customize Accent Colors and Focal Elements in Instagit Diagrams

> Learn to customize accent colors and focal elements in Instagit diagrams. Set focal elements to true in JSON data and define your accent color in style-guide.md for unique designs.

- Repository: [Cathryn Lavery/diagram-design](https://github.com/cathrynlavery/diagram-design)
- Tags: how-to-guide
- Published: 2026-09-12

---

**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`](https://github.com/cathrynlavery/diagram-design/blob/main/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)](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`](https://github.com/cathrynlavery/diagram-design/blob/main/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:

```markdown
| 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:

```json
{
  "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/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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:

```bash
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`](https://github.com/cathrynlavery/diagram-design/blob/main/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:

   ```bash
   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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/type-venn.md) and [`type-wardley.md`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md) to achieve sufficient contrast before the CI pipeline will accept the change.