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

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) 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/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
• 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/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:

// 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/ 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).

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

# 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.

Custom Theme Output Stamp

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

/* 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/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	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 (flow control) and 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, 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.

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