# How Design Tokens Are Mapped from Extracted Colors in Diagram‑Design

> Learn how Diagram-Design maps extracted colors to semantic design tokens using a luminance and saturation heuristic. Discover automatic mapping for paper, ink, accent, muted, and link.

- Repository: [Cathryn Lavery/diagram-design](https://github.com/cathrynlavery/diagram-design)
- Tags: deep-dive
- Published: 2026-08-15

---

**Diagram‑Design automatically maps extracted source colors to semantic design tokens using a luminance and saturation heuristic: the lightest color becomes `paper`, the darkest becomes `ink`, the most saturated becomes `accent`, and remaining hues fill secondary roles like `muted` and `link`.**

Diagram‑Design is an open‑source skill maintained in the `cathrynlavery/diagram-design` repository that converts imported diagrams into a consistent, token‑driven visual system. When you import a source file—such as a Draw.io diagram—the tool translates raw hex values into meaningful design tokens defined in [`style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md). This article details exactly how the repository performs this mapping, referencing the specific scripts and configuration files that govern the transformation.

## The Color Extraction Pipeline

Before mapping can occur, the system extracts the raw palette from the source diagram. The extraction logic resides in [`skills/diagram-design/scripts/drawio_extract.py`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/scripts/drawio_extract.py) for Draw.io XML and [`mermaid_extract.py`](https://github.com/cathrynlavery/diagram-design/blob/main/mermaid_extract.py) for Mermaid JSON.

These parsers scan the source markup, identify unique fill colors, and return them as an ordered list sorted by **luminance** and **saturation**. This ordering is critical because it determines which color assumes which semantic role in the subsequent mapping phase.

### How Colors Are Ordered

The extraction scripts calculate two metrics for every hex value found in the source:

- **Luminance (L):** Perceived brightness, used to identify background versus foreground tones.
- **Saturation (S):** Chroma intensity, used to detect accent or highlight colors.

The resulting ordered list is then passed to the mapper for token assignment.

## Heuristic Mapping to Semantic Tokens

Documented in [`skills/diagram-design/references/import-drawio.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/import-drawio.md), the mapping rules are codified as a deterministic heuristic that assigns extracted colors to specific token roles. If no external token file is provided, the following logic applies:

- **Lightest fill (high L)** → **`paper`**: Assumed to be the canvas or background color.
- **Darkest fill (low L)** → **`ink`**: Used for primary text, lines, and borders.
- **Most saturated hue (high S)** → **`accent`**: Reserved for calls-to-action, highlights, and interactive elements.
- **Remaining fills** → **`muted`**, **`link`**, etc.: Distributed based on hue similarity to the accent color to maintain chromatic harmony.

Once assigned, these mappings are written back into [`style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md), ensuring all subsequent diagrams inherit the new skin.

## Overriding with Manual Token Files

If a project already maintains a design token specification, the heuristic step can be bypassed entirely. When running the onboarding flow, you may supply a JSON file such as [`tokens.json`](https://github.com/cathrynlavery/diagram-design/blob/main/tokens.json) or [`design-tokens.json`](https://github.com/cathrynlavery/diagram-design/blob/main/design-tokens.json):

```bash
diagram-design onboarding --tokens ./my-brand/tokens.json

```

In this mode, the skill copies the user-supplied values verbatim into [`style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md), skipping the luminance and saturation analysis. This guarantees brand consistency when exact hex values must be preserved.

## Key Implementation Files

Understanding the file structure clarifies how the pipeline fits together:

- **[`skills/diagram-design/scripts/drawio_extract.py`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/scripts/drawio_extract.py)**: Parses Draw.io XML and returns the ordered color list.
- **[`skills/diagram-design/references/import-drawio.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/import-drawio.md)**: Documents the heuristic rules that map source colors to token roles.
- **[`skills/diagram-design/references/onboarding.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/onboarding.md)**: Describes the full workflow from palette extraction to style guide generation.
- **[`skills/diagram-design/SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/SKILL.md)**: Core skill documentation detailing token handling.
- **[`style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md)**: The canonical storage for token definitions (`paper`, `ink`, `accent`, `muted`, `link`).

## Practical Example

To see the mapping in action, import a Draw.io file:

```bash

# Extract palette and map tokens automatically

diagram-design import-drawio my-diagram.drawio

```

The CLI outputs the raw colors detected:

```text
#dae8fc #d5e8d4 #e1d5e7 #4a90e2 ...

```

Based on the heuristic, the system generates the following token assignments in [`style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md):

- `paper`: `#dae8fc`
- `ink`: `#4a90e2`
- `accent`: `#e1d5e7`
- `muted`: `#d5e8d4`

## Summary

- **Extraction**: [`drawio_extract.py`](https://github.com/cathrynlavery/diagram-design/blob/main/drawio_extract.py) and [`mermaid_extract.py`](https://github.com/cathrynlavery/diagram-design/blob/main/mermaid_extract.py) parse source files and sort colors by luminance and saturation.
- **Heuristic mapping**: Lightest colors become `paper`, darkest become `ink`, most saturated become `accent`, and leftovers populate secondary roles.
- **Manual override**: Supplying a [`tokens.json`](https://github.com/cathrynlavery/diagram-design/blob/main/tokens.json) file bypasses automatic mapping and writes explicit values to [`style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md).
- **Persistence**: All token definitions live in [`style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md), acting as the single source of truth for diagram styling.

## Frequently Asked Questions

### What happens if my diagram only has two colors?

If the extraction yields fewer colors than token roles, the heuristic prioritizes `paper` and `ink` first. The accent and muted roles may remain undefined or inherit fallback values specified in [`style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md).

### Can I edit the mapped tokens after importing?

Yes. The mapping writes to [`style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md), which is a standard markdown file. You can manually edit the hex values under each token heading, and subsequent diagram generations will use your updated colors.

### Does Diagram‑Design support formats other than Draw.io?

Yes. The repository includes [`mermaid_extract.py`](https://github.com/cathrynlavery/diagram-design/blob/main/mermaid_extract.py) for Mermaid JSON diagrams. The same luminance and saturation ordering applies regardless of source format, ensuring consistent token mapping across import types.

### How does the system handle grayscale diagrams?

For grayscale sources, saturation values approach zero, so the "most saturated" heuristic defaults to the darkest gray for the `accent` role. It is recommended to provide a manual [`tokens.json`](https://github.com/cathrynlavery/diagram-design/blob/main/tokens.json) for monochrome designs to ensure semantic accuracy.