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

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

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

/* 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 — defines the protocol, depths, signals, and stamping format
• skills/hallmark/references/skill.md — contains the generic workflow including the "Stamp the output" step
• site/css/tokens.css — stores catalog theme tokens (read by custom runs but never modified by them)
• site/index.html and 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. 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. 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 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.

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