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

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

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

/* 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 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 — Contains the full protocol specification and defines the two depths, including decision criteria for Tuned versus Bespoke routing.
• skills/hallmark/SKILL.md — Defines the stamp format used by both depths to record theme metadata and version information.
• 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 — 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 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 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, while Bespoke themes may define entirely new structural variables inline, as they are not constrained by the catalog token architecture.

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