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

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

{
  "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

/* 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

/* 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

/* 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 and later parsed by Hallmark to enforce the diversification rule.

---

Key Architectural Files

File	Purpose
skills/hallmark/SKILL.md	Central dispatcher — defines when catalog is default and how custom branch invokes
skills/hallmark/references/custom-theme.md	Full protocol for custom route (signals, palette construction, axis computation)
site/css/tokens.css	Token definitions for all 20 catalog themes
skills/hallmark/references/themes/<theme>.md	Individual catalog theme specifications
.hallmark/log.json	Rotation log storing theme choices and axes for diversification
skills/hallmark/references/macrostructures.md	Index of 21 named macrostructures
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 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, 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.

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 stores theme_axes for custom entries to enable this comparison.

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