# Tuned vs Bespoke Custom Themes in Hallmark: What's the Difference?

> Discover the difference between tuned custom themes and bespoke custom themes in Hallmark. Learn how each approach impacts page structures and visuals for your website.

- Repository: [Hassan El Mghari/hallmark](https://github.com/Nutlope/hallmark)
- Tags: comparison
- Published: 2026-07-19

---

**Tuned custom themes generate a unique palette and font pairing while preserving Hallmark's default page structures, whereas bespoke custom themes design entirely new macro-structures from first principles in addition to custom visuals.**

The `Nutlope/hallmark` repository implements a two-tier **custom theme system** that offers distinct depth levels for custom visual routes. Understanding the difference between **tuned** and **bespoke** depths is essential for determining how radically a generated page will deviate from Hallmark's catalog defaults.

## What Are Tuned Custom Themes?

**Tuned custom themes** represent the first depth level of Hallmark's customization protocol. This mode generates a **one-off OKLCH palette and font pairing** built specifically for the current brief while maintaining all of Hallmark's predefined structural guardrails.

### Preserved Default Structures

When running a tuned theme, Hallmark retains its **default structures, archetypes, and macro-structures**. The page layout follows catalog conventions such as "Long Document," "hero," or "stat-led" compositions. All rules governing paper bands, colour-chroma caps, font bans, and slop-test gates remain intact.

### Implementation Details

According to the source code in [`skills/hallmark/references/custom-theme.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/custom-theme.md) (lines 11-12), the tuned depth only changes the *combination* of palette and typography. The system reads from [`site/css/tokens.css`](https://github.com/Nutlope/hallmark/blob/main/site/css/tokens.css) for default axes but does not modify this file, ensuring structural consistency across runs.

## What Are Bespoke Custom Themes?

**Bespoke custom themes** activate when a brief requires architectural changes impossible to express through existing catalog macro-structures. This depth **designs the entire page from first principles**, creating not just unique visual treatments but entirely new layout architectures.

### First-Principles Design

In bespoke mode, Hallmark discards the catalog's macro-structure and diversification-axis defaults. The system constructs **brand-new macro-structures**—such as scroll-assembling poems, ticket-shaped pages, or interactive periodic tables—while only the universal floor (slop-test gates, accessibility requirements, font-ban lists, and colour discipline) remains fixed.

### When Bespoke Is Required

The protocol documented in [`skills/hallmark/references/custom-theme.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/custom-theme.md) (lines 12-13 and expanded in lines 50-61) specifies that bespoke runs require an **explicit structural signal (signal 5)**. This rarity reflects the architectural complexity involved in generating custom-crafted layouts from scratch.

## Key Differences at a Glance

| Aspect | Tuned Custom Theme | Bespoke Custom Theme |
|--------|-------------------|---------------------|
| **Palette & Typography** | Custom OKLCH + font pairing | Custom OKLCH + font pairing |
| **Macro-Structure** | Preserves catalog defaults (e.g., Long Document, Workbench) | Creates new custom layout architecture |
| **Structural Rules** | All diversification-axis rules intact | Redefines page structure entirely |
| **Scope** | Changes *what* the page looks like | Changes *what* and *how* the page is built |

## Code Examples in Practice

The difference between these depths is visible in the generated CSS comments stamped by Hallmark's workflow (as defined in [`skills/hallmark/references/skill.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/skill.md)).

**Tuned custom theme** example preserving the "Long Document" macro-structure:

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

```

**Bespoke custom theme** example replacing the structure with a custom "Workbench" layout:

```css
/* Hallmark · macrostructure: Workbench · F2 sticky-scroll knobs: pinned=right, content=trace-panel, steps=3
 * theme: custom · vibe: "industrial precision, cool, technical" · paper: oklch(13% 0.012 220) · accent: oklch(72% 0.16 220)
 * display: Geist Mono 500 · body: Geist · axes: dark / mono / cool
 * studied: no · context: explicit · v0.8.0
 */

```

The runtime application of these themes occurs in [`site/index.html`](https://github.com/Nutlope/hallmark/blob/main/site/index.html) and [`site/js/main.js`](https://github.com/Nutlope/hallmark/blob/main/site/js/main.js), which render the final stylesheet and apply the generated CSS variables.

## Summary

- **Tuned custom themes** modify only the visual layer (palette and fonts) while keeping Hallmark's catalog macro-structures intact.
- **Bespoke custom themes** redesign the entire page architecture from first principles when catalog structures cannot accommodate the brief.
- **Tuned themes** maintain all slop-test gates, font bans, and structural rules; **bespoke themes** retain only the universal floor (accessibility and colour discipline).
- The distinction is enforced in [`skills/hallmark/references/custom-theme.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/custom-theme.md) and triggered by specific protocol signals.

## Frequently Asked Questions

### How do I know if I need a tuned or bespoke custom theme?

Choose a **tuned custom theme** when you want custom visuals (specific colours and fonts) but the content fits existing layout patterns like hero sections or document formats. Opt for **bespoke** when the brief demands unconventional layouts—such as interactive data visualizations or non-linear reading experiences—that cannot be expressed through Hallmark's catalog macro-structures.

### Can I switch between tuned and bespoke themes for the same project?

Hallmark treats these as distinct depth levels in the custom-theme protocol. While you can generate multiple variants, switching from tuned to bespoke requires an explicit structural signal (signal 5) and triggers a complete re-architecture of the page layout, not just a colour swap.

### What file controls the custom theme depth settings?

The [`skills/hallmark/references/custom-theme.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/custom-theme.md) file defines both tuned and bespoke depths, including their respective protocol signals and stamping formats. This file governs how the system interprets custom briefs and whether it preserves or replaces default macro-structures.

### Do custom themes modify the core Hallmark theme tokens?

No. Custom themes—whether tuned or bespoke—read from [`site/css/tokens.css`](https://github.com/Nutlope/hallmark/blob/main/site/css/tokens.css) for reference but do not modify the core tokens file. Both modes generate CSS variables at runtime via [`site/js/main.js`](https://github.com/Nutlope/hallmark/blob/main/site/js/main.js), leaving the catalog defaults intact for future runs.