# Tuned vs Bespoke Custom Themes in Hallmark: Understanding the Two Depth Levels

> Discover the difference between tuned and bespoke custom themes in Hallmark. Learn how tuned themes use default structures with custom palettes, while bespoke themes build new structures from scratch.

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

---

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

The Hallmark design system, maintained by Nutlope, offers two distinct levels of customization for "custom" routes. Understanding the difference between tuned and bespoke custom themes helps you determine which depth level fits your project needs and what constraints each approach preserves.

## What Are Tuned Custom Themes?

A **tuned** custom theme generates a one-off OKLCH palette and font pairing built specifically for the current brief. This depth level preserves Hallmark's entire structural foundation while changing only the surface-level aesthetics.

According to the custom-theme protocol in [`skills/hallmark/references/custom-theme.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/custom-theme.md) (lines 11-12), tuned themes maintain:

- All default macro-structures from the catalog (hero, stat-led, catalogue)
- Diversification-axis rules
- Paper band constraints
- Colour-chroma caps
- Font bans
- Slop-test gates

The only per-brief changes are the *combination* of palette and typeface. The page architecture remains untouched.

### Example: Tuned Custom Run

```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
 */

```

This "Coffeebox" example keeps the standard "Long Document" macro-structure intact while applying custom color and typography axes.

## What Are Bespoke Custom Themes?

A **bespoke** custom theme triggers when a brief requires a structure that cannot be expressed by any catalog macro-structure. This is the deeper customization level defined at lines 12-13 and expanded in lines 50-61 of [`skills/hallmark/references/custom-theme.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/custom-theme.md).

Bespoke themes:

- Design the entire page from first principles
- Create a **brand-new macro-structure** (e.g., scroll-assembling poem, ticket-shaped page, interactive periodic table)
- Generate a unique palette and type pairing
- Discard catalog macro-structure and diversification-axis defaults

Only the **universal floor** remains fixed: slop-test gates, accessibility requirements, font-ban list, and colour-discipline rules.

Bespoke runs require **signal 5** in the protocol—an explicit structural signal indicating that standard layouts are insufficient.

### Example: Bespoke Custom Run

```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 "Workbench" macro-structure here is custom-crafted, replacing any catalog default.

## Key Differences: Tuned vs Bespoke Custom Themes

| Dimension | Tuned | Bespoke |
|-----------|-------|---------|
| **Palette** | Custom OKLCH per brief | Custom OKLCH per brief |
| **Typography** | Custom font pairing | Custom font pairing |
| **Macro-structure** | Preserves catalog defaults | Entirely new design |
| **Diversification axes** | Applied from catalog | Redefined custom |
| **Trigger condition** | Any custom brief | Signal 5: structural requirement |
| **Implementation rarity** | Common | Rare |

## Where Custom Theme Data Lives

Several files govern how Hallmark processes tuned and bespoke themes:

- **[`skills/hallmark/references/custom-theme.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/custom-theme.md)** — Defines the full protocol including depth levels, signals, and stamping format
- **[`skills/hallmark/references/skill.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/skill.md)** — Contains the generic workflow with the "Stamp the output" step that records custom axes
- **[`site/css/tokens.css`](https://github.com/Nutlope/hallmark/blob/main/site/css/tokens.css)** — Stores catalog theme tokens; custom runs read but do not modify this file
- **[`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)** — Render stylesheets and apply generated CSS variables at runtime

## Choosing Between Tuned and Bespoke

Select **tuned** when your brief needs:

- A specific aesthetic mood without structural changes
- Faster turnaround with predictable constraints
- Catalog-tested layout patterns

Select **bespoke** when your brief needs:

- A layout impossible to express through catalog macro-structures
- Novel interaction patterns or composition logic
- Explicit signal 5 validation from stakeholders

## Summary

- **Tuned custom themes** change *what* the page looks like (palette + type) while preserving *how* the page is built (catalog macro-structures)
- **Bespoke custom themes** change both *what* and *how*, creating entirely new page architectures from first principles
- Both depths maintain the universal floor: slop-test gates, accessibility, font bans, and colour discipline
- Bespoke requires signal 5 in the protocol and is implemented in [`skills/hallmark/references/custom-theme.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/custom-theme.md)

## Frequently Asked Questions

### Can a tuned theme become bespoke mid-project?

No. The depth level is determined at brief ingestion based on whether signal 5 is present. If structural requirements emerge that exceed catalog capabilities, the project must restart with a bespoke designation and new stamping protocol.

### Does bespoke override [`site/css/tokens.css`](https://github.com/Nutlope/hallmark/blob/main/site/css/tokens.css)?

No. Bespoke themes read from [`site/css/tokens.css`](https://github.com/Nutlope/hallmark/blob/main/site/css/tokens.css) for reference but generate independent CSS variables at runtime. Neither tuned nor bespoke modifications write back to the catalog token file.

### Why is signal 5 required for bespoke?

Signal 5 acts as a governance checkpoint. Because bespoke themes discard tested macro-structures and diversification axes, the protocol requires explicit structural justification to prevent unnecessary complexity and maintain output quality.

### Which depth level performs better at runtime?

Performance is equivalent. Both tuned and bespoke themes compile to static CSS variables applied by [`site/js/main.js`](https://github.com/Nutlope/hallmark/blob/main/site/js/main.js). The difference lies in design flexibility and validation overhead, not rendering speed.