# How Hallmark's Diversification Rule Prevents Template Fatigue

> Discover how Hallmark's diversification rule prevents template fatigue with dynamic macro-structures and visual themes, ensuring unique outputs every time. Learn about its innovative detection methods.

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

---

**Hallmark prevents template fatigue by enforcing a mandatory diversification rule that varies macro-structures and visual themes across successive runs, using CSS stamp detection, three-axis theme comparison, and project-memory logs to ensure no two consecutive outputs share the same layout or visual characteristics.**

Hallmark is an open-source AI-powered page generation system that combats repetitive outputs through a rigorous diversification protocol. According to the Nutlope/hallmark source code, the **diversification rule** systematically rotates both structural layouts and visual themes by analyzing project history and CSS metadata, ensuring each generated page feels distinct while maintaining design coherence.

## Macro-Structure Diversification via CSS Stamp Detection

Hallmark prevents layout repetition by scanning for existing CSS stamps before selecting a macro-structure. As implemented in [`skills/hallmark/SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md) (lines 68-73), the system searches for a comment stamp in the format `/* Hallmark · macrostructure: <name> … */` within existing CSS files.

If a stamp is detected, the diversification rule mandates that the next macro-structure **must differ** from the recorded one. Additionally, it must differ from the macro-structure used in the previous Hallmark output during the current session. This prevents the system from defaulting repeatedly to popular layouts like the "Specimen" macro-structure.

## Theme Diversification Across Three Visual Axes

Even when macro-structures vary, visual themes can still produce fatigue if they share similar characteristics. To prevent this, Hallmark enforces a **three-axis comparison rule** defined in [`skills/hallmark/SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md) (lines 76-79). Consecutive themes must differ on at least one of these axes:

- **Paper band** – Lightness values determined by `--color-paper` (light, mid, or dark)
- **Display style** – Typography classification such as `high-contrast-serif`, `roman-serif`, or `geometric-sans`
- **Accent hue** – Color temperature categories including warm, cool, neutral, or chromatic-other

The system reads these axis values from the top of each theme’s token block in [`site/css/tokens.css`](https://github.com/Nutlope/hallmark/blob/main/site/css/tokens.css). If two consecutive themes match on two or more axes, Hallmark **re-routes** to a different theme that satisfies the diversification requirement (lines 80-82).

## Project-Level Inversion for Multi-Page Consistency

Hallmark’s diversification rule includes an intelligent inversion mechanism for multi-page applications. When a project contains a [`design.md`](https://github.com/Nutlope/hallmark/blob/main/design.md) file—produced during a full-app redesign—the rule inverts to enforce **consistency** rather than variety.

As specified in [`skills/hallmark/references/verbs/redesign.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/verbs/redesign.md) (lines 33-36), this inversion ensures that all pages within a redesigned application share the same visual language. The system detects the presence of [`design.md`](https://github.com/Nutlope/hallmark/blob/main/design.md) and suppresses the normal diversification checks, allowing the same macro-structure and theme to persist across the entire application.

## Log-Driven Rotation and History Tracking

To enforce these rules across multiple sessions, Hallmark maintains a per-project history in [`.hallmark/log.json`](https://github.com/Nutlope/hallmark/blob/main/.hallmark/log.json). According to [`skills/hallmark/SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md) (lines 96-110), the system references the last 3–5 entries when making new selections.

This log feeds the diversification check for both macro-structures and themes, creating a guaranteed rotation cycle that prevents recent choices from reappearing too soon. The combination of stamp detection and log-driven rotation creates a deterministic yet varied output sequence.

## Implementation Details

The following code examples illustrate how Hallmark implements these diversification checks in practice.

### Detecting the Last Macro-Structure

This pattern mirrors the stamp detection logic described in the skill definition:

```javascript
// site/_tests/helpers.js – simplified illustration
import fs from 'fs';
import path from 'path';

// Load the latest CSS stamp (if any)
function getLastMacro() {
  const cssFiles = fs.readdirSync('site').filter(f => f.endsWith('.css'));
  for (const file of cssFiles.reverse()) {
    const content = fs.readFileSync(path.join('site', file), 'utf8');
    const match = content.match(/Hallmark · macrostructure: (\w+)/);
    if (match) return match[1];
  }
  return null;
}

// Enforce diversification
function pickMacro(available) {
  const last = getLastMacro();
  const choice = available.find(m => m !== last);
  if (!choice) throw new Error('No diversified macrostructure available');
  return choice;
}

```

### Comparing Theme Axes

This utility implements the three-axis comparison rule using token values from [`site/css/tokens.css`](https://github.com/Nutlope/hallmark/blob/main/site/css/tokens.css):

```javascript
// utils/themeDiversify.js
import tokens from '../site/css/tokens.css'; // parsed as JSON-like object

function getAxisValues(theme) {
  const block = tokens[theme];               // e.g. tokens['atelier']
  return {
    paperBand: block['--color-paper-lightness'],
    displayStyle: block['--display-style'],
    accentHue: block['--accent-hue']
  };
}

function themesDiffer(prev, next) {
  const a = getAxisValues(prev);
  const b = getAxisValues(next);
  // Return true if at least one axis differs
  return a.paperBand !== b.paperBand ||
         a.displayStyle !== b.displayStyle ||
         a.accentHue !== b.accentHue;
}

```

### Checking for Design Lock Inversion

This detection triggers the consistency mode for redesigned projects:

```javascript
// checkDesignInversion.js
import fs from 'fs';
function isDesignLocked() {
  return fs.existsSync('design.md');
}

// In a redesign run
if (isDesignLocked()) {
  // Consistency required – skip diversification checks
  console.log('Design lock detected – reuse existing theme/macro.');
}

```

## Summary

- **CSS stamp detection** prevents macro-structure repetition by scanning existing files for `/* Hallmark · macrostructure: <name> … */` comments and mandating different selections.
- **Three-axis theme comparison** requires consecutive themes to differ on at least one axis: paper band, display style, or accent hue, with values sourced from [`site/css/tokens.css`](https://github.com/Nutlope/hallmark/blob/main/site/css/tokens.css).
- **Project-level inversion** flips the diversification rule to enforce consistency when [`design.md`](https://github.com/Nutlope/hallmark/blob/main/design.md) is present, ensuring multi-page applications maintain visual coherence.
- **Log-driven rotation** uses [`.hallmark/log.json`](https://github.com/Nutlope/hallmark/blob/main/.hallmark/log.json) to track the last 3–5 entries and prevent recent choices from reappearing too quickly.

## Frequently Asked Questions

### How does Hallmark detect the previously used macro-structure?

Hallmark scans existing CSS files for a specific comment stamp formatted as `/* Hallmark · macrostructure: <name> … */`. As defined in [`skills/hallmark/SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md) (lines 68-73), the system extracts the macro-structure name from this stamp and excludes it from the next selection pool, ensuring the subsequent generation uses a different layout.

### What are the three axes used for theme diversification?

The three axes are **paper band** (light/mid/dark based on `--color-paper` lightness), **display style** (typographic classifications like `high-contrast-serif` or `geometric-sans`), and **accent hue** (warm, cool, neutral, or chromatic-other). According to [`skills/hallmark/SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md) (lines 76-79), themes must differ on at least one of these axes to satisfy the diversification rule.

### When does Hallmark invert its diversification rule?

The rule inverts when a project contains a [`design.md`](https://github.com/Nutlope/hallmark/blob/main/design.md) file, which is generated during a full-app redesign. As documented in [`skills/hallmark/references/verbs/redesign.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/verbs/redesign.md) (lines 33-36), this inversion enforces consistency across pages rather than variety, ensuring that multi-page applications maintain a unified visual design.

### Where does Hallmark store its diversification history?

Hallmark maintains a per-project log in [`.hallmark/log.json`](https://github.com/Nutlope/hallmark/blob/main/.hallmark/log.json). This file stores the last 3–5 macro-structure and theme selections, which the system references during subsequent runs to enforce rotation and prevent template fatigue, as described in [`skills/hallmark/SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md) (lines 96-110).