# How Diagram Design Extracts Design Tokens from an Existing Agent Skill

> Learn how Diagram Design extracts design tokens from your existing Agent Skill by parsing CSS and JSON files, streamlining your style guide management.

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

---

**Diagram Design extracts design tokens by reading the source skill's [`references/style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/references/style-guide.md) file, parsing CSS custom properties and JSON token files, and writing the merged values into the current project's style guide during the declarative onboarding workflow.**

The `cathrynlavery/diagram-design` repository includes a token extraction mechanism that allows users to import visual design systems from existing Agent Skills. When you choose to extract design tokens from an installed skill, the onboarding workflow locates, parses, and migrates color, typography, and spacing definitions without executing any foreign code.

## The Token Extraction Workflow

### Locating the Source Skill's Design System

When you select option **(b) "extract from an installed skill"** during onboarding, Diagram Design searches for the [`references/style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/references/style-guide.md) file inside the installed skill's directory. This markdown file serves as the canonical location where all **design tokens**—including color palettes, typography scales, and spacing values—are defined.

### Parsing the Style Guide

The onboarding code reads the source style guide and applies a multi-layer parsing strategy. First, it extracts **CSS custom properties** using a regular expression matching `--\w+:\s*#[0-9a-fA-F]{3,6}` to capture hex color definitions like `--paper:#f5f5f5`. Second, it loads any **JSON token files** shipped with the source skill, which take precedence over markdown values. Finally, it falls back to token-like prose following the "semantic-role = value" pattern.

According to [`references/onboarding.md`](https://github.com/cathrynlavery/diagram-design/blob/main/references/onboarding.md) at lines 286-288, CSS custom properties and JSON tokens take priority over prose definitions in the extraction hierarchy.

### Building the Brand-Specific Style Guide

After parsing, the extracted tokens are written to the current project's [`references/style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/references/style-guide.md), overwriting the default palette described in [`SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/SKILL.md) (lines 25-31). The default system uses white-smoke paper, jet-black ink, and atomic-tangerine accent colors, but these are replaced with the imported brand values to ensure visual consistency.

### Running the Pre-Output Checklist

Once tokens are in place, the skill executes [`scripts/self_check.py`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/self_check.py) to verify that the generated SVG complies with the design system and connector rules. This pre-output check ensures that the new tokens integrate correctly with Diagram Design's rendering engine, as specified in [`SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/SKILL.md) section 9 (lines 49-57).

## Implementation and Code Examples

The extraction process is completely **declarative**—no code from the source skill is executed, only static token definitions are read. This guarantees safety while enabling automatic brand consistency.

When running the onboarding command:

```bash
instabase skill onboard diagram-design

```

Select option **(b)** when prompted to extract from an installed skill. The underlying Python logic performs the extraction:

```python
import pathlib
import re
import json

# Path to the source skill's style-guide

src = pathlib.Path("/path/to/installed/skill/references/style-guide.md")
text = src.read_text()

# 1. Extract CSS custom properties (e.g., --paper:#f5f5f5)

tokens = {
    m.group(1): m.group(2)
    for m in re.finditer(r'--([\w-]+)\s*:\s*(#[0-9a-fA-F]{3,6})', text)
}

# 2. Load JSON token files (takes precedence over markdown)

json_path = src.parent / "tokens.json"
if json_path.is_file():
    tokens.update(json.load(json_path.open()))

# 3. Write merged tokens to current project

out = pathlib.Path("skills/diagram-design/references/style-guide.md")
out.write_text("\n".join(f"--{k}: {v}" for k, v in tokens.items()))
print("✅ Design tokens extracted to", out)

```

After extraction, verify the results using the built-in checklist:

```bash
python3 scripts/self_check.py skills/diagram-design/references/style-guide.md

```

This confirms that required semantic roles (`paper`, `ink`, `accent`, `muted`, `link`) are present and that SVG output will honor the imported palette.

## Key Files in the Extraction Process

- **[`skills/diagram-design/SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/SKILL.md)** (lines 27-31): Describes onboarding options and the design-system token flow, including the prompt for "extract from an installed skill"
- **[`skills/diagram-design/references/onboarding.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/onboarding.md)** (lines 286-288): Contains detailed precedence rules for CSS custom properties and JSON token files
- **[`skills/diagram-design/references/style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/style-guide.md)**: The single source-of-truth for design tokens that gets overwritten with extracted values
- **[`scripts/self_check.py`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/self_check.py)**: Executes the pre-output checklist to verify token integration with the SVG generator

## Summary

- Diagram Design extracts design tokens through a **declarative onboarding workflow** that reads static files without executing foreign code
- The process prioritizes **CSS custom properties** and **JSON token files** over prose definitions in [`references/style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/references/style-guide.md)
- Extracted tokens overwrite the default palette (white-smoke paper, jet-black ink, atomic-tangerine accent) in the current project's style guide
- The [`scripts/self_check.py`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/self_check.py) validation ensures SVG output compliance with the imported design system
- All source file paths are located within the `skills/diagram-design/` directory structure

## Frequently Asked Questions

### How does Diagram Design locate design tokens in an installed skill?

Diagram Design looks for the [`references/style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/references/style-guide.md) file inside the installed skill's directory structure. This file serves as the canonical location where color, typography, and spacing tokens are defined according to the repository's conventions.

### What token formats does Diagram Design support during extraction?

The extraction mechanism supports **CSS custom properties** (e.g., `--paper:#f5f5f5`), **JSON token files** (which take precedence), and prose patterns following "semantic-role = value" syntax. The precedence rules ensure structured formats override plain text definitions.

### Is the extraction process safe to run on third-party skills?

Yes, the process is completely **declarative** and safe. Diagram Design only reads static token definitions from [`style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md) and JSON files without executing any code from the source skill, preventing malicious code execution while importing design values.

### How can I verify that tokens were extracted correctly?

Run the built-in validation script: `python3 scripts/self_check.py skills/diagram-design/references/style-guide.md`. This checks that all required semantic roles (`paper`, `ink`, `accent`, `muted`, `link`) are present and confirms that generated SVGs will comply with the imported design system rules.