# How Hallmark Decides When to Use Custom Themes vs Catalog Themes: A Technical Deep Dive

> Discover how Hallmark automatically selects custom vs catalog themes using a signal-detection protocol. Learn the technical factors driving theme choice for your brand.

- Repository: [Hassan El Mghari/hallmark](https://github.com/Nutlope/hallmark)
- Tags: deep-dive
- Published: 2026-08-04

---

**Hallmark automatically chooses between custom themes and catalog themes through a signal-detection protocol in [`skills/hallmark/SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md) that scans the brief for explicit requests, brand colors, multi-attribute aesthetics, or bespoke structure—offering the custom route only when signals are detected, defaulting silently to the 20-theme catalog otherwise.**

Hallmark is an AI design skill by [Nutlope/hallmark](https://github.com/Nutlope/hallmark) that generates opinionated web pages. A core architectural decision in its design flow is **when to use a custom theme** (a one-off OKLCH palette with free-font pairing) versus a **catalog theme** (one of 20 pre-crafted named themes like Lumen, Cobalt, or Hum). This decision isn't arbitrary—it follows a strict, signal-driven protocol encoded directly in the source.

## The Five-Step Theme Decision Protocol

Hallmark's theme selection runs through a deterministic five-step flow defined across [`SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/SKILL.md) and [`custom-theme.md`](https://github.com/Nutlope/hallmark/blob/main/custom-theme.md):

| Step | Action | Source Location |
|------|--------|---------------|
| **0 — Pre-flight** | Scans project for existing design tokens, font stacks, motion libraries | [`SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/SKILL.md) — "Pre-flight scan" |
| **1 — Signal Detection** | Searches brief for custom-theme signals; if found, **offers** custom route | [`custom-theme.md`](https://github.com/Nutlope/hallmark/blob/main/custom-theme.md) — "When to surface this fork" |
| **2 — User Confirmation** | Asks single follow-up: *"Custom palette or stay on catalog?"* (default: catalog) | [`custom-theme.md`](https://github.com/Nutlope/hallmark/blob/main/custom-theme.md) — follow-up logic |
| **3 — Theme Route** | Custom → build tuned palette per [`custom-theme.md`](https://github.com/Nutlope/hallmark/blob/main/custom-theme.md); Catalog → pick from 20 themes | [`custom-theme.md`](https://github.com/Nutlope/hallmark/blob/main/custom-theme.md) + [`SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/SKILL.md) |
| **4 — Diversification** | New page must differ on ≥1 axis (paper band, display style, accent hue) from previous build | [`SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/SKILL.md) — "Theme-diversification rule" |
| **5 — Build & Slop-Test** | Emits page, runs 58-gate quality test; revises if any gate fails | [`SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/SKILL.md) + [`slop-test.md`](https://github.com/Nutlope/hallmark/blob/main/slop-test.md) |

This protocol ensures that **catalog themes remain the silent default**, while custom themes require intentional activation.

## Custom Theme Signals: When Hallmark Offers the Fork

Hallmark only surfaces the custom-theme option when the brief contains at least one of four signal types. These are defined in [`skills/hallmark/references/custom-theme.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/custom-theme.md) — "When to surface this fork – Step 1 trigger signals":

### 1. Explicit Custom Request

Phrases like *"I want a custom theme"*, *"make it ours"*, or *"play with the colors"* trigger immediate branch switching.

### 2. Named Brand Color

Hex codes, OKLCH values, or descriptive colors (*"our terracotta"*) signal that a tuned palette anchored to that color is needed.

```javascript
// Signal detection pseudocode from the source analysis
function hasCustomSignal(brief) {
  const colour = /#([0-9a-f]{3}|[0-9a-f]{6})\b|(?:rgb|hsl|oklch)\s*\(/i.test(brief);
  // ... additional signal checks
}

```

### 3. Multi-Attribute Aesthetic

Complex mood descriptions (*"moss, lichen, soft pink, herbal"* or *"late-night, neon, brutalist deli"*) indicate no single catalog theme matches. The regex `/(\w+,?\s*){3,}/` combined with catalog-theme exclusion helps detect these.

### 4. Bespoke Structural Request

Phrases like *"no theme"*, *"build from scratch"*, *"art-direct it"*, or *"a ticket-shaped page"* activate **bespoke depth**: Hallmark designs palette, typography, **and** page structure from first principles rather than applying a theme template.

If **none** of these signals appear, Hallmark never mentions the fork and silently proceeds with catalog selection.

## Catalog Theme Selection: The Default Path

When no custom signals are detected, Hallmark executes the catalog route defined in [`SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/SKILL.md):

1. Selects one of 20 named themes (Lumen, Cobalt, Hum, etc.)
2. Loads its token block from [`site/css/tokens.css`](https://github.com/Nutlope/hallmark/blob/main/site/css/tokens.css)
3. Applies the theme's signature moves per its reference file (e.g., [`skills/hallmark/references/themes/lumen.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/themes/lumen.md))

The catalog themes are **pre-audited**—each has a markdown reference defining its palette drops, visual language, and anti-patterns. This guarantees predictable, high-quality output without user friction.

## The Diversification Rule: Preventing Repetitive Output

Regardless of which route is taken, Hallmark enforces **theme diversification** across consecutive builds. As implemented in [`SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/SKILL.md):

- The new page must differ on **at least one of three axes**: paper band, display style, or accent hue
- Custom runs record their axes in [`.hallmark/log.json`](https://github.com/Nutlope/hallmark/blob/main/.hallmark/log.json) so the rule works across both custom and catalog routes

This prevents the "catalog-theme-only drift" common in design generators, ensuring visual variety even when the same brief is built repeatedly.

## Unified Quality Standards: The 58-Gate Slop Test

Both routes must pass identical quality gates. Per [`SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/SKILL.md) — "Pre-emit self-critique" and [`slop-test.md`](https://github.com/Nutlope/hallmark/blob/main/slop-test.md):

- **No invented metrics**, **no italic headers**, **token-only colors**
- Accessibility requirements
- Structural coherence

The freedom of custom palette construction never compromises core anti-slop constraints. Custom themes are tuned, not unconstrained.

## Programmatic Theme Selection

For testing or scripted workflows, you can force the custom route:

```bash

# Default — signal detection determines route

npx skills add nutlope/hallmark

# Force custom theme, bypassing signal detection

npx skills add nutlope/hallmark --theme custom

```

The `--theme custom` flag jumps directly to [`custom-theme.md`](https://github.com/Nutlope/hallmark/blob/main/custom-theme.md) protocol. Without this flag, signal detection governs the decision.

## Custom Theme Output Format

When Hallmark generates a custom theme, it stamps the CSS with provenance metadata per [`custom-theme.md`](https://github.com/Nutlope/hallmark/blob/main/custom-theme.md) — "§ E · Stamp format":

```css
/* Hallmark · macrostructure: Long Document · H5 hero knobs: salutation=time-stamp, body=2 paragraphs, signoff=initials
 * theme: custom · vibe: "archival warmth, hand-set, no varnish"
 * paper: oklch(94% 0.020 65) · accent: oklch(58% 0.16 35)
 * display: Fraunces italic · body: Source Serif 4
 * axes: light / italic-serif / chromatic-terracotta
 * studied: no · context: explicit · v0.8.0
 */

```

This stamp enables traceability, versioning, and diversification tracking across builds.

## Summary

- **Signal-driven architecture**: Hallmark inspects briefs for explicit requests, brand colors, multi-attribute moods, or bespoke structure before offering custom themes
- **Silent catalog default**: No signals means automatic catalog selection—no user friction, no decision fatigue
- **Single-question confirmation**: When signals fire, one follow-up confirms the route; default remains catalog
- **Unified quality gates**: Both routes pass the same 58-gate slop test, ensuring custom freedom never degrades output quality
- **Diversification enforcement**: [`.hallmark/log.json`](https://github.com/Nutlope/hallmark/blob/main/.hallmark/log.json) records build axes, guaranteeing visual variety across runs

## Frequently Asked Questions

### What happens if I mention a color but don't explicitly ask for a custom theme?

Hallmark treats named brand colors as **custom-theme signals** per [`custom-theme.md`](https://github.com/Nutlope/hallmark/blob/main/custom-theme.md). It will offer the custom route with a single follow-up question, defaulting to catalog if you decline. The color detection uses regex matching for hex codes, OKLCH/RGB/HSL functions, and descriptive color names.

### Can I force Hallmark to use a specific catalog theme instead of auto-selecting?

The source protocol in [`SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/SKILL.md) does not expose direct catalog theme selection in the standard flow. Catalog themes are chosen automatically based on diversification rules and brief compatibility. For precise control, use the custom route and specify your desired palette and typography explicitly.

### Where does Hallmark store the history of previous themes for diversification?

Build history is recorded in [`.hallmark/log.json`](https://github.com/Nutlope/hallmark/blob/main/.hallmark/log.json) at the project root. This file stores macrostructure, theme type (custom or catalog name), and computed axes (paper band, display style, accent hue). The diversification rule consults this log before each build to ensure the new page differs on at least one axis—per [`SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/SKILL.md) and [`custom-theme.md`](https://github.com/Nutlope/hallmark/blob/main/custom-theme.md) "Axis computation" sections.