# What Are Hallmark's 20 Catalog Themes and How Do They Differ From Custom Themes?

> Discover Hallmark's 20 catalog themes and learn how they differ from custom themes. Understand automatic rotations and on-demand generation for unique palettes.

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

---

**Hallmark provides 20 pre-defined catalog themes that rotate automatically through combinations of paper-band color, accent hue, and typography, while custom themes are generated on-demand when a brief requires unique palettes or layouts outside the fixed set.**

The Nutlope/hallmark repository implements a controlled design system that routes users through either **catalog themes** or **custom themes** based on brief requirements. These **20 catalog themes** represent the default design system and are defined in [`skills/hallmark/SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md) and cross-referenced in [`skills/hallmark/references/custom-theme.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/custom-theme.md), providing pre-authorized visual identities that ensure consistent quality through 57 automated slop-test gates.

## The 20 Hallmark Catalog Themes

The complete catalog consists of named themes that map to specific CSS token sets in [`site/css/tokens.css`](https://github.com/Nutlope/hallmark/blob/main/site/css/tokens.css) under `[data-theme="..."]` selectors. Each theme varies one or more of the three diversification axes: paper-band color, accent hue, and display-style typography.

- **Specimen**: Classical-serif-lowercase headline, neutral paper, single-accent restraint.
- **Atelier**: Warm-cream paper, italic-serif headline, subtle accent.
- **Brutal**: Dark paper, bold geometric-sans headline, high-contrast accent.
- **Garden**: Light-cream paper, rounded-sans headline, pastel accent.
- **Newsprint**: Newspaper-style paper, mixed-case serif headline, modest accent.
- **Terminal**: Monospace-heavy paper, terminal-type headline, neon accent.
- **Manifesto**: Strong-contrast paper, geometric-sans headline, single accent.
- **Almanac**: Structured paper, clean serif headline, muted accent.
- **Riso**: Vibrant-paper, experimental headline, saturated accent.
- **Sport**: Dynamic paper, athletic-type headline, energetic accent.
- **Bloom**: Atmospheric, warm-light paper, soft-rounded headline.
- **Coral**: Modern-minimal, single-accent restraint, crisp headline.
- **Cobalt**: Cool-blue paper, geometric-sans headline, deep accent.
- **Aurora**: Night-time paper, luminous accent, sleek headline.
- **Editorial**: Editorial-grade paper, balanced serif/sans headline, neutral accent.
- **Carnival**: Saturated-duo-tone paper, bold headline, vivid accent (six drops).
- **Lumen**: The only lowercase-headline catalog theme, classic-serif-lowercase.
- **Hum**: The sole playful catalog theme, rounded-sans headline with multi-accent support.
- **Midnight**: Dark-mode variant of the editorial family, deep paper, low-key accent.
- **Studio**: Instrument Serif plus Geist fonts, forest-green accent, closest studio-style theme.

Individual theme specifications reside in dedicated files such as [`themes/lumen.md`](https://github.com/Nutlope/hallmark/blob/main/themes/lumen.md) and [`themes/hum.md`](https://github.com/Nutlope/hallmark/blob/main/themes/hum.md), detailing the exact OKLCH color values and font pairings.

## How Catalog Themes Differ From Custom Themes

While both pathways share the same underlying quality constraints, they differ fundamentally in origin, scope, and persistence.

### Origin and Authorization

**Catalog themes** constitute a closed, fixed set of 20 pre-authorized designs maintained by the Hallmark maintainers. **Custom themes**, conversely, are generated on-the-fly when a brief contains a "custom signal"—such as an explicit brand color, multi-attribute vibe request, or bespoke layout requirement.

### Scope of Variation

Catalog themes vary only the three diversification axes: paper-band color, accent hue, and display-style typography. The underlying macrostructure, component catalogue, and motion rules remain constant. Custom themes offer two scope levels:

- **Tuned**: Palette plus font pairing only.
- **Bespoke**: Palette plus type plus layout plus composition—effectively a unique design built from first principles.

### Selection and Rotation Logic

The system applies a **diversification rule** to catalog themes: it automatically selects a theme that differs on at least one of the three axes from the previous generation run, ensuring visual variety without user intervention. Custom themes bypass automatic rotation; instead, the system asks the user to confirm the custom route before constructing the theme based on the brief's specific signals.

### Persistence and Logging

Catalog runs record simply as `theme: <NAME>` in the project stamp, allowing the next run to read the theme name and apply the diversification rule. Custom themes require verbose logging:

```yaml
theme: custom (vibe: "moss-tinted paper with dusty-pink accent")

```

This entry captures the exact OKLCH values, font families, and diversification axes to enable rotation checks across subsequent custom runs.

### Extensibility and Lifecycle

The catalog is immutable—new themes are added only by repository maintainers and become permanent entries. Custom themes are ephemeral; they live only in the generated page’s `:root` CSS and are discarded after the build, never extending the catalog itself.

## Technical Implementation in the Codebase

Theme values are implemented through CSS custom properties in [`site/css/tokens.css`](https://github.com/Nutlope/hallmark/blob/main/site/css/tokens.css). For example, the Brutal theme applies specific OKLCH values to ensure high-contrast rendering:

```css
/* From site/css/tokens.css */
[data-theme="brutal"] {
  --paper-band: oklch(20% 0.01 260);
  --accent-hue: oklch(70% 0.2 250);
  --display-style: "Geist Sans", sans-serif;
}

```

Both catalog and custom themes must pass all **57 slop-test gates**—automated validation checks that verify contrast ratios, motion safety, and typographic hierarchy. Custom themes construct their `:root` tokens dynamically during the build process, inserting the calculated values directly into the generated markup rather than referencing a predefined selector.

## Summary

- Hallmark ships with **20 catalog themes** ranging from Specimen to Studio, each defined by specific paper, accent, and typography combinations in [`skills/hallmark/SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md).
- Catalog themes rotate automatically via the **diversification rule**, which ensures consecutive runs differ on at least one visual axis.
- **Custom themes** trigger only when briefs contain explicit custom signals, offering tuned (palette/font) or bespoke (full layout) options.
- Catalog themes persist as simple name stamps, while custom themes log full OKLCH values and font families for rotation tracking.
- Both theme types are subject to the same **57 slop-test gates**, ensuring all generated output meets Hallmark’s design standards regardless of origin.

## Frequently Asked Questions

### How does the diversification rule work for catalog themes?

The diversification rule is an automatic rotation system that selects a catalog theme differing on at least one of the three axes—paper-band color, accent hue, or display-style typography—from the theme used in the previous generation run. This ensures visual variety across consecutive builds without requiring manual theme selection by the user.

### Can I add my own theme to the Hallmark catalog?

No. The catalog of 20 themes is **closed** and immutable. New themes are added only by Hallmark maintainers through updates to [`skills/hallmark/SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md) and the corresponding CSS token definitions. If you need a unique visual identity, you must use the **custom theme** workflow rather than extending the catalog.

### What triggers the custom theme workflow instead of a catalog theme?

The custom theme workflow activates when the system detects a "custom signal" in the brief. These signals include requests for explicit brand colors, multi-attribute vibe descriptions (e.g., "moss-tinted paper with dusty-pink accent"), or bespoke layout requirements. Upon detection, the system prompts the user to confirm the custom route before generating the unique theme.

### Do custom themes undergo the same quality checks as catalog themes?

Yes. Both catalog and custom themes are validated against the **57 slop-test gates** that check contrast ratios, motion safety, and component hierarchy. Custom themes must construct values that pass these same gates; the only difference is that custom themes generate their CSS token values dynamically at build time rather than pulling from the predefined `[data-theme="..."]` selectors in [`site/css/tokens.css`](https://github.com/Nutlope/hallmark/blob/main/site/css/tokens.css).