Which CSS Properties Are Mapped to Diagram Tokens During Onboarding?

During the onboarding flow, the Diagram Design engine extracts specific CSS properties—including background-color, color, and custom properties like --accent—and maps them to semantic tokens (paper, ink, accent, rule, etc.) that drive all generated diagrams.

The cathrynlavery/diagram-design repository automates visual style extraction during its onboarding process. When you run the onboarding command against a URL, skill, or local folder, the system inspects computed styles and CSS custom properties to build a standardized set of design tokens. Understanding which CSS properties are mapped to diagram tokens during onboarding allows you to prepare your stylesheets for seamless integration.

Extracting Tokens from Live Websites

When onboarding from a live URL, the engine renders the page and inspects the computed stylesheet of the DOM. It assigns the most relevant CSS values to semantic token roles based on element selectors and visual dominance.

Surface and Color Mappings

The following computed CSS properties are extracted directly from the rendered page:

• background-color of the <body> element (or the dominant large region) maps to the paper token, defining the base canvas color.
• color of the body text maps to the ink token, representing the primary text color.
• Secondary text colors (captions, meta information) map to the muted token for low-priority text.
• Brand colors (extracted from CTA buttons, links, or heading accents) map to the accent token.
• Background colors of cards or containers slightly darker than the base paper map to paper-2, creating a secondary surface.
• Border or hairline colors are converted to rgba(ink, ~0.12) and assigned to the rule token for dividers.

These mappings are defined in skills/diagram-design/references/onboarding.md (lines 66-74) and are applied after colors are extracted from the page’s CSS or a screenshot-based color histogram.

Mapping CSS Custom Properties from Local Files

When the source is an installed skill or a local design-system folder, the onboarding engine prioritizes CSS custom properties (--*). It applies heuristic name-matching to determine which token role each property populates.

Heuristic Pattern Matching

The engine scans for the following naming patterns in your CSS:

CSS Custom Property Pattern	Mapped Token Role
background, bg, paper, surface, canvas	paper
foreground, text, body, ink, on-surface	ink
muted, subtle, secondary, caption	muted
accent, brand, primary, cta, highlight	accent
border, rule, divider, outline	rule
mono, code, pre	sublabel (monospace font for technical labels)

Explicit token files (e.g., tokens.json) are also respected, but CSS custom properties take priority when both exist. This logic is documented in skills/diagram-design/references/onboarding.md (lines 25-36).

Font Family Extraction

Typography tokens are derived from specific CSS selectors rather than custom properties. The onboarding flow extracts font-family values from the following elements:

• <h1> selectors map to the title token (heading font).
• <body> selectors map to the node-name token (body text font).
• <code> or <pre> selectors map to the sublabel token (monospace font).

If a --mono style custom property is present in the stylesheet, it overrides the code element extraction for the sublabel font assignment. See skills/diagram-design/references/onboarding.md (lines 79-84) for the complete font extraction specification.

Onboarding Command and Token Generation

When you execute the onboarding command (onboard diagram-design from <source>), the engine reads the identified CSS properties, applies the heuristic tables, and injects the resulting values into style-guide.md.

Consider the following CSS custom properties in your source:

:root {
  --background: #f8f6f0;   /* → paper */
  --foreground: #111111;   /* → ink */
  --muted:      #6b6b68;   /* → muted */
  --accent:     #c73a2b;   /* → accent */
  --border:     #e0e0e0;   /* → rule */
  --mono:       "Geist Mono", monospace; /* → sublabel font */
}

The onboarding process automatically generates the following token block in style-guide.md:

| Token | Value |
|------|-------|
| paper   | #f8f6f0 |
| ink     | #111111 |
| muted   | #6b6b68 |
| accent  | #c73a2b |
| rule    | #e0e0e0 |
| sublabel| "Geist Mono", monospace |

These definitions become the foundation for all subsequent diagram renders in the project.

Key Source Files

The following files define how CSS properties are interpreted as diagram tokens:

• skills/diagram-design/references/onboarding.md — Contains the complete description of the onboarding flow, including CSS-to-token heuristics and mapping logic.
• style-guide.md (generated) — Stores the resulting token definitions that drive all diagram renders.
• scripts/self_check.py — Utility script that runs onboarding checks and validates token extraction.
• scripts/mermaid_extract.py and drawio_extract.py — Downstream parsers that consume the tokens for Mermaid and Draw.io diagram generation.

Summary

• Computed styles from live URLs map background-color to paper, color to ink, and brand elements to accent.
• CSS custom properties are matched heuristically; patterns like --bg, --ink, or --accent automatically populate their respective token roles.
• Typography is extracted from <h1>, <body>, and <code> selectors, with --mono properties overriding monospace detection.
• The onboard diagram-design from <source> command writes the final tokens to style-guide.md, which powers all future diagram generation.

Frequently Asked Questions

How does the onboarding engine decide which CSS custom property to use for the paper token?

The engine scans for patterns like background, bg, paper, surface, or canvas in the property name. The first match found in the computed styles or custom properties is assigned to the paper token. If no custom property matches, it falls back to the computed background-color of the <body> element.

Can I override the automatic color extraction with explicit values?

Yes. While the engine prioritizes CSS custom properties, you can provide an explicit tokens.json file in your design-system folder. However, CSS custom properties take precedence when both exist, so ensure your --* variables are removed or renamed if you want tokens.json values to apply.

What happens if my stylesheet does not define a --mono or code block font?

If no --mono custom property is detected and no <code> or <pre> elements are found in the inspected source, the sublabel token defaults to the system monospace stack. The onboarding process completes successfully even if typography tokens are partially extracted.

Where are the extracted tokens stored after onboarding completes?

The finalized tokens are written to style-guide.md in the project root. This file serves as the single source of truth for all diagram generation scripts, including mermaid_extract.py and drawio_extract.py, ensuring consistent styling across all outputs.

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