# Which CSS Properties Are Mapped to Diagram Tokens During Onboarding?

> Discover which CSS properties map to diagram tokens during onboarding in the Diagram Design engine. Understand how background color, color, and custom properties drive diagram visuals.

- Repository: [Cathryn Lavery/diagram-design](https://github.com/cathrynlavery/diagram-design)
- Tags: deep-dive
- Published: 2026-08-21

---

**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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md).

Consider the following CSS custom properties in your source:

```css
: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`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md):

```markdown
| 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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md)** (generated) — Stores the resulting token definitions that drive all diagram renders.
- **[`scripts/self_check.py`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/self_check.py)** — Utility script that runs onboarding checks and validates token extraction.
- **[`scripts/mermaid_extract.py`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/mermaid_extract.py)** and **[`drawio_extract.py`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/mermaid_extract.py) and [`drawio_extract.py`](https://github.com/cathrynlavery/diagram-design/blob/main/drawio_extract.py), ensuring consistent styling across all outputs.