How Hallmark's Diversification Rule Prevents Structural Sameness Across Pages

Hallmark's diversification rule prevents structural sameness by enforcing rotation at two independent levels—macrostructure and theme—using CSS stamps, historical logs, and three-axis theme comparison to ensure consecutive pages differ in layout and visual language.

The Hallmark diversification rule is a core mechanism in the Nutlope/hallmark repository that automatically rotates page designs during multi-page generation. Built into the generation pipeline, this rule ensures that consecutive pages in the same project cannot end up looking identical by checking against previous builds before selecting new designs. The system operates through three specific artifacts that track history and enforce constraints at both the layout and visual theme levels.

The Three Artifacts That Enforce Rotation

Hallmark reads three distinct artifacts before picking a new design to ensure diversification across pages:

• CSS stamp (/* Hallmark · macrostructure: … */) — Stores the macrostructure name, theme name, and three axis values (paper-band, display-style, accent-hue) from the most recent page. Hallmark scans for existing stamps and rejects any macrostructure or theme that matches the previous one, as defined in skills/hallmark/SKILL.md lines 68-78.
• .hallmark/log.json — Maintains a chronological array of the last 3-5 builds, tracking macrostructure, theme, enrichment, and brief. The engine excludes any macrostructure appearing in this recent history before making a selection, as documented in skills/hallmark/SKILL.md lines 96-110.
• Design-system file (design.md) — When present, marks the project as a multi-page app and inverts the diversification rule so pages share a consistent system rather than rotating, as specified in skills/hallmark/references/verbs/redesign.md lines 31-34.

Macrostructure Diversification

Macrostructure diversification ensures that page layouts vary significantly between builds. According to the source code in skills/hallmark/SKILL.md, the process follows three strict steps:

1. Hallmark reads any existing CSS stamp to identify the current macrostructure (e.g., "Bento Grid" or "Hero Split").
2. It inspects .hallmark/log.json for the last three macrostructures used in the project.
3. The candidate macrostructure must differ from all recorded entries; otherwise, generation aborts and a new structure is chosen.

This guarantees that critical layout elements—such as hero position, component order, and navigation placement—automatically vary between pages.

// Read the most recent CSS stamp
const stamp = findStampInProject(); // e.g. "macrostructure: Bento Grid"

// Load recent log entries
const recent = readLogJson().slice(0, 3).map(e => e.macrostructure);

// Reject if the candidate macrostructure appears in either source
function isMacroAllowed(candidate) {
  return candidate !== stamp && !recent.includes(candidate);
}

Theme Diversification via Three-Axis Comparison

Even when macrostructures differ, visual repetition can still occur if themes remain identical. Hallmark prevents this through a three-axis theme space defined in site/css/tokens.css (lines 1-7). Each theme is evaluated across three specific properties:

• paper-band — Controls background lightness (e.g., light vs. dark)
• display-style — Defines typography approach (e.g., high-contrast-serif vs. geometric-sans)
• accent-hue — Determines color palette (e.g., warm vs. chromatic-green)

The diversification rule, as implemented in skills/hallmark/SKILL.md lines 74-79, requires that two consecutive themes must differ on at least one of these three axes. The engine extracts axis values from the theme's token block and compares them against previous entries in .hallmark/log.json. If all three axes match, the theme is rejected.

// Axis values are stored in the theme’s token block
// Example for the "Specimen" theme (from tokens.css)
const specimenAxes = {
  paperBand: 'light',          // L > 85%
  displayStyle: 'high-contrast-serif',
  accentHue: 'warm'
};

// Load previous theme axes from the log
const previous = readLogJson()[0].themeAxes;

// The diversification rule: at least one axis must differ
function isThemeAllowed(candidateAxes) {
  const diff = Object.keys(candidateAxes).some(
    key => candidateAxes[key] !== previous[key]
  );
  return diff;
}

Multi-Page App Exception

The diversification rule includes a deliberate exception for multi-page applications. When a design.md file exists in the project root, Hallmark recognizes the project as requiring design system consistency rather than rotation. In this case, the rule inverts: all pages must share the same macrostructure and theme, using the design system file as the single source of truth for all pages.

if (exists('design.md')) {
  // All pages must share the same macrostructure and theme
  const shared = parseDesignMd(); // returns { macrostructure, theme }
  enforce(shared.macrostructure, shared.theme);
}

This exception ensures that while marketing sites benefit from visual variety, applications maintain the structural consistency required for user navigation and brand coherence.

Summary

• Hallmark enforces diversification at two levels: macrostructure (page layout) and theme (visual styling).
• The system uses CSS stamps, .hallmark/log.json, and an optional design.md to track history and enforce rules.
• Macrostructures must differ from the last three builds recorded in the log and the current CSS stamp.
• Themes must differ on at least one of three axes (paper-band, display-style, accent-hue) to prevent visual repetition.
• Projects containing a design.md file invert the rule to enforce consistency across multi-page applications.

Frequently Asked Questions

What is the Hallmark diversification rule?

The Hallmark diversification rule is a generation constraint that prevents consecutive pages in a project from sharing identical layouts or visual themes. It operates by comparing candidate designs against historical build data stored in CSS comments and log files, ensuring automatic rotation of both macrostructures and theme characteristics.

How does Hallmark track previous page structures?

Hallmark tracks previous structures through two mechanisms: CSS stamp comments embedded in generated files (recording the current macrostructure and theme axes) and .hallmark/log.json (maintaining a chronological history of the last 3-5 builds). Before generating a new page, the engine checks both sources to exclude recently used designs.

What are the three theme axes in Hallmark?

The three theme axes are paper-band (background lightness), display-style (typography family), and accent-hue (color palette). According to the source code in site/css/tokens.css, consecutive themes must differ on at least one of these axes to satisfy the diversification rule.

When does Hallmark allow structural sameness?

Hallmark allows structural sameness only when a design.md file is present, indicating a multi-page application requiring design system consistency. In this scenario, the diversification rule inverts to enforce that all pages share the same macrostructure and theme, as documented in skills/hallmark/references/verbs/redesign.md.

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