How Tokens Are Used for Theming in Diagram Design

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. It declares the full palette and font stack as custom properties:

<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 with a complementary palette reusing the same token names:

<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:

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:

<!-- 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:

<!-- 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 looks like this:

/* 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 (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 — dark theme token definitions and usage examples
• 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 and 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 for the dark theme's token set and usage, and 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.

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