# Tuned vs Bespoke Custom Themes in Hallmark: Two Levels of Customization Explained

> Understand the difference between tuned and bespoke custom themes in Hallmark. Tuned themes adjust colors and fonts, while bespoke themes create entirely new page layouts for ultimate customization.

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

---

**Tuned custom themes preserve Hallmark's default page structures while generating unique color palettes and font pairings; bespoke custom themes design entirely new page layouts from first principles.**

Hallmark's generative design system distinguishes between two depths of customization for "custom" route requests. Understanding this difference helps designers and developers choose the right approach when creating branded pages. According to the Hallmark source code, these two modes—**tuned** and **bespoke**—operate under different constraints and produce dramatically different outputs.

## What Tuned Custom Themes Do

A **tuned** custom run generates a one-off OKLCH palette and font pairing built specifically for the current brief. However, it preserves all of Hallmark's default structures, archetypes, and macro-structures.

The tuned implementation is described in [`skills/hallmark/references/custom-theme.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/custom-theme.md) under the "Tuned" section. When running in tuned mode, the following rules remain intact:

- Paper bands and color-chroma caps
- Font bans and slop-test gates
- Catalog macro-structures (hero, stat-led, catalogue)
- Diversification-axis rules

Only the **combination** of palette and type changes per brief. The page still follows predefined macro-structures, meaning the foundational layout architecture stays consistent.

### Tuned Example: Archival Café Theme

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

```

Notice the **"macrostructure: Long Document"** declaration—this preserves the default structure while applying custom aesthetic choices.

## What Bespoke Custom Themes Do

A **bespoke** custom run activates when the brief requires a **new structure or composition** that cannot be expressed by any catalog macro-structure. As detailed in [`skills/hallmark/references/custom-theme.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/custom-theme.md) under "§ Bespoke depth" (lines 50-61), this mode:

- Designs the entire page from first principles
- Creates a unique palette and type system
- Builds a **brand-new macro-structure**

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

### Bespoke Example: Industrial Fintech Theme

```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 **"macrostructure: Workbench"** declaration reveals the key difference—this replaces the catalog's default layout with a custom-crafted architecture featuring sticky-scroll behavior and trace-panel content.

## Key Differences Between Tuned and Bespoke

| Aspect | Tuned | Bespoke |
|--------|-------|---------|
| **Palette & Type** | Custom-generated | Custom-generated |
| **Macro-structure** | Preserved from catalog | Built from scratch |
| **Layout rules** | Follows diversification-axis defaults | Redefines page architecture |
| **Trigger** | Implicit custom signal | Requires explicit structural signal (signal 5) |
| **Use case** | Branded look, standard flow | Novel interaction patterns, unconventional layouts |

## How to Choose Between Tuned and Bespoke

Select **tuned** when you need:

- Consistent page flows with unique branding
- Standard hero, catalog, or stat-led structures
- Faster iteration with predictable constraints

Select **bespoke** when you need:

- Scroll-assembling poems, ticket-shaped pages, or interactive periodic tables
- Layouts that violate catalog diversification axes
- Truly novel spatial compositions

Bespoke runs are rarer because they require explicit structural signaling in the protocol and demand more design deliberation.

## Source Files and Implementation

The custom-theme system references these key files:

- [`skills/hallmark/references/custom-theme.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/custom-theme.md) — defines the protocol, depths, 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 including the "Stamp the output" step
- [`site/css/tokens.css`](https://github.com/Nutlope/hallmark/blob/main/site/css/tokens.css) — stores catalog theme tokens (read by custom runs but never modified by them)
- [`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 the final stylesheet and apply CSS variables at runtime

Custom runs, whether tuned or bespoke, do not modify [`tokens.css`](https://github.com/Nutlope/hallmark/blob/main/tokens.css). Instead, they generate inline declarations that override defaults at runtime.

## Summary

- **Tuned custom themes** change *what* the page looks like (palette + typography) while preserving *how* the page is built
- **Bespoke custom themes** change both *what* and *how*, creating entirely new page structures from first principles
- Both modes respect Hallmark's universal floor: accessibility, slop-test gates, and color discipline
- The choice depends on whether your brief requires standard layout flows or novel architectural compositions

## Frequently Asked Questions

### What file controls the tuned vs bespoke distinction in Hallmark?

The protocol is defined in [`skills/hallmark/references/custom-theme.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/custom-theme.md). Lines 11-12 cover the tuned depth, while lines 12-13 introduce bespoke. The bespoke implementation details span lines 50-61.

### Can a tuned theme ever modify macro-structures?

No. Tuned themes explicitly preserve all catalog macro-structures, archetypes, and diversification-axis rules. Only bespoke themes can redefine the page architecture.

### How does Hallmark signal a bespoke run is needed?

Bespoke depth requires **signal 5** in the custom-theme protocol—an explicit structural signal indicating the brief cannot be satisfied by any catalog macro-structure. Tuned runs proceed without this signal.

### Do custom themes write changes to the tokens.css file?

No. As implemented in the Hallmark source code, [`site/css/tokens.css`](https://github.com/Nutlope/hallmark/blob/main/site/css/tokens.css) remains read-only for custom runs. Both tuned and bespoke themes generate inline CSS declarations that override tokens at runtime through [`site/js/main.js`](https://github.com/Nutlope/hallmark/blob/main/site/js/main.js).