# How to Create a Custom Hallmark Theme with OKLCH Colors > Learn to create a custom Hallmark theme using OKLCH colors. Generate a CSS custom properties palette and use tokens for seamless integration and validation. - Repository: [Hassan El Mghari/hallmark](https://github.com/Nutlope/hallmark) - Tags: how-to-guide - Published: 2026-07-13 --- **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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/site/css/tokens.css) and declare your palette under a `[data-theme="custom"]` selector. The following example demonstrates the proper token structure: ```css /* 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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md), use this format: ```css /* 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`](https://github.com/Nutlope/hallmark/blob/main/site/examples/custom-05/tokens.css) pattern: ```css /* 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: ```html

Welcome to our brand

``` In your CSS, maintain token discipline by always using custom properties: ```css .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: ```javascript // 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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/color.md) - Declare all colors in [`site/css/tokens.css`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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.