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

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) 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 【line 20】:

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 【line 177】:

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.

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
• 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 【line 344】:

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

/* 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 【line 461】, 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:

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 【line 251】. This keeps simple briefs fast while reserving the custom path for brand-sensitive work.

Summary

• Signal detection in 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. 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, styles.css, and script.js demonstrating the stamp format, OKLCH variable system, and font loading in practice.

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