# How Hallmark Handles Custom Themes for Unique Briefs: Complete Technical Guide

> Learn how Hallmark handles custom themes for unique briefs. Discover its technical process for generating bespoke color palettes and font pairings while maintaining design constraints.

- Repository: [Hassan El Mghari/hallmark](https://github.com/Nutlope/hallmark)
- Tags: how-to-guide
- Published: 2026-08-07

---

**Hallmark detects requests for bespoke branding through explicit signals in user briefs, then routes to a dedicated branch that generates one-off OKLCH color palettes and custom font pairings while preserving all design constraints.**

The open-source Hallmark design engine (available at [Nutlope/hallmark](https://github.com/Nutlope/hallmark)) treats **custom themes** as a first-class alternative to its default catalog-based approach. When a brief contains specific brand cues or uniqueness requests, Hallmark quietly diverts from its standard 21-theme rotation to build tailored visual systems from scratch.

## Detecting the Custom-Theme Signal

During **Step 1 (signal detection)**, Hallmark scans user briefs for three categories of triggers defined in [`references/custom-theme.md`](https://github.com/Nutlope/hallmark/blob/main/references/custom-theme.md) 【[line 20]((https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/custom-theme.md#L20))】:

| Trigger Type | Example Phrases |
|-------------|---------------|
| **Explicit uniqueness request** | "custom theme", "tailor it to our brand", "make it ours", "something unique" |
| **Brand color specification** | "our brand colour is teal and beige" |
| **Multi-attribute vibe beyond catalog** | "play around with the colors and fonts" |

If any signal matches, the engine immediately routes to the **custom-theme branch** rather than entering the default catalog selection flow.

## Building the Custom Theme

The custom branch constructs a complete visual system through two parallel operations, as implemented in [`references/custom-theme.md`](https://github.com/Nutlope/hallmark/blob/main/references/custom-theme.md) 【[line 177]((https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/custom-theme.md#L177))】:

### OKLCH Palette Generation

Hallmark derives three **diversification-rule axes** from the brief:

- **Paper hue** — the neutral background temperature
- **Accent hue** — the primary action/emphasis color
- **Vibe** — the overall chroma and lightness relationship

These feed into mathematically valid OKLCH coordinates that respect contrast minimums and color-system constraints from [`references/color.md`](https://github.com/Nutlope/hallmark/blob/main/references/color.md).

### Font Pairing Selection

The engine selects a **free-font combination** (display + body) matching the brief's tone while obeying:

- Legibility rules from [`references/typography.md`](https://github.com/Nutlope/hallmark/blob/main/references/typography.md)
- Loading performance guidelines
- Vibe consistency with the generated palette

## Preview and Approval Flow

Before emitting any CSS, Hallmark presents a **Step 5 preview block** defined in [`SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/SKILL.md) 【[line 344]((https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md#L344))】:

```text
--- Preview: Custom Theme ---
Paper hue (OKLCH): 190.2° 0.12 0.93
Accent hue (OKLCH): 70.5° 0.10 0.75
Display font: Poppins
Body font: Roboto

```

This plain-text checkpoint lets users approve the direction or request adjustments. Rejection triggers fallback to a catalog theme without surfacing the custom branch to the user.

## Recording Custom Themes for Diversification

Every custom theme receives a **stamp comment** as the first line of generated CSS, enabling future de-duplication:

```css
/* Hallmark · macrostructure: hero-enrichment · tone: modern-playful ·
   theme: custom · paper hue: 190.2 · accent hue: 70.5 ·
   display font: Poppins · body font: Roboto */

:root {
  --paper-hue: 190.2;
  --paper-chroma: 0.12;
  --paper-lightness: 0.93;
  --accent-hue: 70.5;
  --accent-chroma: 0.10;
  --accent-lightness: 0.75;
  --font-display: "Poppins", sans-serif;
  --font-body: "Roboto", sans-serif;
}

```

According to [`SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/SKILL.md) 【[line 461]((https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md#L461))】, Hallmark reads this stamp on subsequent runs to ensure diversification rules select different macrostructures or themes for related briefs.

## Complete Example: From Brief to CSS

**Input brief:**

```text
We need a landing page for our new product. Our brand colours are teal (#00A3B0) and beige (#E2D1B3). I'd like something unique that feels modern and playful.

```

**Processing flow:**

1. Signal detection matches "brand colours" + "unique"
2. Custom branch converts hex to OKLCH paper (190.2°) and accent (70.5°) hues
3. Tone matching selects **Poppins** (display) and **Roboto** (body)
4. Preview block presented for approval
5. CSS generated with full stamp and token system

## Fallback to Catalog Themes

When **no custom-theme signal** is detected, Hallmark silently selects from its 21 catalog themes without user awareness, as specified in [`SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/SKILL.md) 【[line 251]((https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md#L251))】. This keeps simple briefs fast while reserving the custom path for brand-sensitive work.

## Summary

- **Signal detection** in [`references/custom-theme.md`](https://github.com/Nutlope/hallmark/blob/main/references/custom-theme.md) triggers the custom branch through explicit brand cues or uniqueness requests
- **Palette construction** generates OKLCH systems from diversification-rule axes, not simple color swaps
- **Font pairing** obeys typography constraints while matching brief tone
- **Preview approval** at Step 5 prevents unwanted custom themes from reaching production
- **Stamp comments** enable diversification tracking across multiple briefs
- **Silent catalog fallback** maintains simplicity for standard requests

## Frequently Asked Questions

### How does Hallmark convert brand hex colors to OKLCH values?

Hallmap extracts hue angles from provided hex codes, then derives chroma and lightness mathematically to satisfy contrast requirements in [`references/color.md`](https://github.com/Nutlope/hallmark/blob/main/references/color.md). The resulting OKLCH coordinates preserve the brand identity while ensuring accessibility compliance.

### Can users reject a custom theme after seeing the preview?

Yes. The Step 5 preview block is a hard checkpoint. If rejected, Hallmark falls back to catalog theme selection without exposing the custom branch logic to the end user.

### What happens if a brief has weak custom-theme signals?

Ambiguous signals route to the default catalog flow. Hallmark prioritizes predictable output over speculative custom generation—only definitive brand cues or explicit uniqueness requests trigger the custom branch.

### Where can I see a complete custom-theme implementation?

The `site/examples/custom-02/` directory contains a full working example including [`tokens.css`](https://github.com/Nutlope/hallmark/blob/main/tokens.css), [`styles.css`](https://github.com/Nutlope/hallmark/blob/main/styles.css), and [`script.js`](https://github.com/Nutlope/hallmark/blob/main/script.js) demonstrating the stamp format, OKLCH variable system, and font loading in practice.