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

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 (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. Here's a complete custom theme example:

/* 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:

.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 (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. 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 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 (line 117), implements this heuristic:

// 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 (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 (line 154).

Configuration Pattern

// 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	OKLCH-only rule and perceptual rationale
site/css/tokens.css	Actual OKLCH custom properties for all themes
skills/hallmark/SKILL.md	Locked-token discipline and theme dispatch
skills/hallmark/references/custom-theme.md	Bespoke palette construction workflow
skills/hallmark/references/slop-test.md	OKLCH lightness contrast pre-checks
skills/hallmark/references/anti-patterns.md	Prohibition of inline color values
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
• 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 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 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 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 (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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}