How Hallmark Enforces Theme Diversification: A Technical Deep Dive

Hallmark enforces theme diversification by maintaining a JSON log at /.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. 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 (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 (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 (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:

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

The Redesign verb reference in 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 (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 (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:

// 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:

// 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:

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

Key Files in the Diversification System

• 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 — Explains diversification for single-drop themes and categorical distance logic (lines 7-11).
• 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 — Specifies the diversification log consultation process (lines 215-222).
• skills/hallmark/SKILL.md — Defines the catalog pick step (SKILL § 3) where diversification is enforced (lines 3-7).
• /.hallmark/log.json — The runtime log that stores theme selection history.
• 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 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 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, 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, 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, this stage occurs during the redesign process where the system selects design tokens and must apply the diversification rules before finalizing the theme choice.

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