# Understanding Hallmark's Custom Theme Protocol: Tuned vs Bespoke Design Modes

> Explore Hallmark's custom theme protocol. Understand how bespoke design modes trigger unique OKLCH palettes and font pairings, moving beyond default themes for tailored branding.

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

---

**Hallmark's custom theme protocol activates when a design brief contains specific signals—such as brand colors, explicit requests, or structural visions—triggering a bespoke OKLCH palette and font pairing construction process instead of using the default catalog of 21 named themes.**

The Nutlope/hallmark repository implements a sophisticated design system that dynamically chooses between a fixed catalog of themes and a custom route tailored to unique brand requirements. When your brief contains specific trigger signals, Hallmark engages its custom theme protocol to generate one-off visual identities governed by strict constraints defined in [`skills/hallmark/references/custom-theme.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/custom-theme.md). This protocol integrates into the main workflow via [`skills/hallmark/SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md), ensuring seamless dispatch between standard and custom design flows.

## How the Custom Theme Protocol Activates

Hallmark monitors every brief for five specific signals that indicate a catalog theme will not suffice:

- **Explicit requests** for custom theming
- **Brand colours** provided in the brief
- **Multi-attribute vibes** requiring nuanced interpretation
- **Mood-board attachments** suggesting specific aesthetic directions
- **Structural visions** describing unique page compositions (Signal 5)

According to the protocol documentation in [`skills/hallmark/references/custom-theme.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/custom-theme.md), these signals determine whether Hallmark proceeds with its default catalog or initiates the custom construction pipeline. If you decline the custom route after the follow-up, Hallmark silently falls back to the catalog flow without mentioning the fork, as implemented at lines 30–33 of the protocol file.

## The Five-Step Custom Construction Process

When a signal fires, Hallmark executes a rigorous five-step protocol to build your theme.

### Step 1: Follow-Up Confirmation and Vibe Collection

Hallmark asks a single follow-up question to confirm the custom route and collect a short 4–8 word description of the brand's vibe, plus an optional anchor colour. This step, documented at lines 26–42 of [`custom-theme.md`](https://github.com/Nutlope/hallmark/blob/main/custom-theme.md), ensures the system has sufficient context before proceeding with palette construction.

### Step 2: OKLCH Palette Construction

The system builds the colour hierarchy following a strict sequence: anchor accent → paper → ink → greys → focus. Each colour adheres to numeric limits defined in Hallmark's colour discipline. For example, accent chroma must fall between 0.12 and 0.20, ensuring sufficient vibrancy without compromising accessibility. These constraints are detailed in lines 87–132 of the protocol file.

### Step 3: Font Pairing Selection

Hallmark selects from seven tone-pairings, allowing any mix of display and body fonts while respecting the banned-defaults list and the "free-baseline only" rule. This selection occurs at lines 42–62 of [`custom-theme.md`](https://github.com/Nutlope/hallmark/blob/main/custom-theme.md), ensuring typography aligns with the established vibe while avoiding overused system defaults.

### Step 4: Diversification Axes Computation

To ensure custom themes participate in Hallmark's rotation logic like catalog themes, the system computes three diversification-rule axes: paper band, display style, and accent-hue band. These axes, defined at lines 75–86, allow future runs to select visually distinct alternatives from the same custom base.

### Step 5: CSS Stamp Generation

Finally, Hallmark generates a CSS stamp at the top of the output stylesheet. This comment block records macrostructure, vibe, palette values, font choices, and axis values, enabling the next run to select a different theme. The stamp format is specified at lines 14–22 of the protocol file.

## Tuned vs Bespoke: Two Depths of Customization

The custom theme protocol distinguishes between two implementation depths:

**Tuned Custom** creates a one-off palette and font pair while retaining Hallmark's standard macrostructures. This mode triggers on any signal except structural visions, offering brand-specific colours without abandoning proven layout patterns.

**Bespoke Custom** executes a full page redesign including palette, typography, and composition when the brief specifies Signal 5 (a singular structural vision). This depth allows for radical departures from standard templates, such as scroll-assembling poem pages or non-linear narrative layouts.

Both depths inherit universal constraints including slop-test gates, APCA contrast requirements, and the font-ban list, ensuring design quality remains consistent regardless of customization level.

## CSS Stamp Format and Examples

The CSS stamp serves as both documentation and metadata for Hallmark's theme rotation system. Here are practical examples of the protocol in action.

When processing a brief containing a brand colour or explicit request:

```text
Build a landing page for "Coffeebox".
Tone: warm, hand-set, editorial.
Theme route: custom.

```

Hallmark responds with the follow-up:

> "This brief reads like a custom palette would fit better than the 21 named themes. Want me to construct a custom OKLCH palette + free-font pairing tuned to … ?"

Upon receiving the user's vibe description:

```text
archival warmth, hand-set, no varnish
Anchor colour: terracotta

```

Hallmark generates a Tuned custom stamp:

```css
/* 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: Fraunches italic · body: Source Serif 4 · axes: light / italic-serif / chromatic-terracotta
 * studied: no · context: explicit · v0.8.0
 */

```

For a Bespoke custom request involving structural vision:

```text
Create a scroll-assembling poem page, no theme, from scratch.

```

The resulting stamp reflects the unique composition:

```css
/* Hallmark · route: custom (bespoke) · structure: scroll-poem · idea: "continuous lyrical flow"
 * paper: oklch(88% 0.015 210) · accent: oklch(55% 0.18 210)
 * display: Inter Tight 900 · body: Inter Tight 400 · axes: dark / display-heavy / cool
 * studied: no · context: explicit · v0.8.0
 */

```

## Summary

- Hallmark's custom theme protocol activates on five specific signals defined in [`skills/hallmark/references/custom-theme.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/custom-theme.md), including brand colours and structural visions.
- The protocol follows a five-step construction process: follow-up confirmation, OKLCH palette building, font pairing selection, diversification axes computation, and CSS stamp generation.
- **Tuned** custom themes adjust colours and typography while preserving macrostructures; **Bespoke** themes redesign composition entirely when Signal 5 triggers.
- All custom themes must pass universal quality gates including APCA contrast checks and the banned-fonts list.
- CSS stamps record theme metadata at the top of stylesheets, enabling intelligent rotation in subsequent design runs.

## Frequently Asked Questions

### What triggers the custom theme protocol in Hallmark?

The protocol activates when a brief contains specific signals: an explicit request for custom theming, a specified brand colour, multi-attribute vibe descriptions, mood-board attachments, or a structural vision (Signal 5). These indicators suggest the fixed catalog of 21 themes will not adequately serve the design requirements.

### How does Hallmark ensure custom themes meet accessibility standards?

Every custom theme, whether Tuned or Bespoke, inherits universal constraints including slop-test gates, APCA contrast requirements, and a banned-fonts list. Additionally, the colour discipline enforces strict numeric limits for OKLCH values—such as accent chroma between 0.12 and 0.20—to maintain legibility and visual harmony.

### What is the difference between Tuned and Bespoke custom themes?

Tuned custom themes generate one-off OKLCH palettes and font pairings while retaining Hallmark's standard macrostructures, triggering on any signal except structural visions. Bespoke custom themes activate only on Signal 5 (structural vision) and redesign the entire page composition including layout, palette, and typography from scratch.

### Where is the custom theme protocol documented in the Hallmark repository?

The complete protocol specification resides in [`skills/hallmark/references/custom-theme.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/custom-theme.md), detailing trigger signals, construction steps, and stamp formats. The integration of this protocol into Hallmark's main workflow is described in [`skills/hallmark/SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md), which explains how the system dispatches between catalog and custom routes.