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

> Learn how Hallmark's custom theme protocol injects brand-specific OKLCH colors and fonts into your pages without altering shared themes. Discover a lightweight, on-the-fly design system.

- Repository: [Hassan El Mghari/hallmark](https://github.com/Nutlope/hallmark)
- Tags: how-to-guide
- Published: 2026-08-14

---

**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`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/custom-theme.md) and referenced from [`SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/custom-theme.md):

```css
/* 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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/contract.md) while maintaining isolation.

Example API payload for a custom theme request:

```json
{
  "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:

```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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/.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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/tokens.css) was required.

## Summary

- **Signal detection** in [`custom-theme.md`](https://github.com/Nutlope/hallmark/blob/main/custom-theme.md) and [`SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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.