How Hallmark's Custom Theme Protocol Enables Brand‑Specific Designs

Hallmark's custom theme protocol is a lightweight, on‑the‑fly design system that injects brand‑specific OKLCH color palettes and font pairings into a page's :root CSS without modifying the shared catalog of 21 named themes.

This protocol allows a single‑page build to adopt unique visual identities while maintaining full compatibility with Hallmark's component library. When a brief contains brand colors, custom typography requests, or structural needs the catalog cannot satisfy, the system automatically forks to a custom branch—generating bespoke tokens that downstream components consume exactly like standard catalog theme tokens.

How the Custom Theme Protocol Detects Brand Requests

The detection rules for triggering a custom theme run are documented in skills/hallmark/references/custom-theme.md and referenced from SKILL.md. Hallmark scans for three signal types:

• Explicit requests — phrases like "custom theme," "tailored to our brand," or "bespoke design"
• Brand color references — HEX codes, OKLCH values, Pantone chips, or attached swatches (e.g., #008080)
• Unique structural visions — layouts that no catalog macrostructure can satisfy, such as "scroll‑assembling poem layout"

If any signal matches, the protocol overrides the default catalog route. This ensures low friction for standard briefs while enabling deep customization when brand specificity is required.

Two Depths of Custom Theme Execution

The protocol supports two execution depths, controlled by the detected signals and brief complexity:

Depth	Behavior
Tuned custom	Generates a one‑off OKLCH palette and free‑font pairing, injected into :root. Standard Hallmark macrostructures and components remain unchanged.
Bespoke	Adds brand‑specific composition (custom layout, component selection) built from first principles. No catalog macrostructure is used.

Both depths generate per‑output tokens only—they never write to site/css/tokens.css, keeping the shared catalog pristine.

Technical Implementation: From Signal to Rendered CSS

Step 1: Token Generation in OKLCH

Custom themes use OKLCH color space for perceptual uniformity across light and dark drops. The protocol derives values from brand swatches or natural‑language vibe descriptions, then writes them as CSS custom properties.

A minimal custom theme block from custom-theme.md:

/* Hallmark · route: custom · vibe: "archival warmth, hand‑set, no varnish" */
:root {
  --color-paper: oklch(94% 0.020 65);   /* warm cream */
  --color-accent: oklch(58% 0.16 35);   /* terracotta */
  --font-display: "Geist", system-ui, sans-serif;
  --font-body:    "Geist", system-ui, sans-serif;
}

Step 2: Inline Injection

Unlike catalog themes stored in tokens.css, custom theme values are written inline to the generated page's CSS. This follows the "design‑tokens in one place" rule from contract.md while maintaining isolation.

Example API payload for a custom theme request:

{
  "theme": "custom",
  "vibe": "industrial precision, cool, technical",
  "paper": "oklch(13% 0.012 220)",
  "accent": "oklch(72% 0.16 220)",
  "fontDisplay": "Inter",
  "fontBody": "Inter"
}

Resulting output in the generated HTML:

<style>
:root{
  --color-paper: oklch(13% 0.012 220);
  --color-accent: oklch(72% 0.16 220);
  --font-display: "Inter", system-ui, sans-serif;
  --font-body:    "Inter", system-ui, sans-serif;
}
</style>

Step 3: Universal Component Consumption

Hallmark's token‑consumer logic pulls var(--color-paper), var(--color-accent), and derived values like var(--color-accent-ink) exactly as it would from a catalog theme. As documented in interaction-and-states.md, components automatically respect these brand‑specific tokens for spacing, micro‑interactions, and state variations.

Diversification Rules Prevent Brand Drift

Custom themes participate fully in Hallmark's diversification system. The protocol logs three axis values to .hallmark/log.json:

• paper (background luminance/chroma)
• accent (brand color values)
• type-pairing (font family combination)

Each new custom build must differ on at least one axis from the previous run—whether that prior run used a catalog theme or custom tokens. This prevents accidental repetition across a series of outputs for the same brand, as specified in custom-theme.md (lines 177–256).

Key Advantages Over Catalog Themes

Capability	Catalog Theme	Custom Theme Protocol
Color flexibility	Fixed OKLCH bands per named theme	Arbitrary OKLCH values from brand swatches
Typography	Pre‑approved font families only	Any Google Font or brand‑owned web font
Layout depth	Static macrostructure list	Bespoke composition when needed
Persistence cost	Requires repo changes and version bump	One‑off, no catalog pollution
Rotation safety	Cycles through preset names	Same axis‑based diversification applies

Real‑World Workflow Example

A product manager requests: "Make a landing page for Coffeebox with our teal brand color."

1. Hallmark detects the brand color signal (#008080 or similar)
2. Protocol forks to tuned custom depth (default unless structural bespoke needs detected)
3. Generates OKLCH palette: --color-paper and --color-accent derived from teal
4. Selects compatible free‑font pairing or accepts specified brand fonts
5. Injects tokens into :root, renders requested macrostructure
6. Logs diversification axes to log.json for future run comparison

The resulting page uses Hallmark's standard hero, button, and section components—but every color and type choice reflects Coffeebox's brand identity. No pull request to tokens.css was required.

Summary

• Signal detection in custom-theme.md and SKILL.md triggers the custom branch when brand specificity is needed
• Two depths (tuned custom, bespoke) balance speed against full creative control
• OKLCH tokens written inline to :root ensure perceptual uniformity and automatic component compatibility
• Diversification logging prevents repetitive outputs across custom runs
• Zero catalog pollution keeps the 21 named themes unchanged while enabling unlimited brand variations

Frequently Asked Questions

How does Hallmark prevent custom themes from breaking component layouts?

Components consume tokens through var() references rather than hardcoded values. Since custom themes write to the same CSS custom properties (--color-paper, --color-accent, --font-display, etc.) that catalog themes define, the component rendering pipeline remains unchanged. The contract.md file enforces this "design‑tokens in one place" rule.

Can I use a custom theme with a pre‑defined Hallmark layout?

Yes—tuned custom depth does exactly this. It generates brand‑specific colors and fonts while preserving your choice of standard macrostructure. Only bespoke depth discards catalog layouts entirely.

What happens if I request the same brand colors twice in a row?

The diversification rule (documented in custom-theme.md, lines 177–256) requires each output to differ on at least one axis (paper, accent, or type-pairing) from the previous run. If identical values would be generated, Hallmark automatically adjusts—typically by shifting luminance or selecting an alternative font pairing that maintains brand coherence while ensuring visual variety.

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