How Hallmark's Theme System Ensures Diversification: A Log-Driven Rotation Strategy

Hallmark's theme system ensures diversification by maintaining a JSON log at /.hallmark/log.json that records recent theme and drop selections, then enforcing variety through mandatory drop rotation and categorical distance rules while allowing explicit brief overrides.

The Hallmark design system (Nutlope/hallmark) packages visual design as themes—collections of tokens including palette, typography, and motion parameters. To prevent "theme drift" (unintended visual repetition), the system implements a deterministic diversification strategy that consults a persistent log before selecting drops (variant configurations) for each new build.

How Theme Diversification Works

The diversification engine operates at SKILL § 3 (catalog pick), as specified in skills/hallmark/SKILL.md (lines 3-7). When generating a page, Hallmark records the chosen theme and drop in a diversification log, then applies three core constraints to ensure visual variety.

The Diversification Log

The system persists all theme selections to /.hallmark/log.json, creating an auditable history of visual choices. Each entry follows this structure:

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

As noted in skills/hallmark/references/verbs/redesign.md (lines 215-222), this log drives the "diversification log" logic that prevents consecutive builds from reusing the same visual language.

Drop Rotation Rules

Themes containing multiple drops must rotate through variants. For example, Lumen offers Night versus Day variants, while Carnival provides six distinct drops. The system consults the recent-N entries in /.hallmark/log.json and selects a drop that has not appeared in recent builds.

The specific rule is documented in skills/hallmark/references/themes/lumen.md (lines 58-62), which describes the "Drop rotation rule" requiring alternation between available variants.

Categorical Distance Filtering

When a brief does not specify a theme, Hallmark prefers themes that are categorically distant from recent selections. This logic appears in skills/hallmark/references/themes/hum.md (lines 7-11), which explains how the system avoids thematic repetition by filtering candidates against the recent history. The Carnival theme reference reinforces this in skills/hallmark/references/themes/carnival.md (lines 11-15), describing how the diversification engine weights theme selection toward visual variety.

Brief Override Mechanisms

Explicit brief signals can override rotation rules. If a brief specifies a particular drop (for example, to match brand colors), Hallmark honors the request but documents the override in both the brief and the log. This exception handling is detailed in skills/hallmark/references/themes/carnival.md (lines 127-132).

Implementation Details

The diversification logic lives in the skill engine's utility modules, which interact with the design tokens defined in site/css/tokens.css.

Theme Selection Logic

The pickTheme function in utils/themePicker.js demonstrates the selection algorithm. It reads the diversification log, filters out recently used themes, and rotates drops for multi-variant themes:

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

Log Persistence

The appendLog function in utils/log.js handles atomic updates to the diversification log:

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

Log Entry Structure

Each build appends a structured entry containing the theme identifier, drop variant, and ISO timestamp:

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

Key Source Files

• skills/hallmark/references/themes/lumen.md (lines 58-62): Defines the drop rotation rule for themes with multiple variants like Night and Day.

• skills/hallmark/references/themes/hum.md (lines 7-11): Explains diversification for single-drop themes and categorical distance filtering.

• skills/hallmark/references/themes/carnival.md (lines 11-15, 127-132): Documents six-drop rotation logic and override protocols for brief-specified variants.

• skills/hallmark/references/verbs/redesign.md (lines 215-222): Describes the diversification log and constraints for consecutive pages in app-level builds.

• skills/hallmark/SKILL.md (lines 3-7): Central specification defining the catalog pick step where diversification enforcement occurs.

• /.hallmark/log.json: Runtime JSON store containing the history of theme and drop selections that drives the diversification algorithm.

• site/css/tokens.css: Contains CSS token definitions for each [data-theme] and [data-drop] combination consumed by the diversification system.

Summary

• Hallmark's theme system prevents visual repetition by maintaining a persistent JSON log at /.hallmark/log.json that tracks recent theme and drop selections.
• Drop rotation forces variety by requiring themes with multiple drops (like Lumen's Night/Day or Carnival's six variants) to select unused variants from recent history.
• Categorical distance rules prefer themes visually distinct from recent builds when the brief does not specify a particular theme.
• Override capabilities allow briefs to force specific drops, provided the exception is documented in both the brief and the log.
• The logic is implemented at SKILL § 3 in the catalog pick phase, with reference specifications in skills/hallmark/references/themes/ and skills/hallmark/SKILL.md.

Frequently Asked Questions

What is the purpose of the /.hallmark/log.json file?

The /.hallmark/log.json file serves as the diversification log that records every theme and drop selection with timestamps. Hallmark consults this file during the catalog pick phase to determine which themes and drops have been used recently, enabling the system to enforce rotation rules and prevent "theme drift" by selecting categorically distant or unused variants.

How does Hallmark handle themes with multiple drops?

Themes supporting multiple drops—such as Lumen (Night vs Day) or Carnival (six variants)—implement a drop rotation rule that selects a drop not appearing in the recent-N log entries. According to skills/hallmark/references/themes/lumen.md (lines 58-62), the system must rotate through available drops to ensure visual variety across consecutive builds.

Can the diversification rules be overridden?

Yes, explicit brief signals can override the rotation and distance rules. If a brief specifies a particular drop (for example, to match specific brand colors), Hallmark honors the selection but documents the override in both the brief metadata and the /.hallmark/log.json file, as specified in skills/hallmark/references/themes/carnival.md (lines 127-132).

Where is the diversification logic defined in the Hallmark skill specification?

The diversification logic is formally defined at SKILL § 3 (catalog pick) in skills/hallmark/SKILL.md (lines 3-7). This section establishes the requirement to consult the diversification log and enforce variety during theme selection, while specific implementation details for individual themes reside in their respective reference files under skills/hallmark/references/themes/.

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