How Hallmark Decides Between Custom Theme vs Catalog Theme Routes

Hallmark routes every design brief through a signal-detection gate that checks for five specific custom-intent markers; when any signal fires, it surfaces a single follow-up question to confirm the custom branch, otherwise it silently proceeds with the default catalog route.

The Nutlope/hallmark repository implements a disciplined design flow that prevents unnecessary custom theme generation while ensuring bespoke capabilities exist when explicitly needed. According to the source code in SKILL.md, the system evaluates every brief against a strict set of criteria before deciding whether to load the custom theme protocol from custom-theme.md or select from the 20 catalog themes.

Signal Detection: The Theme Route Gateway

Hallmark's routing logic lives primarily in skills/hallmark/SKILL.md, which defines the scanning rules that trigger the custom theme branch. The system looks for theme-route signals—specific markers indicating the user requires a bespoke aesthetic that the standard catalog cannot satisfy.

Explicit Custom Language

The first signal detects direct requests for custom work. When the brief contains phrases like custom, "custom theme", "tailored to our brand", "make it ours", "something unique", or "play around with the colors and fonts", Hallmark flags the brief for the custom route.

Named Brand Color Anchors

If the user supplies specific color values—hex codes like #c0392b, OKLCH values, or referential names like "our terracotta"—the system recognizes this as a named brand colour signal. This indicates the need for a custom theme built around that specific anchor rather than a prefabricated catalog palette.

Multi-Attribute Aesthetic Overflow

When a brief supplies three or more vibe words that don't map to any single catalog theme (for example, "moss, lichen, soft pink, herbal"), Hallmark detects a multi-attribute aesthetic signal. This indicates the brief's complexity exceeds the catalog's predefined theme structures.

Brand-Mood References

The system scans for references to external color systems. If the user mentions a "swatch", "Pantone" chip, or attaches a moodboard (distinct from a screenshot), Hallmark triggers the brand-mood reference signal, requiring custom palette generation.

Singular Structural Vision

The final signal catches requests for radical structural departure. Phrases like "no theme", "from scratch", "fully bespoke", or descriptions of page shapes lacking matching macrostructures in macrostructures.md trigger the singular structural vision signal, initiating a full bespoke custom run.

Decision Flow: From Signal to Execution

The routing implementation follows a strict procedural sequence defined in SKILL.md under "Theme route — only surface when the brief signals it". When processing a new brief, Hallmark executes these steps:

1. Scan for signals – Evaluate the brief against all five signal types during initial processing.

2. Surface the fork – If any signal fires, ask the one-line follow-up question defined in custom-theme.md section A. This is the only point where Hallmark interrupts the flow to request user input on theme direction.

3. Evaluate the response:

   • If the user confirms custom (or equivalent affirmative responses like "yes", "go", or "make it ours"), the system loads skills/hallmark/references/custom-theme.md and executes either the tuned or bespoke custom protocol.
   • If the user selects catalog or remains silent, the system drops the fork and proceeds to the catalog route.

4. Silent catalog default – If no signals are present, Hallmark does not mention the theme choice at all and proceeds directly to Step 2.6, selecting one of the 20 named catalog themes according to the diversification rule specified in the catalog selection logic.

Key Source Files and Their Roles

The decision architecture spans multiple files in the repository:

• skills/hallmark/SKILL.md – Contains the main design flow, signal detection algorithms, and dispatch logic that determines whether to trigger the custom branch or proceed with catalog selection.

• skills/hallmark/references/custom-theme.md – Implements the full custom-theme protocol, including the follow-up question wording, palette construction algorithms, font pairing logic, and stamp format specifications.

• skills/hallmark/references/macrostructures.md – Serves as the index of available macrostructures used after theme selection to determine page layouts.

• site/css/tokens.css – Houses the axis values for catalog themes and provides the diversification parameters used when the catalog route is selected.

Implementation Example

The following Python pseudo-code illustrates the decision logic implemented in Hallmark's core:

def decide_theme_route(brief):
    # 1️⃣ Detect signals

    signals = {
        "explicit": any(word in brief.lower() for word in ["custom", "tailored", "make it ours", "something unique", "play with the colors"]),
        "brand_colour": re.search(r"#?[0-9a-f]{3,6}|oklch|[a-z]+[-]?[a-z]+", brief, re.I),
        "multi_vibe": len(re.findall(r"\b\w+\b", brief)) >= 3 and not brief.lower().startswith(("warm", "technical", "playful")),
        "mood_reference": "swatch" in brief.lower() or "pantone" in brief.lower(),
        "structural_vision": any(kw in brief.lower() for kw in ["no theme", "from scratch", "fully bespoke"])
    }

    # 2️⃣ If any signal fires → ask follow‑up

    if any(signals.values()):
        answer = ask_user("Custom needs one input – describe the brand's vibe ...")
        if answer.lower().startswith(("custom", "yes", "go", "make it ours")):
            load_file("references/custom-theme.md")
            # proceed with tuned or bespoke custom protocol

            return "custom"
        else:
            # silent or explicit catalog reply

            return "catalog"
    else:
        # No signals → silent catalog

        return "catalog"

This implementation ensures that custom theme generation only occurs when the brief contains clear intent signals, while maintaining the catalog route as the friction-free default for standard requests.

Summary

• Hallmark evaluates every brief for five specific theme-route signals before deciding between custom and catalog paths.
• The signal detection logic resides in skills/hallmark/SKILL.md, which scans for explicit custom language, brand color anchors, multi-attribute aesthetics, mood references, and structural visions.
• When signals fire, Hallmark asks a single follow-up question from custom-theme.md; otherwise, it silently defaults to the catalog route containing 20 predefined themes.
• The catalog route uses diversification rules from site/css/tokens.css, while the custom route loads custom-theme.md for tuned or bespoke palette generation.
• This architecture ensures custom themes are only used when the brief clearly demands a bespoke look, preserving the catalog as the default for ordinary briefs.

Frequently Asked Questions

What happens if I mention a color but don't want a custom theme?

If you mention a specific color (hex, OKLCH, or brand name like "terracotta"), Hallmark detects the named brand colour signal and will ask the follow-up question. You can reply "catalog" or remain silent to proceed with the catalog route, and the system will drop the custom fork and select from the 20 catalog themes without using your specific color anchor.

Can Hallmark detect custom intent from images or screenshots?

Hallmark distinguishes between mood references and screenshots. If you attach a color swatch, moodboard, or Pantone reference (but not a screenshot), it triggers the custom route. Screenshots alone do not trigger the signal; they are processed differently in the visual analysis pipeline.

Where is the catalog theme diversification rule defined?

The diversification rule that determines which of the 20 named catalog themes to apply lives in site/css/tokens.css. This file contains the axis values and selection parameters used by the catalog route when no custom signals are detected in the brief.

What is the difference between "tuned" and "bespoke" custom themes?

According to custom-theme.md, a tuned custom theme generates a palette around specific constraints (like a brand color or multi-attribute vibes) while keeping standard structures, whereas a bespoke custom run occurs when the singular structural vision signal fires—creating full custom palettes, typography, and page structures from scratch without catalog constraints.

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