# Hallmark’s 21 Catalog Themes Explained (Plus How to Choose the Right One)

> Discover Hallmark's 21 catalog themes and learn how to select the perfect one for your needs. Find the right visual system for your next project with our expert guide.

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

---

**Hallmark provides 21 pre-defined catalog themes—identified by short two-letter or word identifiers in [`custom-theme.md`](https://github.com/Nutlope/hallmark/blob/main/custom-theme.md)—that serve as the default visual system when a brief doesn't request custom styling.**

This visual system, sometimes called the *21 catalog* or *2I catalog* due to its compact identifiers, powers Hallmark's automated theme selection. Each theme combines three tunable axes—**paper-band** (background warmth), **display-style** (typography family), and **accent-hue** (color strategy)—to create distinct moods without requiring custom CSS token generation.

## The Complete List: All 21 Hallmark Catalog Themes

The canonical source for these themes is [[`skills/hallmark/references/custom-theme.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/custom-theme.md)](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/custom-theme.md). Below is the full catalog with their defining characteristics:

| Theme | Paper-Band | Display Style | Accent Hue | Best For |
|-------|-----------|---------------|-----------|----------|
| **Specimen** | Warm cream | Italic-serif | Single (terra) | Editorial, magazines |
| **Midnight** | Dark paper | Roman-serif | Single (deep blue) | Night-mode, tech |
| **Brutal** | Concrete grey | Geometric-sans | Duo-tone (red/black) | High-impact advertising |
| **Garden** | Light oat | Classic-serif | Duo-tone (green) | Nature, sustainability |
| **Atelier** | Soft ivory | Instrument-serif | Multi-accent (gold) | Premium product showcases |
| **Newsprint** | News-gray | Serif-sentence | Single (red) | Blogs, news sites |
| **Terminal** | Dark terminal | Monospace | Single (green) | Developer tools, CLIs |
| **Manifesto** | White | Geometric-sans | Duo-tone (orange) | Activist landing pages |
| **Almanac** | Cream | Serif-sentence | Single (blue) | Calendars, timelines |
| **Sport** | Light slate | Bold-sans | Duo-tone (team colors) | Sports portals |
| **Studio** | Warm paper | Instrument-serif | Single (forest green) | Creative agency sites |
| **Riso** | Paper-like | Italic-serif | Duo-tone (magenta) | Print-inspired layouts |
| **Bloom** | Warm-cream | Rounded-sans | Multi-accent (pink/cyan) | Playful, learning apps |
| **Coral** | Cream | — | Single (coral) | Modern-minimal sites |
| **Cobalt** | Dark blue | Geometric-sans | Single (cobalt) | API product landings |
| **Aurora** | Light night | Serif-sentence | Duo-tone (purple) | Atmospheric storytelling |
| **Editorial** | Neutral paper | Classic-serif | Single (black) | Long-form articles |
| **Carnival** | Light paper | Rounded-sans | Multi-accent (drops) | Vibrant brand pages |
| **Lumen** | Dark night | Classical-serif-lowercase | Single (yellow) | Low-light catalogs |
| **Hum** | Cream (pear-yellow) | Rounded-sans | Multi (pear/sky/coral) | Friendly tools, habit trackers |
| **Grid** | Neutral | Geometric-sans | Single (steel) | Institutional indexes |

Three themes deserve special attention for their unique positioning:

- **Hum** — the *only* catalog theme with **three simultaneous accent colors** (pear-yellow, sky-cyan, coral-red), making it irreplaceable for "friendly, curious" applications
- **Coral** and **Cobalt** — the "modern-minimal" pair; choose **Coral** for light backgrounds, **Cobalt** for dark
- **Terminal** — the sole **monospace** display style, essential for developer-facing products

## How to Choose a Catalog Theme (3 Methods)

### Method 1: Match by Genre Cluster

Each genre maps to a preferred theme subset. According to [[`SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/SKILL.md)](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md), these clusters guide automatic selection:

| Genre | Primary Themes | Escape Hatch |
|-------|---------------|--------------|
| Playful | **Hum**, **Bloom**, **Carnival** | Custom if needing 4+ accents |
| Modern-minimal | **Coral**, **Cobalt**, **Grid** | Custom if brand color outside single-accent range |
| Atmospheric | **Aurora**, **Lumen**, **Midnight** | Custom for animated gradients |
| Editorial | **Specimen**, **Editorial**, **Newsprint** | Custom for bespoke type pairings |
| Technical/developer | **Terminal**, **Grid**, **Cobalt** | Custom for syntax-highlighted code blocks |

### Method 2: Decode the Three Axes

When a brief describes visual intent without naming a theme, map its language to Hallmark's axes:

1. **Paper-band** — describes warmth and value
   - "Warm," "inviting," "vintage" → warm-cream, cream, soft-ivory
   - "Clean," "clinical," "modern" → white, neutral, light-slate
   - "Dark mode," "night," "moody" → dark-paper, dark-night, dark-terminal, dark-blue

2. **Display-style** — describes typography personality
   - "Authoritative," "literary" → classic-serif, serif-sentence
   - "Technical," "precise" → monospace
   - "Humanist," "approachable" → rounded-sans, italic-serif
   - "Luxury," "editorial" → instrument-serif

3. **Accent-hue** — describes color energy
   - "Restrained," "single brand color" → single-accent
   - "Dynamic," "high contrast" → duo-tone
   - "Festive," "multi-brand" → multi-accent

### Method 3: Respect the Diversification Rule

Hallmark's automatic selector enforces a **diversification rule**: consecutive runs must differ on at least one axis. When choosing manually, check [`.hallmark/log.json`](https://github.com/Nutlope/hallmark/blob/main/.hallmark/log.json) for the last-used theme:

```json
{
  "lastRun": {
    "theme": "Hum",
    "paperBand": "cream",
    "displayStyle": "rounded-sans",
    "accentHue": "multi"
  }
}

```

Avoid selecting another **cream + rounded-sans + multi** theme immediately. **Bloom** shares two axes with **Hum**; **Carnival** shares the multi-accent hue. Better choices: **Brutal** (concrete-grey, geometric-sans, duo-tone) or **Specimen** (warm-cream, italic-serif, single-accent)—each differs on two or three axes.

## Forcing a Specific Theme in Code

While Hallmark auto-selects from the 21 catalog themes by default, you can override this behavior for testing or explicit brief requirements.

### Inspect Available Themes Programmatically

```javascript
// Extract theme IDs from the canonical source
import fs from 'fs';
import path from 'path';

const catalogPath = path.resolve(
  __dirname,
  'skills/hallmark/references/custom-theme.md'
);
const catalog = fs.readFileSync(catalogPath, 'utf8');

// Theme identifiers appear as: - **ThemeName**
const themeMatches = catalog.match(/^ *- \*\*([A-Za-z]+)\*\*/gm);
const themes = themeMatches.map(m => m.replace(/^ *- \*\*|\*\*$/g, ''));

console.log(themes); 
// ['Specimen','Midnight','Brutal','Garden','Atelier','Newsprint',
//  'Terminal','Manifesto','Almanac','Sport','Studio','Riso',
//  'Bloom','Coral','Cobalt','Aurora','Editorial','Carnival',
//  'Lumen','Hum','Grid']

```

### Override via Environment Variable

```bash

# Force Hum theme for local development

export HALLMARK_FORCE_THEME=Hum

# Verify the override took effect

npm run build 2>&1 | grep -i "theme.*Hum"

```

### Declare in Page Metadata

```html
<!-- Hallmark macrostructure comment triggers theme selection -->
<!-- Hallmark · macrostructure: Catalogue · theme: Bloom -->

<!-- CSS tokens load via data-attribute selector -->
<link rel="stylesheet" href="/site/css/tokens.css" data-theme="bloom">

```

The actual CSS implementation lives in [[`site/css/tokens.css`](https://github.com/Nutlope/hallmark/blob/main/site/css/tokens.css)](https://github.com/Nutlope/hallmark/blob/main/site/css/tokens.css), where each theme maps to a `[data-theme="..."]` selector block with full token sets.

## When to Skip the Catalog (Custom Theme Flow)

Hallmark exits the 21-catalog system and enters **custom-theme generation** when your brief contains any of these signals, as documented in [`custom-theme.md`](https://github.com/Nutlope/hallmark/blob/main/custom-theme.md):

- **Explicit brand color** outside the catalog's predefined palettes
- **Multi-attribute vibe** that doesn't map cleanly (e.g., "dark mode + playful + luxury")
- **Direct request** for custom styling ("make it from scratch," "unique look")

The custom flow generates ad-hoc tokens rather than selecting from the 21 pre-defined sets.

## Summary

- **Hallmark's 21 catalog themes** provide complete visual systems through three tunable axes: paper-band, display-style, and accent-hue
- **Default behavior**: automatic selection with diversification rules to prevent repetition
- **Manual selection**: match genre clusters, decode axis language from briefs, or check rotation history in [`.hallmark/log.json`](https://github.com/Nutlope/hallmark/blob/main/.hallmark/log.json)
- **Override paths**: environment variable `HALLMARK_FORCE_THEME`, HTML comment metadata, or programmatic theme injection
- **Escalation trigger**: brand colors, complex vibes, or explicit custom requests activate the alternative custom-theme flow

## Frequently Asked Questions

### How do I see which theme Hallmark actually selected for my build?

Check [`.hallmark/log.json`](https://github.com/Nutlope/hallmark/blob/main/.hallmark/log.json) after running `npm run build`. The `lastRun.theme` field shows the applied catalog theme. For debugging, add `DEBUG=hallmark:*` to your environment to see selection logic in stdout.

### Can I use multiple catalog themes on different pages of the same site?

Yes. Hallmark supports per-page theme overrides via HTML comments (`<!-- Hallmark · theme: Coral -->`) or route-based configuration in your build pipeline. The diversification rule only applies within consecutive runs of the same build context, not across permanently deployed pages.

### Why does the same brief sometimes produce different themes?

Hallmark's **diversification rule** intentionally varies consecutive selections. If you need deterministic output, set `HALLMARK_FORCE_THEME` or include an explicit theme declaration in your brief. Otherwise, expect rotation among genre-appropriate themes.

### What's the difference between a "theme" and a "macrostructure" in Hallmark?

**Theme** controls visual tokens (colors, typography, spacing). **Macrostructure** controls layout patterns (Catalogue, Edition, Index, etc.). They compose independently—you can use **Hum** theme with **Catalogue** macrostructure, or **Terminal** theme with **Index** macrostructure. See [[`docs/recipes.md`](https://github.com/Nutlope/hallmark/blob/main/docs/recipes.md)](https://github.com/Nutlope/hallmark/blob/main/docs/recipes.md) for valid combinations.