# How Hallmark's Token System Works with OKLCH Colors: A Complete Architecture Guide > Explore Hallmark's design token architecture and OKLCH color system. Learn how CSS custom properties adapt to themes using data-theme attributes for a seamless visual experience. - Repository: [Hassan El Mghari/hallmark](https://github.com/Nutlope/hallmark) - Tags: architecture - Published: 2026-07-13 --- **Hallmark's design-token architecture stores all visual properties as CSS custom properties in [`site/css/tokens.css`](https://github.com/Nutlope/hallmark/blob/main/site/css/tokens.css), using exclusively OKLCH color values (`oklch(L% C H)`) that adapt to themes via `data-theme` attributes on the HTML element.** The Hallmark project (Nutlope/hallmark) implements a strict, perceptually-uniform color system that treats OKLCH values as first-class design tokens. Every hue, tint, and shade is defined as a CSS custom property in a centralized token file, enabling consistent theming across the entire application without inline color values. ## Centralized Token Definitions in tokens.css According to the source code, [`site/css/tokens.css`](https://github.com/Nutlope/hallmark/blob/main/site/css/tokens.css) serves as the single source of truth for all visual values. The file contains a global `:root` block declaring default tokens, followed by theme-specific override blocks targeting `[data-theme="..."]` selectors. ### OKLCH Color Declaration Syntax Hallmark enforces that all color tokens use the OKLCH color model. This provides perceptually-uniform control over **lightness**, **chroma**, and **hue**—ensuring that color adjustments appear consistent to human eyes regardless of the hue angle. Example from the `specimen` theme: ```css [data-theme="specimen"] { --color-paper: oklch(96% 0.018 80); --color-paper-2: oklch(93% 0.020 80); --color-paper-3: oklch(89% 0.022 75); --color-rule: oklch(82% 0.014 75); --color-ink: oklch(18% 0.014 60); --color-accent: #FC4C02; /* fallback hex for legacy support */ --color-accent-ink: oklch(55% 0.21 32); } ``` ### Theme Override Architecture Each catalog theme defines its own OKLCH coordinates within a scoped selector. When `data-theme="cobalt"` is applied to the HTML element, the browser resolves token values from the matching block, instantly shifting the entire palette while maintaining semantic relationships (e.g., paper remains lighter than ink). ## The Locked Tokens Enforcement Rule As documented in [`skills/hallmark/SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md), the project enforces "locked tokens"—a strict design discipline prohibiting inline color values. Component CSS must reference tokens via `var(--color-*)` and cannot contain raw `oklch()` or hex literals. The [`skills/hallmark/references/anti-patterns.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/anti-patterns.md) file specifically forbids **Mid-render token improvisation**, which occurs when developers write inline OKLCH values instead of using the token system. This rule ensures that [`site/css/tokens.css`](https://github.com/Nutlope/hallmark/blob/main/site/css/tokens.css) remains the exclusive source of color truth. ## Consuming Tokens in Component CSS Components never hardcode colors. Instead, they import the token file and reference semantic variables: ```css @import url("./tokens.css"); .button { background-color: var(--color-accent); color: var(--color-accent-ink); border: 1px solid var(--color-rule); } ``` This abstraction allows the same component to render in the warm `specimen` theme or the technical `cobalt` theme without code changes, as the token values resolve differently based on the active theme attribute. ## Runtime Theme Switching Themes activate by setting the `data-theme` attribute on the `` element: ```html ``` The browser automatically recalculates all `var()` references against the new `[data-theme="cobalt"]` block in [`tokens.css`](https://github.com/Nutlope/hallmark/blob/main/tokens.css), providing instantaneous theme switching without JavaScript color manipulation. ## Summary - **Hallmark's token system** stores all colors as CSS custom properties in [`site/css/tokens.css`](https://github.com/Nutlope/hallmark/blob/main/site/css/tokens.css) - **OKLCH color model** (`oklch(L% C H)`) ensures perceptually-uniform lightness and chroma control - **Theme overrides** use `[data-theme="..."]` selectors to replace default token values - **Locked tokens rule** in [`SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/SKILL.md) prohibits inline colors, enforcing `var(--token)` usage exclusively - **Component abstraction** allows automatic theme adaptation via CSS variable resolution ## Frequently Asked Questions ### Why does Hallmark use OKLCH instead of HEX or RGB for color tokens? OKLCH provides perceptually-uniform color spacing, meaning that changing the lightness value produces the same visual difference regardless of hue angle. This allows Hallmark's token system to create harmonious, predictable color palettes where semantic relationships (like paper vs. ink) remain consistent across different themes. ### How does the locked tokens rule prevent unauthorized color values? The rule documented in [`skills/hallmark/SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md) requires that every color or font-family declaration reference a CSS custom property. Any stray `oklch()`, hex literal, or `rgb()` value triggers a slop-test failure during development, forcing developers to move the color definition into [`site/css/tokens.css`](https://github.com/Nutlope/hallmark/blob/main/site/css/tokens.css) and reference it via `var(--color-name)`. ### Can I use fallback hex values alongside OKLCH in Hallmark tokens? While the system prefers pure OKLCH values, the source code shows that legacy hex fallbacks are permitted for specific use cases (such as `--color-accent: #FC4C02` in the specimen theme). However, the primary color workflow expects `oklch(L% C H)` syntax to maximize the perceptual advantages of the color space. ### How do I add a new theme to Hallmark's token system? Create a new `[data-theme="your-theme"]` block in [`site/css/tokens.css`](https://github.com/Nutlope/hallmark/blob/main/site/css/tokens.css) containing OKLCH color definitions for all required tokens (paper, ink, accent, etc.). Reference the [`skills/hallmark/references/themes/cobalt.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/themes/cobalt.md) file for implementation patterns, then activate the theme by setting `data-theme="your-theme"` on the HTML element.