How Hallmark's Token System Works with OKLCH Colors: A Complete Architecture Guide
Hallmark's design-token architecture stores all visual properties as CSS custom properties in 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 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:
[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, 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 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 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:
@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 <html> element:
<html data-theme="cobalt">
<!-- All OKLCH colors now resolve to the cobalt palette -->
</html>
The browser automatically recalculates all var() references against the new [data-theme="cobalt"] block in 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 - 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.mdprohibits inline colors, enforcingvar(--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 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 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 containing OKLCH color definitions for all required tokens (paper, ink, accent, etc.). Reference the skills/hallmark/references/themes/cobalt.md file for implementation patterns, then activate the theme by setting data-theme="your-theme" on the HTML element.
Have a question about this repo?
These articles cover the highlights, but your codebase questions are specific. Give your agent direct access to the source. Share this with your agent to get started:
curl -s "https://instagit.com/install.md" 
Maintain an open-source project? Get it listed too →