# Hallmark Custom Theme Protocol: Understanding the Two Depths (Tuned vs Bespoke)

> Explore Hallmark custom theme protocol's two depths: Tuned for palette and font changes, and Bespoke for full structural redesign. Understand the differences and choose the right approach for your project.

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

---

**The Hallmark custom theme protocol defines two distinct depths—**Tuned** for palette and font customization within existing structures, and **Bespoke** for complete structural redesign from first principles.**

The Nutlope/hallmark repository implements a sophisticated theme system that routes custom design requests through two distinct depths of customization. These depths determine whether the system applies a one-off color and typography treatment or engineering an entirely new page architecture.

## The Two Depths of the Custom Theme Protocol

According to the protocol defined in [`skills/hallmark/references/custom-theme.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/custom-theme.md), Hallmark offers two custom theme routes that trade off flexibility against consistency.

### Tuned Depth: Palette and Typography Customization

The **Tuned** depth represents the lighter customization option. It generates a one-off OKLCH colour palette and font pairing built for a specific brief while **preserving Hallmark’s existing structures, archetypes, and macrostructures**. Only the combination of colours and typefaces changes per brief; the underlying layout engine and component hierarchy remain identical to catalog themes.

This depth stores its metadata in CSS stamp comments that explicitly declare `depth: tuned` alongside the custom palette and font selections.

### Bespoke Depth: Full Structural Redesign

The **Bespoke** depth represents the deepest customization level. At this depth, the page’s **structure and composition** are designed from first principles, dropping the catalog’s fixed macrostructures entirely. The only constraints that remain are the universal *slop-test* gates (the floor-level quality checks).

When Hallmark detects a request for "no theme," "from scratch," or "fully bespoke" treatment, it escalates from Tuned to this Bespoke depth, enabling custom scroll behaviors, non-standard layouts, and experimental compositions.

## How the Protocol Determines Depth

The protocol executes a decision tree when a user requests a custom theme. First, it confirms the user wants a custom theme at all. Then it evaluates the brief:

- If the brief requires only a unique colour and font combination without structural changes, Hallmark applies the **Tuned** depth.
- If the brief explicitly demands a unique page structure or rejects catalog shapes, Hallmark escalates to the **Bespoke** depth.

This logic ensures that structural complexity is only introduced when necessary, keeping simpler customizations lightweight and maintainable.

## Implementation in Code

Both depths record their configuration in machine-readable CSS "stamps" appear at the top of every generated stylesheet. These stamps encode the chosen depth along with all relevant metadata for downstream processing.

### Tuned Depth CSS Stamp

Here is an example stamp for a Tuned depth theme, showing the `depth: tuned` declaration and custom palette data:

```css
/* Hallmark · macrostructure: Long Document · H5 hero knobs: salutation=time‑stamp, body=2 paragraphs, signoff=initials
 * theme: custom · depth: tuned · 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
 */

```

### Bespoke Depth CSS Stamp

Here is a Bespoke depth example, showing the `depth: bespoke` flag and a custom macrostructure:

```css
/* Hallmark · macrostructure: Custom Scroll‑Poem · H7 custom knobs: scroll‑direction=horizontal, interactive=true
 * theme: custom · depth: bespoke · vibe: "experimental scroll poem, no catalog shape"
 * paper: oklch(96% 0.018 145) · accent: oklch(72% 0.13 350)
 * display: Cormorant Garamond · body: EB Garamond
 * axes: light / roman‑serif / chromatic‑other (dusty‑pink)
 * studied: no · context: explicit · v0.8.0
 */

```

The runtime logic in [`site/js/main.js`](https://github.com/Nutlope/hallmark/blob/main/site/js/main.js) parses these stamps to apply the correct CSS variables and layout behaviors.

## Key Source Files

The two depths are implemented across several critical files in the repository:

- **[`skills/hallmark/references/custom-theme.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/custom-theme.md)** — Contains the full protocol specification and defines the two depths, including decision criteria for Tuned versus Bespoke routing.
- **[`skills/hallmark/SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md)** — Defines the stamp format used by both depths to record theme metadata and version information.
- **[`site/css/tokens.css`](https://github.com/Nutlope/hallmark/blob/main/site/css/tokens.css)** — Houses the catalog-theme tokens; custom themes at both depths write their palette inline rather than modifying this file.
- **[`site/js/main.js`](https://github.com/Nutlope/hallmark/blob/main/site/js/main.js)** — Executes the runtime logic that reads the stamp and applies the generated CSS variables based on the declared depth.

## Summary

- The **Tuned** depth customizes only the OKLCH colour palette and font pairing while preserving Hallmark’s existing macrostructures and archetypes.
- The **Bespoke** depth allows complete structural redesign from first principles, overriding the catalog’s fixed layouts while maintaining quality gates.
- Both depths record configuration in CSS stamps that declare `depth: tuned` or `depth: bespoke` for downstream parsing.
- The protocol selects depth automatically based on whether the brief requests structural changes or only aesthetic customization.

## Frequently Asked Questions

### What triggers the Bespoke depth versus the Tuned depth?

The Bespoke depth triggers when a brief explicitly requests structural freedom, such as phrases like "no theme," "from scratch," or "fully bespoke." If the brief only mentions colour and font preferences without rejecting catalog structures, Hallmark keeps the customization at the Tuned depth.

### Where are the custom theme depth rules documented?

The complete protocol is documented in [`skills/hallmark/references/custom-theme.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/custom-theme.md) in the repository root. This file contains the plain-English definitions of both depths and the routing logic that determines which to apply.

### Can I manually override the depth selection in Hallmark?

The protocol is designed to select depth based on brief analysis. While the source code in [`site/js/main.js`](https://github.com/Nutlope/hallmark/blob/main/site/js/main.js) processes the stamp after generation, the depth is determined upstream during the brief interpretation phase. Direct manual override would require modifying the stamp generation logic in the skill definition.

### Do both depths use the same CSS variable system?

Yes, both Tuned and Bespoke themes ultimately generate CSS variables, but they source them differently. Tuned themes work within the existing token system defined in [`site/css/tokens.css`](https://github.com/Nutlope/hallmark/blob/main/site/css/tokens.css), while Bespoke themes may define entirely new structural variables inline, as they are not constrained by the catalog token architecture.