# Hallmark's 21 Catalog Themes: The Complete Reference Guide

> Explore Hallmark's 21 catalog themes, the complete reference guide. Discover the default design system used by Hallmark for a seamless visual experience. Learn more now.

- Repository: [Hassan El Mghari/hallmark](https://github.com/Nutlope/hallmark)
- Tags: api-reference
- Published: 2026-08-16

---

**Hallmark ships with 21 pre-defined visual themes** (collectively called the *2I catalog*) that serve as the default design system when no custom look is requested.

The Hallmark open-source framework by Nutlope provides a **named-theme catalog** that automatically applies consistent visual styling to generated pages. These themes are defined in [[`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) and referenced from [[`SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/SKILL.md)](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md). Each theme combines three axis values—**paper-band**, **display-style**, and **accent-hue**—to create distinct visual personalities.

---

## Complete List of Hallmark Catalog Themes

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

---

## How Hallmark Selects a Catalog Theme

### Default Route: Automatic Catalog Selection

When a brief contains **no explicit "custom" signal**—no brand-colour request, no multi-attribute vibe, no "make it from scratch" instruction—Hallmark silently selects one of the 21 catalog themes.

The selection follows a **diversification rule**: consecutive runs must differ on at least one of the three axes (paper-band, display-style, accent-hue). This prevents the same theme from appearing back-to-back.

### Signal-Driven Branch: Custom Theme Flow

When the user mentions:
- A specific brand colour
- A vibe that doesn't map cleanly to any catalog theme
- An explicit request for a custom look

Hallmark switches to the **custom-theme** flow documented in [`references/custom-theme.md`](https://github.com/Nutlope/hallmark/blob/main/references/custom-theme.md).

### Manual Theme Selection Strategy

To choose the right catalog theme intentionally:

- **Match the genre** — Each genre clusters preferred themes. *Hum* is the sole "playful" theme; *Coral* and *Cobalt* form the "modern-minimal" cluster; *Atelier* and *Studio* serve "premium" contexts.

- **Align tone with axis values** — Warm-cream + italic-serif suggests *Specimen*; dark night + classical-serif-lowercase points to *Lumen*; vibrant multi-accent indicates *Hum* or *Carnival*.

- **Respect rotation history** — Hallmark stores the last used theme in [`.hallmark/log.json`](https://github.com/Nutlope/hallmark/blob/main/.hallmark/log.json). Select a theme whose axis values differ from that entry to satisfy the diversification rule.

---

## Working with Hallmark Catalog Themes Programmatically

### Inspect the Theme List

```javascript
// Read the catalog list programmatically from the source
import fs from 'fs';
import path from 'path';

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

// Extract theme identifiers (formatted as bold list items)
const themeLines = catalogFile.match(/^ *- \*\*([A-Za-z]+)\*\*/gm);
const themes = themeLines?.map(l => l.replace(/^ *- \*\*|\*\*$/g, ''));

console.log('Hallmark catalog themes:', themes);
// Output: ['Specimen', 'Midnight', 'Brutal', ... 'Hum', 'Grid']

```

### Force a Specific Theme

```bash

# Set environment variable to override automatic selection

export HALLMARK_FORCE_THEME=Hum
npm run build   # or `vercel dev` depending on setup

```

### Declare Theme in Page Markup

```html
<!-- Explicit theme reference in page-level comment -->
<!-- Hallmark · macrostructure: Catalogue · theme: Bloom -->
<link rel="stylesheet" href="/site/css/tokens.css" data-theme="bloom">

```

The actual CSS token sets for every theme live 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), using `[data-theme="..."]` selectors.

---

## Key Source Files

| File | Purpose | Location |
|------|---------|----------|
| [`custom-theme.md`](https://github.com/Nutlope/hallmark/blob/main/custom-theme.md) | Defines all 21 themes and custom-theme flow | [[`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) |
| [`SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/SKILL.md) | Documents selection algorithm and diversification rule | [[`skills/hallmark/SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md)](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md) |
| [`tokens.css`](https://github.com/Nutlope/hallmark/blob/main/tokens.css) | CSS token sets for each theme | [[`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) |
| [`_tests/README.md`](https://github.com/Nutlope/hallmark/blob/main/_tests/README.md) | Examples of pages built with different themes | [[`site/_tests/README.md`](https://github.com/Nutlope/hallmark/blob/main/site/_tests/README.md)](https://github.com/Nutlope/hallmark/blob/main/site/_tests/README.md) |
| [`recipes.md`](https://github.com/Nutlope/hallmark/blob/main/recipes.md) | Combining themes with macrostructures | [[`docs/recipes.md`](https://github.com/Nutlope/hallmark/blob/main/docs/recipes.md)](https://github.com/Nutlope/hallmark/blob/main/docs/recipes.md) |

---

## Summary

- Hallmark provides **21 catalog themes** ranging from *Specimen* to *Grid*, each with distinct paper-band, display-style, and accent-hue combinations.

- The **2I catalog** serves as the default when briefs lack custom signals; selection follows a **diversification rule** preventing immediate repetition.

- Themes map to **genre clusters** (playful, modern-minimal, editorial, premium, etc.) for intuitive manual selection.

- Source definitions live in **[`custom-theme.md`](https://github.com/Nutlope/hallmark/blob/main/custom-theme.md)** with implementation in **[`tokens.css`](https://github.com/Nutlope/hallmark/blob/main/tokens.css)** and logic in **[`SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/SKILL.md)**.

- Developers can **inspect**, **force**, or **declare** themes programmatically using environment variables or markup comments.

---

## Frequently Asked Questions

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

Check [`.hallmark/log.json`](https://github.com/Nutlope/hallmark/blob/main/.hallmark/log.json) in your project root. This file stores the last used theme identifier, rotation history, and which axis values were applied. You can also grep the generated HTML for `data-theme` attributes or the Hallmark comment signature `<!-- Hallmark · theme: ... -->`.

### Can I add my own theme to the 21 catalog themes?

No—the 21 catalog themes are fixed in the upstream repository. For custom visual needs, use the **custom-theme flow** documented in [`references/custom-theme.md`](https://github.com/Nutlope/hallmark/blob/main/references/custom-theme.md). This accepts arbitrary colour palettes, typography choices, and axis overrides without modifying the core catalog.

### What happens if two consecutive briefs would select the same theme?

The **diversification rule** intervenes. Hallmark compares the candidate theme against [`.hallmark/log.json`](https://github.com/Nutlope/hallmark/blob/main/.hallmark/log.json) and rejects it if it matches on all three axes (paper-band, display-style, accent-hue). The selector then rotates to the next valid theme in the internal sequence, ensuring visual variety across builds.

### Which theme should I choose for a developer documentation site?

**Terminal** is purpose-built for this use-case: dark terminal paper-band, monospace display style, and single green accent. For API products with a modern landing page, **Cobalt** (dark blue paper-band, geometric-sans, cobalt accent) provides stronger commercial appeal while retaining technical credibility.