# How Hallmark Catalog Themes Map to Genre Clusters: The 20‑Theme System Explained

> Discover how Hallmark's 20 catalog themes connect to four genre clusters. Understand the system that ensures diverse and engaging selections for every run.

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

---

**Hallmark’s 20 catalog themes are statically grouped into four genre clusters—Atmospheric (5 themes), Modern‑Minimal (2 themes), Playful (1 theme), and Editorial (12 themes)—and the system rotates selections within each cluster to ensure consecutive runs differ in paper‑band, display‑style, or accent‑hue.**

The Hallmark design system organizes visual output through a fixed catalog of 20 predefined themes defined in [`skills/hallmark/references/custom-theme.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/custom-theme.md). Each theme maps to a specific genre cluster that drives the automated Design flow, ensuring structural variety while maintaining coherent aesthetic families.

## The Four Genre Clusters and Their 20 Themes

The theme‑to‑genre mapping is hard‑coded in the skill description at [`skills/hallmark/SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md) (lines 240‑284). During the Design flow, Hallmark detects the brief’s genre, then selects a theme from the corresponding cluster.

### Atmospheric Cluster (5 Themes)

Themes in this cluster emphasize moody, ambient aesthetics:

- **Bloom**
- **Midnight**
- **Terminal**
- **Aurora**
- **Lumen**

These five themes share a unified atmospheric sensibility and rotate among themselves when the brief signals an atmospheric genre.

### Modern‑Minimal Cluster (2 Themes)

This cluster offers clean, restrained visuals:

- **Coral**
- **Cobalt**

When the brief indicates a modern‑minimal direction, Hallmark selects between these two themes.

### Playful Cluster (1 Theme)

A single‑theme cluster for lighthearted, energetic outputs:

- **Hum**

Hum is the exclusive choice when the genre detection identifies a playful brief.

### Editorial Cluster (12 Themes)

The largest cluster, covering sophisticated, content‑forward designs:

- **Specimen**
- **Atelier**
- **Brutal**
- **Garden**
- **Newsprint**
- **Studio**
- **Manifesto**
- **Almanac**
- **Riso**
- **Sport**
- **Editorial**
- **Carnival**

These twelve themes provide extensive diversification options for editorial‑genre briefs.

## How Theme Selection Works in the Design Flow

### Genre Detection and Cluster Assignment

According to [`skills/hallmark/SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md), the Design flow (the default verb) first analyzes the brief to determine its genre—**playful**, **modern‑minimal**, **atmospheric**, or **editorial**. It then restricts theme selection to the corresponding cluster:

- Atmospheric → one of Bloom, Midnight, Terminal, Aurora, Lumen
- Modern‑Minimal → Coral or Cobalt
- Playful → Hum
- Editorial → any of the twelve editorial themes

### The Diversification Rule

As documented in [`skills/hallmark/references/custom-theme.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/custom-theme.md), the system enforces a **diversification rule** that prevents visual repetition. The chosen theme must differ from the previous run on at least one of three axes:

1. **Paper‑band** (background texture/color)
2. **Display‑style** (typographic treatment)
3. **Accent‑hue** (color accents)

This ensures that consecutive builds within the same genre cluster still produce distinct visual outputs.

## Technical Implementation in CSS

### Theme Tokens in tokens.css

Each theme is implemented as a CSS custom property block under a `[data‑theme="…"]` selector in [`site/css/tokens.css`](https://github.com/Nutlope/hallmark/blob/main/site/css/tokens.css). For example, the Lumen theme (Atmospheric cluster) and Hum theme (Playful cluster) define concrete token values:

```css
/* Atmospheric cluster example */
[data-theme="lumen"] {
  --color-paper: oklch(98% 0.01 100);
  --color-accent-1: oklch(75% 0.15 200);
  --font-display: "Inter", sans-serif;
}

/* Playful cluster example */
[data-theme="hum"] {
  --color-paper: oklch(95% 0.04 95);   /* cream paper */
  --color-accent-1: oklch(70% 0.12 30); /* pear‑yellow */
  --font-display: "Plus Jakarta Sans", sans-serif;
}

```

All components consume these tokens via `var(--color-paper)` and `var(--font-display)`, rather than hard‑coding values, enabling instant theme switches.

### Runtime Theme Application

Themes are applied at the HTML root level:

```html
<html data-theme="cobalt">
  <!-- Hallmark injects Modern‑Minimal tokens -->
</html>

```

Dynamic switching is supported through JavaScript manipulation of the `dataset` property:

```javascript
function setTheme(name) {
  document.documentElement.dataset.theme = name;
}
setTheme('aurora'); // switches to Atmospheric cluster theme

```

## Summary

- Hallmark maintains a **fixed catalog of 20 themes** defined in [`skills/hallmark/references/custom-theme.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/custom-theme.md).
- Themes map to **four genre clusters**: Atmospheric (5), Modern‑Minimal (2), Playful (1), and Editorial (12).
- The **Design flow** detects genre from the brief, then selects a theme from the appropriate cluster.
- A **diversification rule** enforces variation on paper‑band, display‑style, or accent‑hue axes to prevent repetitive output.
- Theme definitions live in [`site/css/tokens.css`](https://github.com/Nutlope/hallmark/blob/main/site/css/tokens.css) under `[data‑theme]` selectors, consumed by components via CSS custom properties.

## Frequently Asked Questions

### What is the difference between a genre and a theme in Hallmark?

**A genre is a high‑level aesthetic category** (atmospheric, modern‑minimal, playful, editorial) detected from the brief content, while **a theme is a concrete design system** combining specific paper‑band, display‑style, and accent‑hue values. The genre determines which cluster of themes is eligible for selection.

### How does Hallmark prevent the same theme from appearing in consecutive runs?

The system implements a **diversification rule** documented in [`skills/hallmark/references/custom-theme.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/custom-theme.md). When selecting a theme from a genre cluster, Hallmark ensures the choice differs from the previous run on at least one of three axes: paper‑band, display‑style, or accent‑hue. This guarantees visual variety even when processing similar briefs.

### Can I force a specific theme regardless of genre detection?

Yes, by bypassing the default Design flow and specifying a theme directly via the `data‑theme` attribute or JavaScript API. However, doing so overrides the automatic genre‑cluster logic defined in [`skills/hallmark/SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md). Custom themes outside the 20‑theme catalog require explicit configuration in the custom‑theme protocol.

### Where are individual theme specifications documented?

Detailed specifications for each catalog theme reside in `skills/hallmark/references/themes/`. For example, [`skills/hallmark/references/themes/lumen.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/themes/lumen.md) contains the complete palette, typography, and structural rules for the Lumen theme. The aggregate list of all 20 themes appears in [`skills/hallmark/references/custom-theme.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/custom-theme.md) (lines 9‑10).