# How Hallmark's Macrostructure Diversification Rule Prevents Repeated Page Shapes

> Learn how Hallmark's macrostructure diversification rule prevents repeated page shapes by stamping and reading CSS file history for unique layout selection from its 21-structure catalog.

- Repository: [Hassan El Mghari/hallmark](https://github.com/Nutlope/hallmark)
- Tags: deep-dive
- Published: 2026-07-19

---

**Hallmark prevents repeated page shapes by stamping each generated CSS file with its chosen macrostructure, then reading that history before subsequent builds to force selection of a categorically different layout from its 21-structure catalog.**

The **macrostructure diversification rule** is a core constraint in the Hallmark static site generator (Nutlope/hallmark) designed to eliminate the "slop split-personality" problem where consecutive pages default to identical layouts. By combining persistent stamping, a JSON-based build log, and a strict slop-test gate, Hallmark guarantees that every page in a project derives from a unique structural family.

## How the Macrostructure Diversification Rule Works

Hallmark enforces structural variety through a five-step validation pipeline that runs before any code generation begins.

### Stamping the Chosen Macrostructure

Every build embeds a machine-readable fingerprint in the generated CSS. This **macrostructure stamp** follows a strict comment format:

```css
/* Hallmark · macrostructure: Marquee Hero · … */

```

As documented in [`skills/hallmark/references/macrostructures.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/macrostructures.md), this stamp serves as the permanent record of which structural family the page belongs to, creating an auditable trail of layout choices across the project.

### Reading Previous Stamps from Build History

Before selecting a new macrostructure, Hallmark checks the [`.hallmark/log.json`](https://github.com/Nutlope/hallmark/blob/main/.hallmark/log.json) file created during previous runs. According to [`skills/hallmark/references/verbs/redesign.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/verbs/redesign.md), the system parses this log to identify the most recently used macrostructure name, ensuring the next generation cannot select the same structural fingerprint.

### The Slop-Test Gate

Hallmark implements a hard gate in the **slop-test checklist** that explicitly fails the build if the selected macrostructure matches any previous output. As defined in [`skills/hallmark/references/slop-test.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/slop-test.md), this gate checks for "same structural fingerprint / macrostructure as a previous Hallmark output," preventing accidental repetition at the CI/CD level.

## Catalog-Based Selection Process

The diversification rule operates against a fixed catalog of **21 named macrostructures** defined in [`skills/hallmark/references/macrostructures.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/macrostructures.md). The selection algorithm works as follows:

1. Parse the brief to determine page requirements
2. Load the full macrostructure catalog
3. Filter out any macrostructure already stamped in the current project's history
4. Randomly select from the remaining candidates to ensure categorical difference

This forced exclusion prevents the common pitfall where AI-generated sites repeat the same hero-and-three-column pattern across every route.

## Handling Design Files and App Pages

When a [`design.md`](https://github.com/Nutlope/hallmark/blob/main/design.md) file exists, the rule adapts for **app pages** where thematic consistency takes priority. As noted in [`skills/hallmark/references/verbs/redesign.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/verbs/redesign.md) (lines 214-222), the macrostructure may still vary within the declared family, allowing structural diversity while maintaining visual cohesion across application interfaces.

## Implementation Examples

The following JavaScript snippets demonstrate the core logic Hallmark uses to enforce diversification.

### Detecting the Last Macrostructure

```javascript
import fs from 'fs';
import path from 'path';

// Path to the Hallmark log (created by each run)
const LOG_PATH = path.resolve('.hallmark/log.json');

// Return the macrostructure name from the most recent entry
function getLastMacrostructure() {
  if (!fs.existsSync(LOG_PATH)) return null;
  const log = JSON.parse(fs.readFileSync(LOG_PATH, 'utf8'));
  const latest = log[log.length - 1];
  return latest?.macrostructure || null;
}

```

### Selecting a New Macrostructure

```javascript
import macrocatalog from './skills/hallmark/references/macrostructures.json';

function pickMacrostructure(avoid) {
  // Filter out the previously used macrostructure
  const candidates = macrocatalog.filter(m => m.name !== avoid);
  // Simple heuristic: pick the first remaining one
  return candidates[0];
}

// Example usage
const previous = getLastMacrostructure();
const newMacro = pickMacrostructure(previous);
console.log('Choosing macrostructure:', newMacro.name);

```

### Adding the Stamp to Generated CSS

```javascript
function addMacroStamp(css, macroName) {
  const stamp = `/* Hallmark · macrostructure: ${macroName} */\n`;
  return stamp + css;
}

// After building the page's CSS:
let css = generateCssForPage(newMacro);
css = addMacroStamp(css, newMacro.name);
fs.writeFileSync('dist/page.css', css);

```

## Summary

- **Hallmark's macrostructure diversification rule** prevents layout repetition by maintaining a persistent history of used page shapes in [`.hallmark/log.json`](https://github.com/Nutlope/hallmark/blob/main/.hallmark/log.json) and CSS stamps.
- The **slop-test gate** aborts builds when the selected macrostructure matches previous outputs, enforcing variety at the CI level.
- Hallmark selects from a **catalog of 21 named macrostructures**, automatically excluding any previously used in the current project.
- For **app pages** with existing [`design.md`](https://github.com/Nutlope/hallmark/blob/main/design.md) files, the rule relaxes to allow thematic consistency while still varying the underlying macrostructure.

## Frequently Asked Questions

### What is a macrostructure in Hallmark?

A macrostructure is a high-level layout pattern that defines the semantic organization of a page—such as "Marquee Hero" or "Split Feature"—chosen from a catalog of 21 predefined families. According to [`skills/hallmark/references/structure.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/structure.md), these structures determine the fundamental HTML landmark regions and CSS grid patterns before any styling details are applied.

### How does the slop-test gate detect repeated page shapes?

The slop-test gate defined in [`skills/hallmark/references/slop-test.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/slop-test.md) compares the candidate macrostructure against the "structural fingerprint" found in the most recent CSS stamp or log entry. If the names match, the gate triggers a build failure with the specific error citing "same structural fingerprint / macrostructure as a previous Hallmark output."

### Where does Hallmark store the macrostructure history?

Hallmark maintains build history in two locations: the [`.hallmark/log.json`](https://github.com/Nutlope/hallmark/blob/main/.hallmark/log.json) file contains a chronological array of past generations with macrostructure metadata, while each generated CSS file contains an inline stamp comment. The redesign verb in [`skills/hallmark/references/verbs/redesign.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/verbs/redesign.md) prioritizes the log file for batch operations but falls back to parsing CSS stamps when rebuilding individual pages.

### Does the rule apply to all page types in Hallmark?

The diversification rule applies to standard marketing and content pages by default. However, when processing **app pages** that reference an existing [`design.md`](https://github.com/Nutlope/hallmark/blob/main/design.md) theme file, Hallmark inverts the constraint to preserve visual consistency while still allowing macrostructure variation within the declared family, as implemented in the redesign logic (lines 214-222).