Overview

If primitives are "what colors exist", semantic tokens are "what those colors mean". Instead of painting a button as bg-gray-900, you paint it as bg-primary, and the meaning of "primary" changes when the theme changes.

This is layer 2 of 3: it consumes primitives and is what components (and the chart layer) consume in turn. The full picture lives in the three-layer model.

Intent as the interface

All the chrome of Gremorie components talks to the semantic layer. It defines a fixed set of intents, background, foreground, primary, border, ring, and so on, that every theme must fill.

Seven themes, two modes

Gremorie ships seven themes. The Default theme is the base layer itself; five match the visual voice of the leading AI products, and Purple is a violet theme for reading products, adapted from the Fumadocs Purple preset:

Each theme ships light and dark independently. Switching is a single attribute change:

<html data-theme="claude">
  <!-- Claude, light -->
</html>
<html data-theme="gemini" class="dark">
  <!-- Gemini, dark -->
</html>

Components do not know which theme is active. They ask for bg-primary, and the browser resolves var(--primary) in the right context.

How the tokens are defined

The source is DTCG JSON in packages/tokens/tokens/ (semantic/light.json, semantic/dark.json, themes/<id>.json), which generates packages/tokens/styles/theme.css (:root for light, .dark for dark) and themes/<id>.css. Each named theme is an override file that remaps only what differs, naming primitives by their token path:

{
  "light": {
    "primary": { "$type": "color", "$value": "{color.orange.600}" },
    "primary-foreground": { "$type": "color", "$value": "{color.gray.950}" },
    "accent": { "$type": "color", "$value": "{color.orange.100}" }
  }
}

The build writes each alias as a reference to the primitive, so the generated CSS keeps the cascade:

:root[data-theme='mistral'] {
  --primary: var(--color-orange-600);
  --primary-foreground: var(--color-gray-950);
  --accent: var(--color-orange-100);
  /* ... */
}

The consequence: adjust --color-orange-600 in the primitive layer and the Mistral theme, along with any other theme referencing orange-600, updates automatically. Edit once, it cascades. Tokens a theme does not override resolve to the base layer, so an accent theme like Mistral stays a dozen lines while a full-surface theme like Claude remaps almost everything.

For the full table

The Colors page has the intent-to-value mapping (light and dark) for the seven themes. Use it to understand why a button turns clay in one theme and emerald in another, and to audit whether your own custom theme is filling the intents with consistent values.