How Hallmark's Diversification Rule Prevents Template Fatigue

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 (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 (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. 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 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 (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 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. According to 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:

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

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

// 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.
• Project-level inversion flips the diversification rule to enforce consistency when design.md is present, ensuring multi-page applications maintain visual coherence.
• Log-driven rotation uses .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 (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 (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 file, which is generated during a full-app redesign. As documented in 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. 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 (lines 96-110).

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