# How Theme Diversification Works in Hallmark: Log-Driven Design Token Rotation

> Discover how Hallmark's theme diversification ensures visual variety using a log-driven design token rotation. Learn how it tracks selections and applies deterministic algorithms to your builds.

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

---

**Hallmark implements theme diversification by maintaining a JSON log at [`/.hallmark/log.json`](https://github.com/Nutlope/hallmark/blob/main//.hallmark/log.json) that tracks recent theme and drop selections, then uses a deterministic rotation algorithm to force visual variety across builds while respecting explicit brief overrides.**

The Nutlope/hallmark repository treats a **theme** as a packaged set of design tokens—encompassing palette, typography, motion, and optional *drop* variants. To prevent "theme drift" (unintentional visual repetition across consecutive pages), the system enforces a **theme diversification** strategy at SKILL § 3 (catalog pick). This mechanism ensures that each new build introduces categorical distance from recent selections unless the brief explicitly demands otherwise.

## The Diversification Log

At the core of the system is the **diversification log** located at [`/.hallmark/log.json`](https://github.com/Nutlope/hallmark/blob/main//.hallmark/log.json). This file stores a chronological history of every theme and drop selection, enabling the rotation algorithm to determine which combinations have appeared recently.

Each entry follows this structure:

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

```

According to 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), this log is consulted during the catalog pick phase to ensure consecutive pages receive distinct visual treatments.

## How Theme Diversification Works

The diversification algorithm operates through four distinct rules:

### 1. Rotating Theme Drops

When a theme supports multiple **drops** (variant configurations), Hallmark rotates through them to ensure variety. For example, the **Lumen** theme maintains two drops (Night and Day), while **Carnival** offers six distinct drops.

As specified 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 enforces a "Drop rotation rule" that prevents the same drop from appearing in recent-N entries. The algorithm selects the next available drop that hasn't been used in the recent history recorded in [`/.hallmark/log.json`](https://github.com/Nutlope/hallmark/blob/main//.hallmark/log.json).

### 2. Avoiding Repeat Themes

When the brief doesn't specify a theme, Hallmark prefers selections that are *categorically distant* from the last few builds. The **Hum** theme file in [`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 logic, which is reinforced by the generic diversification notes 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 filters out themes that appear in the recent log entries, forcing the selection of alternative visual languages.

### 3. Logging Every Selection

After rendering a page, Hallmark appends the chosen theme and drop to the diversification log. This step completes the feedback loop, updating the historical record that future builds will consult. The logging mechanism ensures that the rotation algorithm operates on accurate, up-to-date data.

### 4. Handling Explicit Overrides

The diversification rules yield when the brief explicitly signals a particular drop. For instance, if a brand color matches a specific Carnival drop, the system may ignore the standard rotation. According to [`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 log, maintaining an audit trail of why the diversification rule was bypassed.

## Implementation in Code

The diversification logic appears in the skill engine's theme selection utilities. The following pseudo-code from [`utils/themePicker.js`](https://github.com/Nutlope/hallmark/blob/main/utils/themePicker.js) demonstrates the rotation algorithm:

```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 };
}

```

The logging utility in [`utils/log.js`](https://github.com/Nutlope/hallmark/blob/main/utils/log.js) handles persistence:

```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));
}

```

## Key Source Files

Understanding theme diversification requires examining these specific files:

- **[`skills/hallmark/references/themes/lumen.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/themes/lumen.md)** — Documents the two-drop system (Night vs Day) and the explicit "Drop rotation rule" (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 how the rule is inverted for app-level consistency (lines 7–11).

- **[`skills/hallmark/references/themes/carnival.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/themes/carnival.md)** — Details the six-drop system and the log-based rotation logic (lines 11–15), plus override documentation requirements (lines 127–132).

- **[`skills/hallmark/references/verbs/redesign.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/verbs/redesign.md)** — Defines the diversification log and explains when consecutive pages must share themes for app-level builds (lines 215–222).

- **[`skills/hallmark/SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md)** — Central specification of the catalog-pick step where diversification is enforced (section 3, lines 3–7).

- **[`/.hallmark/log.json`](https://github.com/Nutlope/hallmark/blob/main//.hallmark/log.json)** — Runtime file storing the theme and drop history that drives the diversification algorithm.

- **[`site/css/tokens.css`](https://github.com/Nutlope/hallmark/blob/main/site/css/tokens.css)** — Contains the CSS token definitions for each `[data-theme]` and `[data-drop]` combination used by the diversification system.

## Summary

- **Theme diversification** prevents visual repetition by rotating through available theme drops and avoiding recent theme selections.
- The system relies on **[`/.hallmark/log.json`](https://github.com/Nutlope/hallmark/blob/main//.hallmark/log.json)** to maintain a history of theme and drop choices across builds.
- **Drop rotation** forces variety in multi-drop themes like Lumen and Carnival, while **categorical distance** prevents rapid theme reuse.
- Explicit brief signals can **override** diversification rules, but these exceptions must be logged.
- The entire mechanism is enforced at **SKILL § 3** (catalog pick) as part of Hallmark's design-system discipline.

## Frequently Asked Questions

### What is a "drop" in Hallmark themes?

A **drop** is a variant configuration within a theme that adjusts specific design tokens such as color palette or density. Themes like Lumen provide two drops (Night and Day), while Carnival offers six distinct drops. The diversification system rotates through these drops to ensure visual variety across consecutive builds.

### Where does Hallmark store the theme diversification history?

Hallmark stores the diversification history in **[`/.hallmark/log.json`](https://github.com/Nutlope/hallmark/blob/main//.hallmark/log.json)**. This JSON file contains timestamped entries recording each theme and drop selection, which the rotation algorithm consults to determine which combinations have appeared recently.

### Can I force a specific theme drop despite rotation rules?

Yes. If the brief explicitly signals a particular drop—for example, when a brand color matches a specific variant—Hallmark will honor that request and skip the rotation rule. However, according to the Carnival theme reference, such overrides must be documented in both the brief and the diversification log to maintain an audit trail.

### At what stage does theme diversification occur?

Theme diversification is enforced at **SKILL § 3** (catalog pick), as defined in [`skills/hallmark/SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md). This stage occurs during the build process when the system selects the visual theme for the page, ensuring that the chosen theme and drop provide categorical distance from recent entries in the diversification log.