# How Hallmark Enforces Theme Diversification: A Technical Deep Dive

> Discover how Hallmark enforces theme diversification using a JSON log and algorithmic rotation to ensure varied content. Learn about drop selection and categorical distance. Read the technical deep dive.

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

---

**Hallmark enforces theme diversification by maintaining a JSON log at [`/.hallmark/log.json`](https://github.com/Nutlope/hallmark/blob/main//.hallmark/log.json) that records recent theme and drop selections, then algorithmically rotates drops and selects categorically distant themes on subsequent builds unless an explicit override is specified in the brief.**

In the Nutlope/hallmark repository, theme diversification is a core discipline that prevents visual monotony by ensuring design tokens rotate systematically across builds. The system treats each theme as a packaged set of tokens—including palette, type-stack, motion, and optional drop variants—and consults a diversification log to enforce variety at the catalog selection stage.

## What Is Theme Diversification in Hallmark?

A **theme** in Hallmark is not merely a color scheme but a comprehensive package of design tokens. Many themes include multiple **drops** (variants), such as Lumen’s Night versus Day modes or Carnival’s six distinct drops.

When Hallmark generates a page, it records the chosen theme and drop in [`/.hallmark/log.json`](https://github.com/Nutlope/hallmark/blob/main//.hallmark/log.json). This **diversification log** serves as the system’s memory, enabling the build process to enforce variety by comparing current selections against recent history.

## How Hallmark Enforces Theme Diversification

The enforcement mechanism operates through four distinct rules that work together to prevent "theme drift" while respecting explicit brief requirements.

### Drop Rotation for Multi-Drop Themes

For themes with multiple drops, Hallmark implements a strict rotation policy. According to the "Drop rotation rule" documented in [`skills/hallmark/references/themes/lumen.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/themes/lumen.md) (lines 58-62), the system must select a drop that has not appeared in the recent *N* entries of the log.

The Carnival theme demonstrates this with six distinct drops. As noted in [`skills/hallmark/references/themes/carnival.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/themes/carnival.md) (lines 11-15), the system rotates through these drops to ensure visual variety across consecutive builds.

### Categorical Distance Between Themes

When the brief does not specify a theme, Hallmark prefers selections that are *categorically distant* from recent builds. The Hum theme file at [`skills/hallmark/references/themes/hum.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/themes/hum.md) (lines 7-11) describes this diversification strategy, which prevents the unintentional reuse of similar visual languages even when switching between different theme families.

### The Diversification Log

After rendering a page, Hallmark appends a structured entry to [`/.hallmark/log.json`](https://github.com/Nutlope/hallmark/blob/main//.hallmark/log.json):

```json
{
  "theme": "carnival",
  "drop": "studio-night",
  "timestamp": "2024-11-02T13:45:00Z"
}

```

The Redesign verb reference in [`skills/hallmark/references/verbs/redesign.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/verbs/redesign.md) (lines 215-222) specifies how this log is consulted during the build process. The diversification logic is applied at **SKILL § 3** (the catalog pick step), as defined in [`skills/hallmark/SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md) (lines 3-7), making it a mandatory checkpoint in the generation pipeline.

### Explicit Override Rules

If a brief explicitly signals a particular drop—for example, when a brand color matches a specific variant—Hallmark may bypass the rotation rule. However, as documented in [`skills/hallmark/references/themes/carnival.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/themes/carnival.md) (lines 127-132), such overrides must be documented in both the brief and the diversification log to maintain auditability.

## Implementation: Code Examples

The following examples demonstrate the practical implementation of the diversification logic.

### Selecting a Theme and Drop

The theme picker utility consults the log to enforce rotation rules:

```javascript
// utils/themePicker.js
import { readLog } from './log.js';
import { THEMES } from '../site/css/tokens.js';

export function pickTheme(requestedTheme) {
  const log = readLog();                       // reads /.hallmark/log.json
  const recent = log.slice(-3).map(e => e.theme);
  
  // If the brief forces a specific drop, honour it
  if (requestedTheme?.drop) return requestedTheme;
  
  // Choose a theme not in recent list
  const candidates = Object.keys(THEMES).filter(t => !recent.includes(t));
  const theme = candidates[0] || Object.keys(THEMES)[0];
  
  // Rotate drops if the theme supports them
  const drops = THEMES[theme].drops;
  const usedDrop = log.find(e => e.theme === theme)?.drop;
  const drop = drops.find(d => d !== usedDrop) || drops[0];
  
  return { theme, drop };
}

```

### Updating the Diversification Log

The logging utility persists selections for future builds:

```javascript
// utils/log.js
import fs from 'fs';
const LOG_PATH = '.hallmark/log.json';

export function appendLog(entry) {
  const logs = fs.existsSync(LOG_PATH) ? JSON.parse(fs.readFileSync(LOG_PATH, 'utf8')) : [];
  logs.push({ ...entry, timestamp: new Date().toISOString() });
  fs.writeFileSync(LOG_PATH, JSON.stringify(logs, null, 2));
}

```

### Sample Log Entry

A typical entry captures the exact theme and drop combination:

```json
{
  "theme": "carnival",
  "drop": "studio-night",
  "timestamp": "2024-11-02T13:45:00Z"
}

```

## Key Files in the Diversification System

- **[`skills/hallmark/references/themes/lumen.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/themes/lumen.md)** — Documents the drop rotation rule for themes with multiple variants (lines 58-62).
- **[`skills/hallmark/references/themes/hum.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/themes/hum.md)** — Explains diversification for single-drop themes and categorical distance logic (lines 7-11).
- **[`skills/hallmark/references/themes/carnival.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/themes/carnival.md)** — Details a six-drop theme and override documentation requirements (lines 11-15 and 127-132).
- **[`skills/hallmark/references/verbs/redesign.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/verbs/redesign.md)** — Specifies the diversification log consultation process (lines 215-222).
- **[`skills/hallmark/SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md)** — Defines the catalog pick step (SKILL § 3) where diversification is enforced (lines 3-7).
- **[`/.hallmark/log.json`](https://github.com/Nutlope/hallmark/blob/main//.hallmark/log.json)** — The runtime log that stores theme selection history.
- **[`site/css/tokens.css`](https://github.com/Nutlope/hallmark/blob/main/site/css/tokens.css)** — Contains CSS token definitions for each `[data-theme]` and `[data-drop]` combination.

## Summary

- Hallmark maintains a **diversification log** at [`/.hallmark/log.json`](https://github.com/Nutlope/hallmark/blob/main//.hallmark/log.json) that records every theme and drop selection with timestamps.
- The system **rotates drops** for multi-variant themes (like Lumen and Carnival) to prevent recent repeats.
- **Categorical distance** rules prevent similar themes from appearing consecutively when the brief is unspecified.
- Diversification is enforced at **SKILL § 3** (catalog pick), making it a mandatory build step.
- Briefs can **override** rotation rules, but must document the exception in the log.

## Frequently Asked Questions

### How does Hallmark prevent theme drift across consecutive builds?

Hallmark prevents theme drift by consulting the diversification log at [`/.hallmark/log.json`](https://github.com/Nutlope/hallmark/blob/main//.hallmark/log.json) before each build. The system checks the last *N* entries to ensure new selections are categorically distinct from recent themes, and rotates through available drops for multi-variant themes.

### What happens if a brief requests a specific theme drop?

If a brief explicitly signals a particular drop (for example, to match specific brand colors), Hallmark honors the request and bypasses the normal rotation rule. According to the source code in [`skills/hallmark/references/themes/carnival.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/themes/carnival.md), these overrides must be documented in both the brief and the diversification log to maintain system transparency.

### Where does Hallmark store the history of theme selections?

The system stores theme selection history in [`/.hallmark/log.json`](https://github.com/Nutlope/hallmark/blob/main//.hallmark/log.json), a JSON file that tracks the theme name, drop variant, and timestamp for each build. This file is read by the theme picker utility and updated after each successful render.

### At what stage in the build process is diversification enforced?

Diversification is enforced at **SKILL § 3**, also known as the catalog pick step. As defined in [`skills/hallmark/SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md), this stage occurs during the redesign process where the system selects design tokens and must apply the diversification rules before finalizing the theme choice.