# Hallmark Catalog Themes vs. Custom Theme Branch: What's the Difference?

> Understand the difference between Hallmark catalog themes and custom theme branches. Learn how pre-defined themes rotate automatically while custom branches create unique palettes based on creative intent.

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

---

**Hallmark catalog themes are 20 pre-defined visual systems that rotate automatically, while the custom-theme branch generates made-to-measure palettes and font pairings when a brief signals creative intent.**

The [Nutlope/hallmark](https://github.com/Nutlope/hallmark) design engine routes every brief through one of two distinct theme pathways. Understanding this architecture helps you predict when Hallmark will apply a ready-made theme versus building a bespoke visual system from scratch.

---

## What Are Hallmark Catalog Themes?

**Catalog themes are a fixed collection of 20 named presets** (including *Specimen, Atelier, Hum,* and *Carnival*). Each bundles three locked attributes: a **paper-band**, a **display-style**, and an **accent-hue**. These values are hard-coded in [[`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) and never improvised during generation.

### When Catalog Themes Run

According to [[`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), the catalog is the **silent default**. Hallmark stays in this route unless the brief carries explicit creative-intent signals.

The catalog decision flow works as follows:

1. **Detect signals** — none found → remain in catalog
2. **Pick a theme** from the 20-item list, respecting the **diversification rule** (must differ from the previous run in at least one axis: paper-band, display-style, or accent-hue)
3. **Proceed** with macrostructure, nav/footer, and enrichment steps

### Catalog Theme Limitations

- **Never** invents new palettes or fonts
- Every color and typeface must reference tokens defined in the catalog
- **Slop-test gate 48** rejects any mid-render improvisation
- Theme choice is recorded in [`.hallmark/log.json`](https://github.com/Nutlope/hallmark/blob/main/.hallmark/log.json) as `theme: "<name>"`

---

## What Is the Hallmark Custom Theme Branch?

**The custom-theme branch is a one-off, made-to-measure system** that constructs fresh OKLCH palettes and free font pairings per brief. It can operate in two modes:

| Mode | Scope |
|------|-------|
| **Tuned** | Custom palette + fonts applied to Hallmark's existing macrostructures |
| **Bespoke** | Custom palette + fonts + entirely new page structure |

As documented in [[`skills/hallmark/references/custom-theme.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/custom-theme.md)](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/custom-theme.md), this route triggers only when the brief meets at least one of five conditions:

1. Explicitly asks for a custom look
2. Names a brand color
3. Supplies a multi-attribute aesthetic unmapped to any catalog theme
4. Attaches a moodboard or color swatch
5. Requests a completely new structure

### Custom Theme Workflow

Hallmark follows a strict six-step protocol:

1. **Signal detection** (conditions above)
2. **Ask the one-line vibe** (4–8 words) plus optional anchor color
3. **Palette construction**: anchor → OKLCH, paper-L band, ink, greys
4. **Font pairing**: any tone-pair, not limited to catalog's fixed sets
5. **Axis computation**: paper band, display style, accent hue recorded for diversification
6. **Optional bespoke step**: design new page layout if structure itself is the ask

### Custom Theme Persistence

Unlike catalog themes, custom outputs log their full axis data:

```json
{
  "theme": "custom",
  "theme_axes": { "paper": "light", "display": "italic-serif", "accent": "chromatic-terracotta" },
  "vibe": "archival warmth, hand-set, no varnish"
}

```

This lets the diversification rule remain **theme-route-blind** — custom vs. custom must also differ on at least one axis.

---

## Code Comparison: Theme Stamps in Generated CSS

Hallmark writes a diagnostic stamp to the top of every stylesheet. These stamps reveal which route was taken and enable diversification tracking.

### Catalog Theme Stamp

```css
/* Hallmark · macrostructure: Marquee Hero · theme: hum
 * paper: oklch(96% 0.012 95) · accent: oklch(58% 0.16 95)
 * display: Inter Tight · body: Inter · axes: light / geometric-sans / cool
 */

```

### Custom Theme (Tuned) Stamp

```css
/* Hallmark · macrostructure: Long Document
 * 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
 */

```

### Custom Theme (Bespoke) Stamp

```css
/* Hallmark · macrostructure: Catalogue · route: custom (bespoke)
 * theme: custom · vibe: "moss, lichen, soft pink, herbal"
 * paper: oklch(96% 0.018 145) · accent: oklch(72% 0.13 350)
 * display: Cormorant Garamond · body: EB Garamond
 * axes: light / roman-serif / chromatic‑other (dusty‑pink)
 */

```

These stamps are generated in **Step 6** of [`SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/SKILL.md) and later parsed by Hallmark to enforce the diversification rule.

---

## Key Architectural Files

| File | Purpose |
|------|---------|
| [`skills/hallmark/SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md) | Central dispatcher — defines when catalog is default and how custom branch invokes |
| [`skills/hallmark/references/custom-theme.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/custom-theme.md) | Full protocol for custom route (signals, palette construction, axis computation) |
| [`site/css/tokens.css`](https://github.com/Nutlope/hallmark/blob/main/site/css/tokens.css) | Token definitions for all 20 catalog themes |
| `skills/hallmark/references/themes/<theme>.md` | Individual catalog theme specifications |
| [`.hallmark/log.json`](https://github.com/Nutlope/hallmark/blob/main/.hallmark/log.json) | Rotation log storing theme choices and axes for diversification |
| [`skills/hallmark/references/macrostructures.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/macrostructures.md) | Index of 21 named macrostructures |
| [`skills/hallmark/references/component-cookbook.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/component-cookbook.md) | Nav/footer archetypes applied after macrostructure selection |

The **catalog lives in static token files**; the **custom logic lives in [`custom-theme.md`](https://github.com/Nutlope/hallmark/blob/main/custom-theme.md)** and executes dynamically per brief.

---

## Summary

- **Catalog themes** are 20 pre-defined, hard-coded visual systems that rotate automatically when no creative signals are detected
- **Custom-theme branch** generates ephemeral, made-to-measure palettes and font pairings only when briefs explicitly signal creative intent
- Both routes enforce **universal design disciplines**: contrast requirements, banned font restrictions, and no pure `#000/#fff` colors
- **Diversification rules apply equally**: consecutive outputs must differ in at least one axis regardless of route
- Custom themes **do not extend the permanent catalog** — they are per-output, disposable designs

---

## Frequently Asked Questions

### How does Hallmark decide between catalog and custom theme?

Hallmark checks for five signals in every brief: explicit custom requests, brand color names, unmapped multi-attribute aesthetics, attached moodboards, or structural redesign asks. If none appear, it defaults to the catalog rotation. If any appear, it asks a brief follow-up to confirm the custom route before proceeding with palette construction.

### Can a custom theme become part of the permanent catalog?

No. Custom themes are **ephemeral by design**. Each is built per-output from the protocol in [`custom-theme.md`](https://github.com/Nutlope/hallmark/blob/main/custom-theme.md), logged with full axis data for diversification, then discarded. The 20 catalog themes remain the only persistent, named options unless the repository maintainer manually adds new entries to [`site/css/tokens.css`](https://github.com/Nutlope/hallmark/blob/main/site/css/tokens.css).

### What happens if a custom theme fails slop-test gates?

The custom theme branch is **still subject to all slop-test gates** including contrast validation, banned font detection, and pure black/white prohibition. A generation that violates these rules is rejected and regenerated, just like catalog themes. The "freedom" in custom mode refers only to palette/structure invention, not relaxed quality standards.

### How does diversification work across theme routes?

The diversification rule is **theme-route-blind**. Whether the previous output used catalog theme *Hum* or a custom "archival warmth" build, the next output must differ in at least one of three axes: paper-band lightness, display style, or accent hue chromaticity. The [`.hallmark/log.json`](https://github.com/Nutlope/hallmark/blob/main/.hallmark/log.json) stores `theme_axes` for custom entries to enable this comparison.