# How to Design a Custom Theme from First Principles Using Hallmark's Bespoke Depth

> Learn to design a custom theme from first principles with Hallmark. Gain full control over your palette, typography, and structure while obeying core system rules.

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

---

**Hallmark treats a custom theme as a first-principles construction that obeys every core rule of the system while giving you full control over palette, typography, and structure.**

When you need a theme that goes beyond the 21 pre-defined catalog options, Hallmark activates its **bespoke depth** workflow—a parallel route that builds themes from scratch using your brand's unique signals. This article walks through the complete protocol, from signal detection to stamped CSS output, using the actual implementation in `Nutlope/hallmark`.

## Signal Detection: When Hallmark Switches to Custom Mode

Hallmark's decision logic lives in [`skills/hallmark/SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md). The system diverts to the custom-theme protocol when your brief contains any of three explicit signals:

1. **Explicit ask** — phrases like "custom theme", "tailored to our brand", or "make it ours"
2. **Named brand colour** — a specific anchor hue supplied as HEX, OKLCH, or a brand name
3. **Multi-attribute aesthetic** — three or more descriptive words that don't map cleanly onto any catalog theme (e.g., "moss, lichen, soft pink, herbal")

A single adjective is **not** a signal. Hallmark treats standalone descriptors as **tone modifiers** and routes them through the standard catalog instead.

## The Six-Step Bespoke Construction Protocol

The full custom workflow is documented in [`skills/hallmark/references/custom-theme.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/custom-theme.md). Each step enforces Hallmark's global constraints while opening new degrees of freedom.

### Step 1: Vibe Capture

You provide a 4–8 word description of your brand's essence. The protocol includes concrete examples:

- "archival warmth, hand-set, no varnish"
- "moss, lichen, soft pink, herbal"
- "clinical precision, warm amber accents"

This description becomes the generative seed for all downstream decisions.

### Step 2: Palette Generation

Hallmark builds an **OKLCH palette** from your anchor hue (or derives one from the vibe). The generation follows strict rules from [`skills/hallmark/references/color.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/color.md):

- Hue, chroma, and lightness stay within allowed bands
- Neutral tinting constraints prevent muddy grays
- Anti-pattern gates from [`skills/hallmark/references/anti-patterns.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/anti-patterns.md) block invalid combinations

The floor of constraints never moves—even bespoke themes must pass every slop-test.

### Step 3: Typography Pairing

Hallmark selects from **seven tone-pairings** defined in [`skills/hallmark/references/typography.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/typography.md):

| Tone | Character |
|------|-----------|
| Editorial | Classic, authoritative |
| Technical | Utilitarian, precise |
| Brutalist | Raw, confrontational |
| Soft | Gentle, approachable |
| Luxury | Refined, expensive |
| Playful | Energetic, informal |
| Austere | Minimal, severe |
| Workshop | Handmade, craft-focused |

**Variable fonts are preferred**. The chosen display and body fonts are recorded for the final stamp.

### Step 4: Macrostructure (Optional)

If your brief demands unique layout architecture, Hallmark injects a bespoke structure here. Otherwise, the default macrostructure applies. Reference implementations live in [`skills/hallmark/references/custom-theme.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/custom-theme.md) under the Structure section.

### Step 5: Preview Block

Before emitting any CSS or HTML, Hallmark renders a **plain-text preview** for your approval:

```

Palette:
  Paper – LCH(95% 0.02 225)
  Accent – LCH(70% 0.12 225)
  Neutral – LCH(50% 0.01 225)

Fonts:
  Display – Cormorant Garamond (Luxury, free)
  Body – EB Garamond (Luxury, free)

Stamp:
  /* Hallmark · macrostructure: custom · tone: Luxury · anchor hue: 225 */

```

Sample formats are cataloged in [`skills/hallmark/references/preview-examples.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/preview-examples.md).

### Step 6: Stamp & Log

The first line of your generated stylesheet contains a **machine-readable comment** that records:

- Macrostructure name
- Tone selection
- Anchor hue value
- Complete palette values
- Font pairing

This stamp enables **diversification enforcement** on subsequent runs—Hallmark reads it back to avoid repeating similar themes.

## Complete Implementation Example

Here's a runnable CSS output from the bespoke depth pipeline, generated for a "Luxury" tone with anchor hue 225:

```css
/* Hallmark · macrostructure: custom · tone: Luxury · anchor hue: 225 */
:root {
  /* OKLCH palette generated from the brand anchor hue */
  --paper-oklch: oklch(95% 0.02 225);
  --accent-oklch: oklch(70% 0.12 225);
  --neutral-oklch: oklch(50% 0.01 225);

  /* Font pair chosen for a "Luxury" tone */
  --display-font: "Cormorant Garamond", serif;   /* free */
  --body-font:    "EB Garamond", serif;         /* free */
}

body {
  background-color: lch(var(--paper-oklch));
  color: lch(var(--neutral-oklch));
  font-family: var(--body-font);
}

h1, h2, h3 {
  font-family: var(--display-font);
  color: lch(var(--accent-oklch));
}

```

The OKLCH color space ensures perceptually uniform lightness, making your palette robust across display conditions and accessibility requirements.

## Key Source Files for Custom Theme Development

| File Path | Purpose |
|-----------|---------|
| [`skills/hallmark/references/custom-theme.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/custom-theme.md) | Complete protocol: signal detection, construction steps, preview format, stamp specification |
| [`skills/hallmark/SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md) | High-level flowchart with custom-branch decision logic |
| [`skills/hallmark/references/color.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/color.md) | OKLCH palette generation, hue bands, chroma caps |
| [`skills/hallmark/references/typography.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/typography.md) | Seven tone-pairings, variable font handling |
| [`skills/hallmark/references/anti-patterns.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/anti-patterns.md) | Global constraint checks applied to all themes |
| [`skills/hallmark/references/preview-examples.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/preview-examples.md) | Sample preview blocks for validation |

## Summary

- **Signal detection** triggers the custom branch—single adjectives won't; explicit asks, brand colors, or multi-word vibes will
- **Bespoke depth** follows six locked steps: vibe capture → palette generation → typography pairing → optional macrostructure → preview approval → stamped output
- **Global constraints** from anti-patterns.md and color.md apply at every depth level
- **The stamp comment** enables reproducibility and diversification across multiple theme generations
- All implementation details are documented in [`skills/hallmark/references/custom-theme.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/custom-theme.md) and companion reference files

## Frequently Asked Questions

### What makes a brief qualify for custom theme treatment instead of the catalog?

Hallmark requires one of three signals: an explicit request for custom work, a specific anchor color value, or a multi-attribute description that doesn't match any catalog theme. Single adjectives like "minimal" or "bold" are treated as tone modifiers on catalog themes, not custom build triggers.

### Why does Hallmark use OKLCH instead of HSL or HEX for custom palettes?

OKLCH provides perceptually uniform lightness, meaning a 10% lightness change looks equally distinct whether you're in yellows or blues. This ensures your palette maintains consistent contrast relationships and accessibility compliance across all hue selections, as enforced by the rules in [`skills/hallmark/references/color.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/color.md).

### Can I override Hallmark's typography pairings in a custom theme?

No—the seven tone-pairings in [`skills/hallmark/references/typography.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/typography.md) are fixed sets. However, selecting a tone unlocks the full flexibility within that pairing, including variable font axes and weight ranges. The system prioritizes free, open-source fonts to ensure your custom theme remains deployable without licensing friction.

### What happens if I regenerate a custom theme with similar parameters?

Hallmark reads the stamp from your previous stylesheet and applies diversification logic to avoid near-duplicates. The anchor hue may shift slightly, or the typography pairing may rotate within the same tone family, ensuring each generation produces perceptibly distinct results while maintaining brand coherence.