# How Tokens Are Used for Theming in Diagram Design

> Explore how Diagram Design uses CSS custom-property tokens for theming. Dynamically restyle entire diagrams by swapping token blocks, not individual elements.

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

---

**TLDR: Diagram Design implements theming through CSS custom-property tokens defined in `:root` blocks — each theme assigns semantic values like colors, fonts, and spacing, and every diagram element references those tokens via `var()`, so swapping the entire token block restyles the whole diagram without touching individual components.**

The **cathrynlavery/diagram-design** repository uses a token-driven theming architecture to give diagram examples a consistent, easily swappable visual style. Instead of hard-coding colors and fonts into individual elements, the project defines semantic CSS variables — called **tokens** — and references them throughout the markup. This approach powers every diagram-skills example in the repo and makes adding new themes as simple as redefining one `:root` block.

## The Token Architecture Behind Diagram Design Theming

Tokens in Diagram Design are CSS custom properties declared inside `:root`. Each token has a semantic name — like `--color-paper` or `--color-ink` — rather than a descriptive color name like `--white` or `--gray`. This abstraction is the key: markup never sees literal hex values, only the semantic reference.

According to the source files in `skills/diagram-design/assets/`, each theme is a complete set of tokens covering **colors, fonts, and by extension any future design value** (spacing, borders, shadows, etc.). The repository ships two documented themes — dark and light — that share the same token names but different values.

## Dark Theme Token Definitions

The dark theme declaration lives in **[`skills/diagram-design/assets/example-high-level-dark.html`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/assets/example-high-level-dark.html)**. It declares the full palette and font stack as custom properties:

```html
<style>
  :root {
    --color-paper:  #2d3142;
    --color-ink:    #f5f5f5;
    --color-muted:  #bfc0c0;
    --color-accent: #f08a59;
    --font-sans:    'Geist', system-ui, sans-serif;
    --font-serif:   'Instrument Serif', serif;
    --font-mono:    'Geist Mono', ui-monospace, monospace;
  }
</style>

```

Notice the semantic intent: **paper** is the background, **ink** is the primary text color, **muted** is secondary text, and **accent** highlights important diagram elements. The font tokens give you sans, serif, and mono stacks in one place.

## Light Theme Token Definitions

The companion light theme is defined in [`skills/diagram-design/assets/example-high-level.html`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/assets/example-high-level.html) with a complementary palette reusing the same token names:

```html
<style>
  :root {
    --color-paper:  #f5f5f5;
    --color-ink:    #2d3142;
    --color-muted:  #4f5d75;
    --color-accent: #eb6c36;
    /* same font tokens as above */
  }
</style>

```

The font tokens (`--font-sans`, `--font-serif`, `--font-mono`) are identical across themes, so typography stays consistent. Only the color tokens change — exactly what they are designed for.

## How Tokens Are Referenced in Diagram Markup

Once the tokens are defined at `:root`, the diagram markup and any CSS rules reference them through the `var()` function. This creates a **single source of truth** for all visual styling. From the diagram examples:

```css
body {
  font-family: var(--font-sans);
  background: var(--color-paper);
  color: var(--color-ink);
}
code {
  font-family: var(--font-mono);
}
.muted {
  color: var(--color-muted);
}
.accent {
  color: var(--color-accent);
}

```

In the actual HTML markup, classes apply those rules — no inline color codes anywhere in the diagram structure:

```html
<!-- Diagram markup uses the tokens -->
<div class="node accent">Critical Path</div>
<p class="muted">Metadata about the diagram</p>

```

By keeping colors, fonts, and weights out of the markup, the diagram remains structurally clean while the theme controls all appearance.

## Swapping Themes by Replacing the Token Block

The thematic architecture pays off when you want to change the entire look of a diagram. Since every element depends on the `:root` token values, switching themes is a one-file operation:

```html
<!-- Apply a theme by including its token block -->
<link rel="stylesheet" href="theme-dark.css">   <!-- defines the --color… tokens -->

```

For example, a complete dark theme stylesheet saved as [`theme-dark.css`](https://github.com/cathrynlavery/diagram-design/blob/main/theme-dark.css) looks like this:

```css
/* theme-dark.css (or inline <style>) */
:root {
  --color-paper:  #2d3142;
  --color-ink:    #f5f5f5;
  --color-muted:  #bfc0c0;
  --color-accent: #f08a59;
  --font-sans:    'Geist', system-ui, sans-serif;
  --font-serif:   'Instrument Serif', serif;
  --font-mono:    'Geist Mono', ui-monospace, monospace;
}

/* Component styles */
.node {
  background: var(--color-paper);
  color: var(--color-ink);
  font-family: var(--font-sans);
}
.accent { color: var(--color-accent); }
.muted  { color: var(--color-muted); }

```

Switching to a light theme is as simple as loading [`theme-light.css`](https://github.com/cathrynlavery/diagram-design/blob/main/theme-light.css) (or swapping inline `<style>` blocks) — the same token names resolve to new values and the entire diagram re-themes consistently. This makes it trivial to add additional themes (high-contrast, brand-specific palettes, corporate colors) without touching diagram markup.

### Key Files in This Architecture

- **[`skills/diagram-design/assets/example-high-level-dark.html`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/assets/example-high-level-dark.html)** — dark theme token definitions and usage examples
- **[`skills/diagram-design/assets/example-high-level.html`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/assets/example-high-level.html)** — light theme token definitions and usage examples

These two files illustrate the complete token-theming pattern that powers Diagram Design's flexible styling. Authors creating new diagram examples follow the same contract — define the tokens, reference them with `var()`, and let the theme do the rest.

## Summary

- **Tokens are CSS custom properties** (`--color-*`, `--font-*`) defined in `:root` blocks within each theme.
- **Semantic names over descriptive hex values** — tokens like `--color-paper` and `--color-ink` abstract the actual colors, providing a stable contract.
- **`var()` invocations in markup** connect components to the theme so no hard-coded colors exist in diagram markup.
- **Swapping any `:root` block** restyles the entire diagram consistently at once, making multi-theme support (dark, light, high-contrast, brand palettes) a matter of a single variable redefinition.
- **The reference files** — [`example-high-level-dark.html`](https://github.com/cathrynlavery/diagram-design/blob/main/example-high-level-dark.html) and [`example-high-level.html`](https://github.com/cathrynlavery/diagram-design/blob/main/example-high-level.html) — in `skills/diagram-design/assets/` demonstrate the pattern on real diagram examples.

## Frequently Asked Questions

### Are these tokens just CSS variables?

Yes — Diagram Design standards use native CSS custom properties declared under `:root`. They are read with the `var()` function inside stylesheets and are fully supported in all modern browsers.

### How do I create a new theme, say a high-contrast mode?

Create a new CSS file (or `<style>` block) that redefines every token name — `--color-paper`, `--color-ink`, `--color-muted`, `--color-accent`, and the font tokens — under `:root`. Then load that block instead of the existing theme. Because the markup only references the semantic token names, nothing else needs to change.

### Do I have to define both `--font-sans` and `--font-serif`?

The repository's convention uses all three font tokens (`--font-sans`, `--font-serif`, `--font-mono`) for document consistency. If your diagram only uses one family, you can omit the others — they will fall back gracefully since tokens that are not used won't affect the layout.

### Where can I find the dark and light theme examples in the repo?

Look at [`skills/diagram-design/assets/example-high-level-dark.html`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/assets/example-high-level-dark.html) for the dark theme's token set and usage, and [`skills/diagram-design/assets/example-high-level.html`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/assets/example-high-level.html) for the light theme equivalent. Both files show the full `:root` token block followed by diagram markup that references those tokens.