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

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. 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 for Draw.io XML and 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, 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, 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 or design-tokens.json:

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

In this mode, the skill copies the user-supplied values verbatim into 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: Parses Draw.io XML and returns the ordered color list.
• skills/diagram-design/references/import-drawio.md: Documents the heuristic rules that map source colors to token roles.
• skills/diagram-design/references/onboarding.md: Describes the full workflow from palette extraction to style guide generation.
• skills/diagram-design/SKILL.md: Core skill documentation detailing token handling.
• 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:

# Extract palette and map tokens automatically

diagram-design import-drawio my-diagram.drawio

The CLI outputs the raw colors detected:

#dae8fc #d5e8d4 #e1d5e7 #4a90e2 ...

Based on the heuristic, the system generates the following token assignments in style-guide.md:

• paper: #dae8fc
• ink: #4a90e2
• accent: #e1d5e7
• muted: #d5e8d4

Summary

• Extraction: drawio_extract.py and 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 file bypasses automatic mapping and writes explicit values to style-guide.md.
• Persistence: All token definitions live in 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.

Can I edit the mapped tokens after importing?

Yes. The mapping writes to 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 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 for monochrome designs to ensure semantic accuracy.

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