How Diagram Design Extracts Design Tokens from an Existing Agent Skill

Diagram Design extracts design tokens by reading the source skill's 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 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 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, overwriting the default palette described in 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 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 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:

instabase skill onboard diagram-design

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

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:

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 (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 (lines 286-288): Contains detailed precedence rules for CSS custom properties and JSON token files
• 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: 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
• 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 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 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 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.

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