# Why Hallmark Uses Token-Based CSS and Forbids Inline OKLCH: A Deep Dive

> Discover why Hallmark uses token-based CSS and forbids inline OKLCH for design consistency, effortless theming, and preventing visual drift across 24 themes. Learn more.

- Repository: [Hassan El Mghari/hallmark](https://github.com/Nutlope/hallmark)
- Tags: deep-dive
- Published: 2026-08-01

---

**Hallmark enforces token-based CSS and bans inline OKLCH values to guarantee design consistency, enable one-touch theming, and prevent visual drift across its 24-theme system.**

Hallmark's styling architecture revolves around **design tokens** — CSS custom properties that centralize color, typography, spacing, and other visual primitives. Every theme imports a shared token file where the color palette is defined using the perceptually-uniform **OKLCH** color space. This strict token-based approach with no inline values is a deliberate architectural choice baked into the codebase.

## How Hallmark's Token System Works

At the core of every Hallmark theme lies a [`tokens.css`](https://github.com/Nutlope/hallmark/blob/main/tokens.css) file. This file defines all visual primitives using OKLCH values, which components reference exclusively through CSS variables.

### Token Definition in [`site/css/tokens.css`](https://github.com/Nutlope/hallmark/blob/main/site/css/tokens.css)

The central token file establishes the OKLCH color space as the foundation for all 24 themes:

```css
/* Twenty-four themes. Each occupies a distinct point in OKLCH space. */
[data-theme="midnight"] {
  --color-paper:    oklch(15%  0.022 250);
  --color-paper-2:  oklch(20%  0.024 250);
  --color-paper-3:  oklch(25%  0.026 250);
  /* ... additional tokens */
}

```

As noted in [`site/css/tokens.css`](https://github.com/Nutlope/hallmark/blob/main/site/css/tokens.css) lines 2-4, each theme "occupies a distinct point in OKLCH space," ensuring perceptually meaningful color relationships across the entire system.

### Token Consumption in Component Styles

Component stylesheets never contain raw color values. Instead, they import the token file and reference variables:

```css
/* styles.css – imports the token file and references the variable */
@import url("./tokens.css");

.hero {
  background-color: var(--color-paper);
  color: var(--color-ink);
}

```

This pattern appears throughout Hallmark's example themes, such as in [`site/examples/riso-01/styles.css`](https://github.com/Nutlope/hallmark/blob/main/site/examples/riso-01/styles.css).

## The "No Inline Values" Rule

The prohibition against inline OKLCH is explicitly documented. In [`site/examples/riso-01/tokens.css`](https://github.com/Nutlope/hallmark/blob/main/site/examples/riso-01/tokens.css) lines 6-7, a comment states:

> "Every colour + font in styles.css references a token here. **No inline values**."

This comment serves as both documentation and enforcement mechanism — any deviation from the token system would violate this stated rule.

### What Constitutes a Violation

The following pattern is **forbidden** in Hallmark's codebase:

```css
/* ❌ This is prohibited – it bypasses the token system */
.bad-example {
  background-color: oklch(96% 0.018 80); /* Inline OKLCH – not allowed */
}

```

Even though the value uses OKLCH — the correct color space — its inline placement violates the architectural constraint.

## Three Reasons Hallmark Forbids Inline OKLCH

### 1. Consistency and Theming

**Token-based CSS guarantees unified visual language.** When every component references `--color-paper` rather than hard-coding `oklch(15% 0.022 250)`, a single file change propagates system-wide. This enables:

- Instant theme switching via `data-theme` attribute
- Guaranteed color harmony across all components
- Predictable maintenance patterns

### 2. Design Fidelity Through OKLCH

**OKLCH is chosen for its perceptual uniformity.** Unlike RGB or HSL, OKLCH maps directly to human color perception, allowing precise control over:

- **Lightness (L)** — perceptually uniform brightness
- **Chroma (C)** — color intensity independent of hue
- **Hue (H)** — angle in OKLCH color wheel

By centralizing OKLCH definitions in token files, Hallmark ensures these perceptual relationships remain intact across all 24 themes.

### 3. Prevention of Ad-hoc Styling

**Inline values create visual drift and audit failures.** Hard-coded colors:

- Bypass theme switching mechanisms
- Complicate design system audits
- Introduce inconsistencies that accumulate over time

Hallmark's strict token enforcement also supports automated quality checks, including detection of AI-generated artifacts that might introduce inline styling.

## Key Implementation Files

| File | Purpose |
|------|---------|
| [`site/css/tokens.css`](https://github.com/Nutlope/hallmark/blob/main/site/css/tokens.css) | Central OKLCH token definitions for base themes |
| [`site/examples/riso-01/tokens.css`](https://github.com/Nutlope/hallmark/blob/main/site/examples/riso-01/tokens.css) | Per-theme token customization with "No inline values" rule |
| [`site/examples/riso-01/styles.css`](https://github.com/Nutlope/hallmark/blob/main/site/examples/riso-01/styles.css) | Component styles using `var()` references only |
| [`README.md`](https://github.com/Nutlope/hallmark/blob/main/README.md) | Design intent: "Twenty-four themes... each occupies a distinct point in OKLCH space" |

## Summary

- **Token-based CSS** centralizes all OKLCH color definitions in shared [`tokens.css`](https://github.com/Nutlope/hallmark/blob/main/tokens.css) files
- **Inline OKLCH prohibition** prevents hard-coded colors that would break theming
- **OKLCH color space** provides perceptual uniformity for precise palette crafting
- **Explicit documentation** in [`tokens.css`](https://github.com/Nutlope/hallmark/blob/main/tokens.css) comments enforces the architectural rule
- **24-theme system** relies on this discipline for reliable, switchable visual identities

## Frequently Asked Questions

### Why does Hallmark use OKLCH instead of HSL or RGB?

OKLCH offers perceptual uniformity — its lightness component matches human vision, and chroma remains consistent across hues. This allows Hallmark to define "distinct points in OKLCH space" for each of its 24 themes with predictable visual relationships. RGB and HSL produce uneven perceptual steps that complicate systematic palette generation.

### Can I use OKLCH values anywhere in Hallmark?

Only within token definition files. OKLCH values must appear exclusively in [`tokens.css`](https://github.com/Nutlope/hallmark/blob/main/tokens.css) files where design tokens are established. Component stylesheets must reference these tokens via `var(--token-name)` and cannot contain inline OKLCH literals, even if the values match existing tokens exactly.

### What happens if I add an inline OKLCH value?

The change would violate the documented "No inline values" rule from [`site/examples/riso-01/tokens.css`](https://github.com/Nutlope/hallmark/blob/main/site/examples/riso-01/tokens.css). This creates technical debt: the color won't respond to theme switching, complicates design audits, and may trigger automated quality checks. The codebase architecture assumes all colors flow through the token system.

### How does token-based CSS improve maintainability?

Centralized tokens enable one-touch updates — changing `--color-paper` in a single file updates every component using that variable. This eliminates find-and-replace operations across dozens of stylesheets and guarantees that related colors (paper variants, ink colors) remain harmonized through their shared token definitions.