deep-dive

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

August 8, 2026 Nutlope/hallmark ↗

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. 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 (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, 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, 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:

Paper‑band (background texture/color)
Display‑style (typographic treatment)
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. For example, the Lumen theme (Atmospheric cluster) and Hum theme (Playful cluster) define concrete token values:

/* 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 data-theme="cobalt">
  <!-- Hallmark injects Modern‑Minimal tokens -->
</html>

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

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.
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 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. 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. 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 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 (lines 9‑10).

Have a question about this repo?

These articles cover the highlights, but your codebase questions are specific. Give your agent direct access to the source. Share this with your agent to get started:

Share the following with your agent to get started:

curl -s "https://instagit.com/install.md"

Add to your MCP client configuration:

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}

Ask your agent:

"Use Instagit MCP to understand how Nutlope/hallmark works."

Works with

Claude Codex Cursor VS Code OpenClaw Any MCP Client

Maintain an open-source project? Get it listed too →