# How OKLCH Powers Hallmark's Color System: The Complete Technical Guide

> Discover how OKLCH powers Hallmark's color system. Learn how this perceptually uniform space ensures consistent color, hue shifts, and accessibility.

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

---

**OKLCH serves as the single source of truth for all color decisions in Hallmark, replacing traditional RGB and HSL with a perceptually uniform color space that ensures consistent lightness, predictable hue shifts, and robust accessibility across every theme.**

Hallmark's design system enforces strict OKLCH discipline from palette creation through final export. This article examines how the `Nutlope/hallmark` repository implements OKLCH as its foundational color model, with direct references to source files, token architecture, and validation rules that maintain visual consistency at scale.

## Why Hallmark Rejects RGB, HSL, and Hex

Hallmark's color philosophy centers on **perceptual uniformity**. While `rgb()`, `hsl()`, and hex values remain common in CSS, they produce uneven lightness shifts when adjusting saturation or hue. OKLCH (Lightness, Chroma, Hue in the Oklab color space) solves this by mapping colors to how humans actually perceive them.

The rule is absolute: only OKLCH values are permitted. The color reference file at [`skills/hallmark/references/color.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/color.md) (line 7) documents this prohibition explicitly. Any designer or developer attempting to introduce alternative color formats triggers validation failures.

This rejection of traditional formats delivers three concrete benefits:

- **Predictable lightness**: Adjusting chroma without shifting perceived brightness
- **Consistent hue**: Maintaining hue integrity across the lightness range
- **Reliable contrast calculations**: Using the L channel for accessibility pre-checks

## The Token-Based Architecture

Colors never appear as raw values in Hallmark components. Instead, the system stores **OKLCH values as CSS custom properties** (design tokens) on `:root` or under `[data-theme="..."]` attributes.

### Token Structure in tokens.css

The source of truth lives in [`site/css/tokens.css`](https://github.com/Nutlope/hallmark/blob/main/site/css/tokens.css). Here's a complete custom theme example:

```css
/* Custom theme anchored on "sea-blue" */
[data-theme="custom"] {
  /* ── Colour (OKLCH) ──────────────────────────── */
  --color-paper:   oklch(96% 0    210);  /* light neutral */
  --color-ink:     oklch(18% 0    210);  /* dark text */
  --color-accent:  oklch(55% 0.12 210);  /* brand accent */
  --color-muted:   oklch(80% 0.04 210);
}

```

Each component consumes these tokens exclusively:

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

.cta-button {
  background: var(--color-accent);
  color: var(--color-paper);
}

```

The anti-patterns guide at [`skills/hallmark/references/anti-patterns.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/anti-patterns.md) (line 239) reinforces this discipline, explicitly warning against hard-coding any color values outside the token system.

## Theme Generation: Catalog and Custom Workflows

Hallmark ships with **20 pre-built catalog themes**, each defined as a complete OKLCH palette in [`site/css/tokens.css`](https://github.com/Nutlope/hallmark/blob/main/site/css/tokens.css). Every theme occupies its own `[data-theme="..."]` block—search for the *Cobalt* theme as a reference implementation.

### Custom Theme Construction

When brands require bespoke palettes, Hallmark's custom-theme flow builds a **one-off OKLCH palette** anchored on a brand-provided color. The process is documented in [`skills/hallmark/references/custom-theme.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/custom-theme.md) under "OKLCH palette discipline":

1. Extract the OKLCH values from the brand's reference color
2. Derive a complete tonal range by adjusting L (lightness) and C (chroma) while holding H (hue) constant
3. Assign semantic roles: paper, ink, accent, muted, etc.
4. Lock the tokens for production use

This anchored approach ensures brand colors maintain perceptual relationships regardless of where they appear in the UI hierarchy.

## Contrast Validation with OKLCH Lightness

Hallmark's accessibility pipeline uses OKLCH's **L channel for rapid contrast pre-checks**. The slop-test suite, defined in [`skills/hallmark/references/slop-test.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/slop-test.md) (line 117), implements this heuristic:

```javascript
// Fast contrast pre-check using OKLCH lightness
function hasAdequateContrast(textL, bgL, threshold = 0.5) {
  return Math.abs(textL - bgL) >= threshold; // 50% difference minimum
}

// Example: text on paper
const textL = 0.18;  // --color-ink
const bgL = 0.96;    // --color-paper
const passes = Math.abs(textL - bgL) >= 0.5; // true

```

If `|L_text − L_bg| < 50%`, the combination likely fails accessibility standards. Full **WCAG/APCA validation** follows only for combinations that pass this lightweight screen.

## Token Locking and Immutability

Once a theme is selected, **locked tokens prevent any mid-render improvisation**. The "Locked tokens" section in [`skills/hallmark/SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md) (line 50) defines this enforcement:

- All color references must use `var(--color-*)` tokens
- Any stray OKLCH, hex, or rgb value outside defined tokens triggers build failure
- Runtime color manipulation is prohibited

This immutability guarantee ensures that design system decisions persist through production, preventing drift that often undermines visual consistency in large codebases.

## Tailwind v4 Export Pipeline

Hallmark's build system reads OKLCH custom properties and automatically generates Tailwind utilities. The export format is documented in [`skills/hallmark/references/export-formats.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/export-formats.md) (line 154).

### Configuration Pattern

```javascript
// tailwind.config.js
module.exports = {
  content: ['./site/**/*.html', './site/**/*.js'],
  theme: {
    extend: {
      // Tailwind reads @theme block from tokens.css
    },
  },
  plugins: [
    require('@tailwindcss/theme')({
      // @theme block lives in site/css/tokens.css
    }),
  ],
}

```

The plugin extracts OKLCH values and generates utilities like `bg-paper`, `text-ink`, `bg-accent`, preserving the perceptual benefits through the entire toolchain.

## Core Implementation Files

| File | Purpose |
|------|---------|
| [`skills/hallmark/references/color.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/color.md) | OKLCH-only rule and perceptual rationale |
| [`site/css/tokens.css`](https://github.com/Nutlope/hallmark/blob/main/site/css/tokens.css) | Actual OKLCH custom properties for all themes |
| [`skills/hallmark/SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md) | Locked-token discipline and theme dispatch |
| [`skills/hallmark/references/custom-theme.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/custom-theme.md) | Bespoke palette construction workflow |
| [`skills/hallmark/references/slop-test.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/slop-test.md) | OKLCH lightness contrast pre-checks |
| [`skills/hallmark/references/anti-patterns.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/anti-patterns.md) | Prohibition of inline color values |
| [`skills/hallmark/references/export-formats.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/export-formats.md) | Tailwind and design-token export specs |

## Summary

- **OKLCH is mandatory**: Hallmark rejects RGB, HSL, and hex in favor of perceptual uniformity
- **Tokens centralize control**: All colors live as CSS custom properties in [`site/css/tokens.css`](https://github.com/Nutlope/hallmark/blob/main/site/css/tokens.css)
- **Themes are OKLCH palettes**: 20 catalog themes plus custom workflows anchored on brand colors
- **Lightness drives accessibility**: The L channel enables fast contrast pre-checks before full WCAG/APCA validation
- **Locked tokens prevent drift**: Immutability rules in [`SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/SKILL.md) enforce systematic color usage
- **Export preserves benefits**: Tailwind v4 integration maintains OKLCH through the build pipeline

## Frequently Asked Questions

### What makes OKLCH better than HSL for design systems?

OKLCH separates lightness (L) from chroma (C) and hue (H) in a perceptually uniform way. In HSL, changing saturation affects perceived brightness, making consistent theming difficult. OKLCH's L channel remains stable when adjusting C, enabling predictable tint and shade generation that Hallmark exploits for its token architecture.

### Can I use hex colors in Hallmark if I convert them to OKLCH first?

Yes, but only as an input step. Hallmark's custom-theme workflow accepts brand colors in any format, immediately converts them to OKLCH, and then locks the resulting tokens. The prohibition in [`color.md`](https://github.com/Nutlope/hallmark/blob/main/color.md) applies to authored code, not the conversion pipeline. No hex values survive into production CSS.

### How does Hallmark handle OKLCH browser support?

According to the source implementation, Hallmark targets modern browsers where OKLCH enjoys full support. The token architecture in [`site/css/tokens.css`](https://github.com/Nutlope/hallmark/blob/main/site/css/tokens.css) uses raw OKLCH syntax without fallbacks, indicating a baseline requirement of 2022+ browser versions. Projects requiring legacy support would need preprocessing outside Hallmark's core system.

### What happens if I accidentally use a non-token color in Hallmark?

The slop-test suite and build pipeline flag violations immediately. As documented in [`SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/SKILL.md) (line 50), any OKLCH, hex, or rgb value that isn't a defined `--color-*` token triggers a failure. This enforcement ensures the locked-token guarantee holds across all contributions, preventing the gradual degradation common in less strict systems.