How to Create a Custom Hallmark Theme with OKLCH Colors

You create a custom Hallmark theme by generating an OKLCH color palette as CSS custom properties under a [data-theme="custom"] selector, then referencing these tokens exclusively throughout your codebase to pass the slop-test validation gates.

The Nutlope/hallmark repository provides a dual-path theming system that supports both a default catalog of 20 pre-defined themes and a custom route for bespoke branding. Creating a custom Hallmark theme with OKLCH colors requires strict adherence to token-based architecture, where all color values derive from CSS custom properties defined in OKLCH format rather than inline hex or RGB values.

Understanding Hallmark's Theme Architecture

Hallmark distinguishes between two theme routes according to skills/hallmark/references/custom-theme.md. The catalog route provides pre-built palettes, while the custom route constructs a one-off OKLCH palette tuned to your specific brief. The custom route activates when your design brief signals a brand color or requires a bespoke palette, triggering the token-generation workflow described in the signal detection section of the custom theme reference.

Step-by-Step Guide to Creating a Custom OKLCH Theme

Step 1: Trigger the Custom Theme Branch

Activate the custom theme workflow by indicating a brand color requirement in your project brief. According to skills/hallmark/references/custom-theme.md, this signal detection shifts the system from catalog selection to palette generation mode.

Step 2: Define Your Anchor Colour

Supply an anchor color as a hex code, OKLCH string, or named color (e.g., "terracotta"). Hallmark converts this to OKLCH and uses it as the foundation for your accent tokens. The anchor color selection determines the hue family for your entire custom palette.

Step 3: Generate the OKLCH Palette

Hallmark constructs a full token set following the OKLCH-only policy from skills/hallmark/references/color.md.

• Paper tokens: Lightness values between 96–98% L with slight hue tint
• Accent tokens: Chroma capped at 5% to maintain color discipline
• Neutral tints: Derived from the same OKLCH scale without using pure #000 or #fff

Step 4: Declare Tokens in CSS

Create or edit site/css/tokens.css and declare your palette under a [data-theme="custom"] selector. The following example demonstrates the proper token structure:

/* site/css/tokens.css */
[data-theme="custom"] {
  --color-paper: oklch(97% 0.02 220);
  --color-surface: oklch(92% 0.03 220);
  --color-accent: oklch(55% 0.07 180);
  --color-ink: oklch(18% 0.01 220);
}

For a concrete implementation, examine site/examples/custom-05/tokens.css in the repository, which shows a complete working example of custom OKLCH token definitions.

Step 5: Reference Tokens Consistently

All color declarations must use the custom properties (var(--color-accent), var(--color-paper), etc.). According to skills/hallmark/references/anti-patterns.md, inline OKLCH or hex values constitute mid-render improvisation and trigger gate 48 failures during validation. Never use raw color values in your markup or stylesheets.

Step 6: Validate with Slop-Test Gates

Run the automatic slop-test gates to verify your palette. Hallmark checks for:

• APCA and WCAG contrast ratios between text and background tokens
• Token discipline ensuring all colors reference custom properties
• Missing token detection for incomplete palettes

Adjust your OKLCH lightness or chroma values if any gate reports failures.

Step 7: Stamp the Build

The first line of your generated CSS must contain a Hallmark stamp comment recording theme metadata. According to skills/hallmark/SKILL.md, use this format:

/* Hallmark · macrostructure: modern-minimal · tone: warm · anchor hue: 30 */

This stamp persists in the output and informs future theme runs.

Complete OKLCH Token Implementation

When implementing your custom theme, follow this complete token structure referencing the site/examples/custom-05/tokens.css pattern:

/* site/css/tokens.css */
[data-theme="custom"] {
  /* Paper – light, neutral backgrounds */
  --color-paper: oklch(97% 0.01 250);
  
  /* Surface – cards and elevated surfaces */
  --color-surface: oklch(90% 0.02 250);
  
  /* Accent – brand color, chroma capped at 5% */
  --color-accent: oklch(55% 0.05 30);
  
  /* Ink – text and content colors */
  --color-ink: oklch(20% 0.01 250);
}

Consuming Custom Tokens in Your Application

Reference your OKLCH tokens in HTML using the var() function:

<section class="hero" style="background: var(--color-paper); color: var(--color-ink);">
  <h1 style="color: var(--color-accent);">Welcome to our brand</h1>
</section>

In your CSS, maintain token discipline by always using custom properties:

.button {
  background: var(--color-accent);
  color: var(--color-paper);
  border: 1px solid var(--color-ink);
}

Switching Themes at Runtime

Activate your custom theme by setting the data attribute on the document root:

// site/js/main.js
document.documentElement.dataset.theme = 'custom';

This JavaScript implementation applies the [data-theme="custom"] selector and renders your OKLCH palette.

Summary

• Hallmark supports custom themes through a strict OKLCH token system defined in skills/hallmark/references/custom-theme.md
• Paper tokens require 96–98% lightness, while accent chroma remains capped at 5% per skills/hallmark/references/color.md
• Declare all colors in site/css/tokens.css under [data-theme="custom"] selectors
• Reference tokens exclusively with var() to avoid gate 48 failures from skills/hallmark/references/anti-patterns.md
• Validate palettes through automatic APCA/WCAG contrast checks
• Stamp builds with metadata comments as specified in skills/hallmark/SKILL.md

Frequently Asked Questions

Why does Hallmark require OKLCH instead of hex or RGB?

OKLCH provides perceptual uniformity that hex and RGB cannot match, ensuring that your custom Hallmark theme maintains consistent lightness and chroma relationships across different hues. The skills/hallmark/references/color.md specification mandates OKLCH-only to prevent accessibility issues and visual discontinuities that arise from non-perceptual color spaces.

What happens if I use inline colors instead of CSS tokens?

Using inline hex, RGB, or OKLCH values triggers gate 48 in the slop-test validation system, rejecting your build as a mid-render improvisation. You must reference all colors through var(--color-*) tokens declared in your site/css/tokens.css file to pass validation.

How do I switch between the catalog and custom theme routes?

The custom route activates automatically when your brief signals a brand color requirement, while the catalog route presents 20 pre-defined options. You can force the custom route by providing an anchor color (hex, OKLCH string, or named color) in your configuration, which triggers the bespoke palette generation workflow described in skills/hallmark/references/custom-theme.md.

Can I mix pure black or white in my OKLCH custom theme?

No. The Hallmark system prohibits pure #000 or #fff values even in OKLCH format. According to the color discipline rules, neutral tints must derive from your anchor hue with low chroma values, ensuring your custom theme maintains chromatic coherence without harsh absolute neutrals.

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