How to Extract Design Tokens from a Local Folder Using Diagram Design

Diagram Design extracts color palettes and typography from local design-system folders through an 8-step onboarding flow that scans JSON and Markdown files, maps them to semantic roles, and updates the central style guide.

Diagram Design, an open-source diagramming skill maintained in the cathrynlavery/diagram-design repository, enables teams to import design tokens directly from existing design-system directories. This eliminates manual color configuration by automatically parsing CSS, JSON, and Markdown files from your local filesystem. Learning how to extract design tokens from a local folder ensures every diagram inherits your brand's exact color and typography specifications.

Initiating Folder-Based Onboarding

The extraction process begins through the interactive onboarding flow defined in [references/onboarding.md](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/onboarding.md). This workflow connects your local design-system repository to Diagram Design's rendering engine.

Selecting the Local Folder Option

When the skill is first invoked, the system presents several onboarding sources. Choose (c) Extract from a local folder / design-system directory to trigger the folder-scanning logic. This option instructs Diagram Design to bypass default templates and instead pull tokens from your specified directory.

Specifying the Directory Path

After selecting the folder option, supply the absolute path to your design-system root directory (for example, ~/projects/brand-design/). The skill validates this path before initiating the recursive scan.

Scanning and Parsing Token Files

Diagram Design performs a targeted glob operation to locate token definitions without manually indexing every file.

Recursive File Discovery (3-Level Glob)

The system scans the supplied directory recursively to a maximum depth of three levels, searching for specific token file patterns. According to the onboarding implementation detailed in [SKILL.md](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/SKILL.md), the glob logic targets:

• tokens.json, design-tokens.json, *.tokens.json — Style Dictionary and Figma-compatible JSON files
• style-guide.md, *design*.md — Narrative design documentation containing color and font definitions

Supported File Formats and Specifications

Once discovered, files are parsed according to their format:

• JSON token files are validated against the Design Tokens Specification (e.g., { "color": { "primary": { "value": "#eb6c36" } } })
• Markdown files are scanned for hex color literals and typographic family declarations embedded in documentation

Token Mapping and Style Guide Generation

Raw extracted values must be transformed into Diagram Design's internal semantic model before they can be applied to diagrams.

Semantic Role Mapping

Extracted values are mapped onto Diagram Design's semantic roles as defined in [references/style-guide.md](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/style-guide.md). These roles include:

• paper — Background colors
• ink — Primary text colors
• accent — Highlight and call-to-action colors
• muted — Secondary or disabled state colors
• link — Hyperlink and interactive element colors

Updating the Central Style Guide

The skill overwrites or creates references/style-guide.md with the newly extracted token values. This file serves as the single source of truth for all subsequent diagram generation. Once rewritten, every future diagram automatically inherits the custom skin without requiring additional imports.

Persisting Profile Configurations

After successful token import, Diagram Design prompts you to save the current style-guide state as a named client profile (see [references/profiles.md](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/profiles.md)). This creates a reusable snapshot in ~/.diagram-design/profiles/, allowing you to switch between brand identities across different projects without repeating the folder extraction process.

Automating Extraction Programmatically

For CI/CD pipelines or automated workflows, you can trigger the extraction using Python helper scripts or command-line invocations.

Python Implementation

Run the following from the repository root to programmatically process a folder:

import subprocess

folder_path = "/home/user/projects/brand-design/"

# Invoke the onboarding flow for local folders

subprocess.run([
    "python3", "scripts/onboard_folder.py",
    "--folder", folder_path
])

The script executes the full pipeline: globbing for token files, parsing according to the Design Tokens Specification, rewriting skills/diagram-design/references/style-guide.md, and optionally generating a profile in ~/.diagram-design/profiles/.

Chat-Ops Command Syntax

If Diagram Design is exposed as a slash command in your chat environment:

/diagram-design:onboard --folder /home/user/projects/brand-design/

Resulting Style Guide Format

After extraction, references/style-guide.md contains mapped values ready for diagram rendering:

paper: "#ffffff"
ink:   "#2d3142"
accent: "#eb6c36"
muted: "#7a8399"
link:  "#2e5aa8"

Summary

• Entry Point: Select option (c) in the onboarding flow defined in references/onboarding.md to extract from local folders
• Discovery: Recursive glob scans up to 3 levels deep for *.tokens.json, tokens.json, design-tokens.json, and Markdown design files
• Parsing: JSON files follow the Design Tokens Specification; Markdown files are scanned for hex codes and font families
• Mapping: Raw values map to semantic roles (paper, ink, accent, muted, link) documented in references/style-guide.md
• Persistence: The process updates references/style-guide.md and optionally saves reusable profiles per references/profiles.md
• Automation: Use scripts/onboard_folder.py for programmatic extraction in build pipelines

Frequently Asked Questions

What file patterns does Diagram Design recognize during extraction?

Diagram Design searches for tokens.json, design-tokens.json, *.tokens.json (JSON files following the Design Tokens Specification), and style-guide.md or *design*.md (Markdown documentation) within the specified folder. The scan operates recursively to a maximum depth of three directory levels as implemented in the onboarding logic.

How does Diagram Design handle conflicting token definitions?

When multiple files contain definitions for the same semantic role (such as accent or ink), the extraction process maps values according to the parsing order defined in the onboarding workflow. The final values written to references/style-guide.md reflect the last processed occurrence, though the specific precedence rules depend on the glob result ordering in scripts/onboard_folder.py.

Can I extract tokens from a folder without overwriting existing profiles?

Yes. The extraction process updates references/style-guide.md immediately, but saving the result as a named profile is optional. When prompted after successful extraction, you may decline to create a profile, keeping the updated style-guide active only for the current session without persisting it to ~/.diagram-design/profiles/.

What is the maximum folder depth scanned during token extraction?

Diagram Design scans up to three levels deep from the specified root directory. This limitation balances comprehensive discovery against performance overhead, ensuring that nested node_modules or deep build directories do not trigger excessive file operations during the onboarding process described in references/onboarding.md.

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