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

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 (lines 11-12), the tuned depth only changes the combination of palette and typography. The system reads from 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 (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).

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

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

/* 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 and 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 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 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 for reference but do not modify the core tokens file. Both modes generate CSS variables at runtime via site/js/main.js, leaving the catalog defaults intact for future runs.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}