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

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 (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

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

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

/* 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 — Defines the full protocol including depth levels, signals, and stamping format
• skills/hallmark/references/skill.md — Contains the generic workflow with the "Stamp the output" step that records custom axes
• site/css/tokens.css — Stores catalog theme tokens; custom runs read but do not modify this file
• site/index.html and 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

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?

No. Bespoke themes read from 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. The difference lies in design flexibility and validation overhead, not rendering speed.

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