How Hallmark's OKLCH System Ensures Accessibility: A Technical Deep Dive

Hallmark's design system guarantees accessible colour contrast by combining OKLCH colour space with APCA (Accessible Perceptual Contrast Algorithm) validation in its token architecture.

The Nutlope/hallmark repository demonstrates how modern CSS colour spaces can bake accessibility directly into design tokens. By anchoring every UI colour in OKLCH—a perceptually uniform colour space—and enforcing APCA contrast checks at the token level, Hallmark eliminates accessibility gaps before components reach production.

Why OKLCH Over Traditional Colour Spaces

OKLCH represents colours using three perceptually meaningful dimensions: L (lightness), C (chroma), and H (hue). Unlike RGB or HSL, OKLCH lightness is uniform across hues, making contrast calculations predictable.

In site/examples/wayfare/tokens.css, base tokens are defined as pure OKLCH values:

:root {
  --color-paper: oklch(13% 0.010 60);
  --color-ink-0: oklch(98% 0.002 60);
  --color-ink-1: oklch(78% 0.040 70);
  --color-ink-2: oklch(57% 0.075 70);
}

This structure enables precise manipulation of lightness without chroma drift—a critical property for maintaining accessible contrast ratios across theme variations.

APCA Validation in Token Definitions

Hallmark's OKLCH accessibility system embeds contrast verification directly in CSS comments. The site/examples/press-01/tokens.css file contains explicit APCA annotations:

--color-accent-ink: oklch(97% 0.012 30); /* bone text on red fill — APCA-checked */
--color-accent-fill: oklch(50% 0.190 30); /* 🔴 riso red */
--color-muted-ink: oklch(55% 0.050 30); /* APCA ≥ 45:1 on paper */

These inline notes serve as both documentation and enforcement mechanism. Designers cannot commit tokens without confirming APCA compliance, creating a self-auditing pipeline.

Dynamic Colour Mixing Preserves Perceptual Contrast

The system uses color-mix() with OKLCH interpolation to generate state variations. In site/examples/tally/styles.css, hover and focus states preserve lightness relationships:

.tag {
  border-color: color-mix(in oklch, var(--color-ink-0) 16%, transparent);
}

.tag:hover {
  background: color-mix(in oklch, var(--color-fill) 8%, transparent);
}

The in oklch modifier ensures that mixing operations respect perceptual uniformity. A 16% opacity reduction in OKLCH maintains predictable lightness, whereas HSL opacity shifts can produce non-linear contrast changes that fail accessibility thresholds.

Focus Ring Specifications for Keyboard Navigation

Hallmark's OKLCH accessibility strategy includes dedicated focus tokens tuned to APCA minimums. From site/examples/riso-01/tokens.css:

--color-focus: oklch(48% 0.170 220); /* darker cyan — AA-contrast focus ring (≥ 3:1) */

This token guarantees Lc ≈ 90 against underlying surfaces, meeting WCAG 2.2 requirements for focus indicators. The OKLCH definition allows the focus colour to adapt across themes while maintaining minimum contrast.

Design-Time Verification Workflow

Repository documentation in skills/hallmark/references/typography.md formalizes the colour-token workflow. Every token must pass APCA verification before commit, integrating accessibility into the design system governance.

This workflow differs from post-hoc auditing: contrast validation happens at token creation, not during component testing. The OKLCH foundation makes these predictions reliable—designers can calculate final contrast mathematically without browser inspection.

Practical Implementation Example

A complete accessible component using Hallmark's OKLCH system:

/* 1. Define APCA-validated tokens */
:root {
  --color-primary: oklch(66% 0.235 25);
  --color-primary-ink: oklch(97% 0.012 30); /* APCA-checked */
  --color-focus: oklch(48% 0.170 220); /* ≥ 3:1 contrast guarantee */
}

/* 2. Component with preserved contrast states */
.button {
  background: var(--color-primary);
  color: var(--color-primary-ink);
}

.button:hover {
  /* Lightness reduces to 56.1% (66% × 0.85), preserving chroma/hue */
  background: color-mix(in oklch, var(--color-primary) 85%, transparent);
}

.button:focus-visible {
  outline: 2px solid var(--color-focus);
  outline-offset: 2px;
}

Summary

Hallmark's OKLCH accessibility system achieves reliable contrast through four architectural decisions:

• OKLCH token foundation — perceptually uniform colour definitions in site/examples/wayfare/tokens.css
• APCA inline validation — contrast annotations enforcing minimum thresholds at design time
• color-mix(in oklch, ...) interpolation — state variations that preserve lightness relationships
• Dedicated focus tokens — guaranteed ≥ 3:1 contrast for keyboard navigation in site/examples/riso-01/tokens.css

Frequently Asked Questions

What makes OKLCH better than HSL for accessibility?

OKLCH lightness is perceptually uniform—reducing L by 10% produces the same visual darkening regardless of hue. HSL lightness varies by hue (yellow appears lighter than blue at identical L values), making contrast calculations unpredictable. Hallmark's OKLCH system eliminates this variance.

How does APCA differ from WCAG 2.0 contrast ratios?

APCA calculates perceptual contrast using modern colour science, weighting spatial frequency and text size. It replaces the outdated WCAG 2.0 formula that treated all colours mathematically rather than perceptually. Hallmark's token comments reference APCA specifically, as seen in site/examples/press-01/tokens.css.

Can OKLCH colours fail accessibility requirements?

Yes—OKLCH enables precise control but doesn't guarantee compliance. Hallmark's mandatory APCA verification step catches non-compliant combinations before commit. The colour space is a tool; the workflow enforces standards.

Does color-mix() affect APCA compliance?

When using in oklch interpolation, color-mix() preserves predictable lightness relationships, making APCA outcomes calculable. Other colour spaces or interpolation methods can produce mixtures with unexpected contrast results.

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