# When Does Hallmark Trigger Custom Theme Branches vs. Catalog Themes?

> Discover when Hallmark uses custom theme branches or catalog themes based on creative intent signals, versus defaulting to pre-defined catalog options. Learn about custom styling and brand colors.

- Repository: [Hassan El Mghari/hallmark](https://github.com/Nutlope/hallmark)
- Tags: how-to-guide
- Published: 2026-07-22

---

**Hallmark triggers the custom-theme branch whenever a design brief contains a creative-intent signal—such as explicit requests for custom styling, brand-specific colors not in the catalog, or multi-attribute vibes—while defaulting to its 20 pre-defined catalog themes when no such signals are detected.**

Hallmark is an AI-powered design system that dynamically selects between two mutually exclusive theme generation paths. Understanding when Hallmark uses custom theme branches versus catalog themes is essential for predicting how the system interprets your design briefs and generates CSS palettes.

## The Two Mutually Exclusive Branches

Hallmark always begins by selecting a **theme** for a design brief. The system evaluates the brief against specific criteria and routes execution down one of two branches: the catalog-theme path or the custom-theme path.

### The Catalog Theme Branch (Default)

The catalog branch activates when the brief **lacks any creative-intent signal**. This means there is no explicit request for a custom look, no brand-specific color mentioned, and no multi-attribute vibe that the 20 named catalog themes cannot satisfy.

When this branch runs, Hallmark silently selects one of the **20 pre-defined catalog themes** and rotates among them according to the *diversification rule* documented in [[`SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/SKILL.md) § “Theme-diversification rule”](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md#L38). Users never see the word "catalog" in the output; the system simply applies the selected theme's palette and typography.

### The Custom Theme Branch (Creative-Intent Signals)

Hallmark dispatches to the custom-theme branch when the brief **contains a creative-intent signal**. According to the source code analysis, the system looks for three specific cues during the signal detection phase:

1. **Explicit ask** – The user writes phrases like *custom*, *custom theme*, *tailored to our brand*, *make it ours*, or *play around with the colors and fonts* (see [[`custom-theme.md`](https://github.com/Nutlope/hallmark/blob/main/custom-theme.md) § 1](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/custom-theme.md#L20)).

2. **Brand-color mention** – The brief names a brand hue that does not match any catalog drop, such as "our brand is teal and beige." In these cases, Hallmark routes to the custom branch (see the fallback note in [[`carnival.md`](https://github.com/Nutlope/hallmark/blob/main/carnival.md#L144)](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/themes/carnival.md#L144)).

3. **Multi-attribute vibe** – The user describes a mood or visual language that cannot be expressed by any single catalog theme, such as "a high-tech, pastel-gradient, retro-futurist vibe."

When any of these signals fire, Hallmark **constructs a one-off OKLCH palette and free-font pairing** and proceeds through the custom-theme flow (see [[`custom-theme.md`](https://github.com/Nutlope/hallmark/blob/main/custom-theme.md) § E](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/custom-theme.md#L177)).

## The Signal Detection and Dispatch Flow

The decision logic follows a strict two-step process defined in the high-level design flow:

1. **Signal detection (Step 1)** – The system scans the brief for the three creative-intent signals listed above.

2. **Dispatch (Step 2.6)** – 
   - If a signal is found → **custom-theme branch**.
   - If no signal is found → **catalog branch**.

This dispatch mechanism ensures that the branches remain mutually exclusive. The custom-theme branch also enforces all regular constraints (color, typography, anti-patterns) and runs the same **58 slop-test gates** as catalog themes—it simply uses a different palette and font generation path (see [[`SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/SKILL.md#L344-L378)](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md#L344)).

## Output Differentiation: Stamping vs. Silent Selection

The branches produce distinguishable outputs that downstream systems can parse.

### Custom Theme Stamping

When Hallmark generates a custom theme, it stamps the resulting CSS with a multi-line comment that records the vibe, paper and accent OKLCH values, and the three diversification-axis values. This metadata appears at [[`SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/SKILL.md#L461)](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md#L461) and enables the runtime system in [`site/js/main.js`](https://github.com/Nutlope/hallmark/blob/main/site/js/main.js) to identify custom themes and adjust macrostructure rotation on subsequent runs.

### Catalog Theme Output

Catalog themes generate a simpler stamp without custom vibe metadata, referencing only the macrostructure, tone, and anchor hue. The runtime system treats these as standard rotations within the 20-theme catalog set.

## Code Examples

### Prompt Triggering a Custom Theme

The following brief contains multiple creative-intent signals (brand colors + explicit "tailored" request):

```text
Create a landing page for our new product.  
Our brand colour is teal and beige, and we want something unique that feels “clean‑tech”.  
Please make the design tailored to our brand.

```

**Generated CSS excerpt:**

```css
/* Hallmark · macrostructure: hero · tone: bright ·
   theme: custom
   vibe: clean‑tech
   paper hue: oklch(0.85 0.12 210)  /* teal */
   accent hue: oklch(0.70 0.20 45)   /* beige */
   display font: "Inter", sans-serif
   body font: "Merriweather", serif
   diversification axes: hue‑rotation, contrast‑level, font‑weight */
:root {
  --paper: oklch(0.85 0.12 210);
  --accent: oklch(0.70 0.20 45);
  /* …rest of custom palette… */
}

```

The multi-line comment header serves as the **stamp** that distinguishes this as a custom theme.

### Prompt Using a Catalog Theme

This brief lacks creative-intent signals:

```text
Design a simple blog homepage for a tech writer.  
No brand colours or special styling requests. Just a clean layout.

```

**Generated CSS excerpt:**

```css
/* Hallmark · macrostructure: hero · tone: neutral · anchor hue: 210 */
:root {
  --paper: oklch(0.95 0.02 210);   /* Light gray */
  --accent: oklch(0.60 0.15 260);  /* Soft blue */
  /* …palette from the “cobalt” catalog theme… */
}

```

With no custom signals detected, Hallmark silently selected the "cobalt" theme from its catalog.

## Key Source Files and Implementation

The logic governing when Hallmark triggers custom theme branches versus catalog themes is distributed across these critical files:

- **[`SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/SKILL.md)** – Defines the high-level design flow, signal detection criteria, and dispatch rules at Step 2.6. Also documents the diversification rule for catalog rotation ([L38](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md#L38)) and the custom theme stamping format ([L461](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md#L461)).

- **[`custom-theme.md`](https://github.com/Nutlope/hallmark/blob/main/custom-theme.md)** – Contains the detailed specification for the custom-theme branch, including the explicit signal list ([§ 1](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/custom-theme.md#L20)), palette generation algorithms, and OKLCH construction rules ([§ E](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/custom-theme.md#L177)).

- **`themes/*.md`** (e.g., [`carnival.md`](https://github.com/Nutlope/hallmark/blob/main/carnival.md)) – Define the 20 catalog themes and contain fallback notes indicating when brand colors should trigger the custom branch ([L144](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/themes/carnival.md#L144)).

- **[`site/js/main.js`](https://github.com/Nutlope/hallmark/blob/main/site/js/main.js)** – Implements the runtime logic that reads the CSS stamp comments and determines macrostructure rotation behavior for subsequent runs.

## Summary

- **Creative-intent signals** (explicit custom requests, non-catalog brand colors, or complex multi-attribute vibes) trigger the custom-theme branch.
- **Absence of signals** defaults to the catalog branch, rotating silently among 20 pre-defined themes per the diversification rule.
- Both branches enforce identical constraints and pass the same 58 slop-test gates; they differ only in palette/font generation.
- Custom themes receive a detailed **stamp comment** in the CSS output containing vibe metadata and OKLCH values, while catalog themes receive minimal stamping.

## Frequently Asked Questions

### What specific phrases trigger Hallmark's custom-theme branch?

Hallmark looks for explicit phrases like *custom*, *custom theme*, *tailored to our brand*, *make it ours*, *something unique*, or *play around with the colors and fonts*. These signals are defined in [[`custom-theme.md`](https://github.com/Nutlope/hallmark/blob/main/custom-theme.md) § 1](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/custom-theme.md#L20) and are evaluated during the initial signal detection step.

### Can I force Hallmark to use a catalog theme even if I mention brand colors?

No. If you mention brand colors that do not match any of the 20 catalog theme drops, Hallmark automatically routes to the custom-theme branch according to the fallback logic noted in [[`carnival.md`](https://github.com/Nutlope/hallmark/blob/main/carnival.md#L144)](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/themes/carnival.md#L144). To stay in the catalog branch, avoid specifying exact brand hues or requesting tailored styling.

### How does Hallmark ensure custom themes meet the same quality standards as catalog themes?

The custom-theme branch runs through all regular constraints, color rules, typography checks, and the same **58 slop-test gates** applied to catalog themes. This enforcement is documented in [[`SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/SKILL.md#L344-L378)](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md#L344). The branches differ only in how the palette and fonts are generated, not in quality validation.

### Where can I find the list of Hallmark's 20 catalog themes?

The catalog themes are defined in the individual Markdown files located in the `skills/hallmark/references/themes/` directory (e.g., [`carnival.md`](https://github.com/Nutlope/hallmark/blob/main/carnival.md), [`cobalt.md`](https://github.com/Nutlope/hallmark/blob/main/cobalt.md)). These files specify each theme's anchor hues, diversification axes, and conditions for falling back to custom themes when brand requirements exceed the catalog's capabilities.