# Choosing Custom Hallmark Themes vs. Catalog Themes: A Complete Decision Guide

> Decide between custom Hallmark themes and catalog themes. Understand when each is best for your project based on design brief signals, brand colors, and structural needs.

- Repository: [Hassan El Mghari/hallmark](https://github.com/Nutlope/hallmark)
- Tags: best-practices
- Published: 2026-08-01

---

**Hallmark automatically routes every project to either a custom theme or a catalog theme based on signal detection in your design brief, with custom themes triggered only by explicit requests, brand colors, complex aesthetics, or structural demands.**

Choosing between custom Hallmark themes versus catalog themes determines your entire design workflow. The **Nutlope/hallmark** framework handles this decision through an automated protocol that inspects your brief before any visual work begins, ensuring you get the right level of design flexibility without unnecessary friction.

## How Hallmark Decides: The 5-Step Signal Protocol

Hallmark's routing logic lives in [[`skills/hallmark/SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md)](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md) and executes automatically on every project. Understanding this flow helps you craft briefs that trigger the correct path.

### Step 0: Pre-Flight Scan

Before theme selection, Hallmark analyzes your project for existing design tokens, font stacks, and motion libraries. This scan reports findings to you but does not influence the route—the actual decision happens in Step 1.

### Step 1: Signal Detection (The Critical Fork)

The [[`custom-theme.md`](https://github.com/Nutlope/hallmark/blob/main/custom-theme.md)](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/custom-theme.md) reference defines how Hallmark detects custom-theme signals. If **any** signal fires, Hallmark offers the custom route; otherwise, it silently proceeds with catalog selection.

### Steps 2-5: Confirmation, Building, and Validation

- **Step 2**: Single follow-up question when signals detected ("custom palette or catalog?")
- **Step 3**: Execute custom protocol or load catalog token block from [`site/css/tokens.css`](https://github.com/Nutlope/hallmark/blob/main/site/css/tokens.css)
- **Step 4**: Apply diversification rule (new page must differ on paper band, display style, or accent hue)
- **Step 5**: Run 58-gate slop-test; revise until all gates pass

## When to Use a Custom Hallmark Theme

A custom theme is appropriate **only** when your brief contains specific signals. According to [[`custom-theme.md`](https://github.com/Nutlope/hallmark/blob/main/custom-theme.md)](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/custom-theme.md), these are the four trigger categories:

| Signal Category | Example Phrasing | Hallmark Response |
|-----------------|------------------|-------------------|
| **Explicit theme request** | "I want a custom theme," "make it ours," "play with the colors" | Switches to custom branch; asks one-line vibe question |
| **Named brand color** | "Our brand red is #c0392b," "use our terracotta" | Treats color as anchor; constructs tuned OKLCH palette |
| **Multi-attribute aesthetic** | "moss, lichen, soft pink, herbal," "late-night, neon, brutalist deli" | Detects catalog mismatch; offers custom route |
| **Bespoke structural request** | "No theme—build from scratch," "art-direct it," "ticket-shaped page" | Enters *bespoke depth*: designs palette, typography, **and** page structure from first principles |

The pseudologic for signal detection follows this pattern:

```js
// From SKILL.md Step 1 implementation
function hasCustomSignal(brief) {
  const explicit = /\b(custom|tailored|unique|palette)\b/i.test(brief);
  const colour   = /#([0-9a-f]{3}|[0-9a-f]{6})\b|(?:rgb|hsl|oklch)\s*\(/i.test(brief);
  const vibe     = /(\w+,?\s*){3,}/.test(brief) && !/^(warm|technical|playful)$/i.test(brief);
  const structure= /\b(no theme|bespoke|from scratch|art‑direct)\b/i.test(brief);
  return explicit || colour || vibe || structure;
}

```

If **none** of these patterns match, Hallmark never mentions custom themes and automatically selects from the 20-theme catalog.

## When to Use a Catalog Theme

The **catalog route is the default** and handles the majority of briefs. Use a catalog theme when:

- Your brief contains **no custom-theme signals**
- You want **fast, predictable results** without design exploration
- Your project benefits from **tested, named aesthetics** (Lumen, Cobalt, Hum, etc.)

Each catalog theme has a dedicated reference file in [`skills/hallmark/references/themes/`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/themes/lumen.md) defining its signature moves, palette drops, and visual language. Themes load their token blocks from [[`site/css/tokens.css`](https://github.com/Nutlope/hallmark/blob/main/site/css/tokens.css)](https://github.com/Nutlope/hallmark/blob/main/site/css/tokens.css).

## Custom Theme Architecture: What Changes Under the Hood

### Palette Construction

Custom themes use **OKLCH color space** with free-font pairings. The palette is tuned to your specific inputs rather than pulled from predefined token blocks.

### Structure Flexibility

Catalog themes apply consistent macrostructures. Custom themes—especially at **bespoke depth**—can redesign page architecture from first principles.

### Persistent Logging

Custom runs record their diversification axes in [`.hallmark/log.json`](https://github.com/Nutlope/hallmark/blob/main/.hallmark/log.json), enabling the diversification rule to work across both custom and catalog projects.

### Verification Equality

Both routes must pass the **58-gate slop-test** defined in [[`slop-test.md`](https://github.com/Nutlope/hallmark/blob/main/slop-test.md)](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/slop-test.md). Custom palette freedom never compromises core constraints: no invented metrics, no italic headers, token-only colors, accessibility requirements, and more.

## Practical Examples: Triggering Each Route

### Force Custom Theme (CLI Testing)

```bash

# Default behavior—silent catalog selection

npx skills add nutlope/hallmark

# Force custom path, bypassing signal detection

npx skills add nutlope/hallmark --theme custom

```

The `--theme custom` flag jumps directly to the custom-theme protocol in [`custom-theme.md`](https://github.com/Nutlope/hallmark/blob/main/custom-theme.md).

### Custom Theme Output Stamp

All custom themes generate a machine- and human-readable stamp comment:

```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 format is specified in [[`custom-theme.md`](https://github.com/Nutlope/hallmark/blob/main/custom-theme.md)](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/custom-theme.md) §E.

## Key Design Principles Behind the Decision Model

| Principle | Implementation | Benefit |
|-----------|---------------|---------|
| **Signal-first design** | Brief inspection before theme commitment | Respects creator intent; avoids premature constraints |
| **Single-question confirmation** | One follow-up when signals fire | Preserves "quiet custom branch"; minimal friction |
| **Diversification across runs** | Axis tracking in [`.hallmark/log.json`](https://github.com/Nutlope/hallmark/blob/main/.hallmark/log.json) | Prevents repetitive outputs even with identical briefs |
| **Unified quality gates** | Same 58-gate slop-test for both routes | Custom freedom without quality degradation |

## Summary

- **Custom themes** trigger only on explicit signals: direct requests, brand colors, complex multi-word aesthetics, or bespoke structural demands
- **Catalog themes** are the silent default for all other briefs, drawing from 20 pre-crafted options
- The decision engine lives in [`SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/SKILL.md) (flow control) and [`custom-theme.md`](https://github.com/Nutlope/hallmark/blob/main/custom-theme.md) (signal definitions)
- Both routes enforce diversification rules and identical quality gates
- Force custom selection with `--theme custom` CLI flag when testing

## Frequently Asked Questions

### What happens if my brief accidentally contains a custom-theme signal?

Hallmark will surface the one-line follow-up: "Do you want a custom palette (custom) or stay on the catalog?" The default selection is catalog, so accidental triggers never force you into custom work without explicit confirmation.

### Can I convert a catalog theme project to custom mid-process?

No—the route is determined at **Step 1** before design work begins. To switch, you must restart with a new brief containing stronger custom signals or use the `--theme custom` CLI override.

### How does Hallmark ensure custom themes don't look like catalog themes?

The **diversification rule** requires every new page to differ on at least one of three axes (paper band, display style, accent hue) from previous Hallmark outputs. Custom runs log their axes to [`.hallmark/log.json`](https://github.com/Nutlope/hallmark/blob/main/.hallmark/log.json), making this comparison possible across both route types.

### Are custom themes slower to generate than catalog themes?

Yes—custom themes require palette construction or bespoke structural design, plus the same 58-gate verification. Catalog themes load pre-defined token blocks and macrostructures. The trade-off is customization depth versus generation speed.