# How Hallmark Enforces Structural Variety in Generated UI: A Deep Dive into Its Diversification Engine

> Discover how Hallmark enforces structural variety in generated UI with its three-layer diversification engine. Learn about macrostructures, combinatorial fingerprints, and reuse prevention.

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

---

**Hallmark guarantees structural variety through a three-layer system: a catalog of 21 distinct macrostructures, combinatorial structural fingerprints across multiple axes, and a project-level diversification log that prevents reuse.**

Hallmark is an open-source UI generation system by Nutlope that solves the "same page" problem plaguing AI-generated interfaces. Unlike tools that merely swap colors and fonts, Hallmark enforces genuine structural difference by treating page layout as a controlled, non-repeating variable. This article examines the specific mechanisms—macrostructures, structural fingerprints, and the diversification log—that make this enforcement possible.

## Macrostructures: The 21-Shape Page Catalog

At the heart of Hallmark's variety system lies **macrostructures**, a predefined catalog of 21 distinct page shapes. Each macrostructure prescribes a high-level layout pattern including hero configuration, component placement rules, and navigation/footer archetypes.

The complete catalog lives in [[`skills/hallmark/references/macrostructures.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/macrostructures.md)](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/macrostructures.md). Representative entries include:

- **Marquee Hero** – full-bleed hero with scrolling ticker element
- **Bento Grid** – dense modular layout with asymmetric cell sizing
- **Stat-Led** – data-forward page with prominent metric display
- **Workbench** – tool-centric interface with persistent side panel

When Hallmark runs, it selects a macrostructure that has not appeared in recent project history. This macrostructure selection serves as the primary source of structural variety—two Hallmark pages with different macrostructures are fundamentally different in shape, regardless of styling.

The runtime driver in [`site/js/main.js`](https://github.com/Nutlope/hallmark/blob/main/site/js/main.js) (lines 145-150) surfaces this catalog to the UI, displaying "21 macrostructures · 50 archetypes" as proof of the underlying variety system.

## Structural Fingerprints: Axes of Combinatorial Variation

Within a selected macrostructure, Hallmark generates a **structural fingerprint** by choosing one option from each axis defined in [[`skills/hallmark/references/structure.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/structure.md)](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/structure.md). The governing rule is absolute: **"Two pages should never share the same fingerprint."**

The fingerprint axes cover:

| Axis | Example Options |
|------|---------------|
| Layout | `left-hero`, `centre-hero`, `split-hero` |
| Navigation | `N1a-minimal`, `N1b-SaaS-three`, `N5-floating-pill` |
| Footer | `Ft1-single-line`, `Ft4-colophon`, `Ft7-rich` |
| Component archetype | Hero variant, grid density, CTA placement |
| Typographic pairing | Font family combinations |
| Color anchor | Primary palette selection |

This multi-axis approach creates combinatorial explosion. Even within a single macrostructure, the fingerprint system generates hundreds of unique structural configurations.

The JavaScript driver implements this selection in [`site/js/main.js`](https://github.com/Nutlope/hallmark/blob/main/site/js/main.js):

```javascript
// Pull the list of macrostructures and archetypes
const macrostructures = [
  "Marquee Hero", "Bento Grid", "Stat-Led", "Workbench", /* … */
];
const fingerprints = {
  layout: ["left-hero", "centre-hero", "split-hero"],
  nav:   ["N1a-minimal", "N1b-SaaS-three", "N5-floating-pill"],
  footer:["Ft1-single-line", "Ft4-colophon", "Ft7-rich"],
  // … other axes from structure.md
};

// Choose a macrostructure not in the log
const chosenMacro = pickUniqueMacrostructure(log);
const chosenFingerprint = pickUniqueFingerprint(log);

```

Line 222 of [`site/js/main.js`](https://github.com/Nutlope/hallmark/blob/main/site/js/main.js) embeds the enforcement rule directly: "Hallmark looks up the right page-shape for the brief and refuses to use the same one twice."

## Diversification Log: Project Memory for Non-Repetition

Hallmark maintains persistent **project memory** through [`.hallmark/log.json`](https://github.com/Nutlope/hallmark/blob/main/.hallmark/log.json), a JSON file that records every build's structural decisions. According to [[`SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/SKILL.md)](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md), the "Diversification" section specifies that each log entry contains:

```json
[
  {
    "date": "2026-08-15",
    "macrostructure": "Bento Grid",
    "theme": "carnival",
    "fingerprint": {
      "layout": "split-hero",
      "nav": "N5-floating-pill",
      "footer": "Ft4-colophon"
    },
    "brief": "SaaS analytics dashboard"
  }
  // … older entries trimmed to the last 20
]

```

On subsequent runs, Hallmark reads this file and deliberately avoids reusing any recorded axis combination. This ensures consecutive pages differ not merely in visual styling but in underlying structural DNA. The log serves as the ground truth for the `pickUniqueMacrostructure()` and `pickUniqueFingerprint()` functions.

The file is automatically pruned to maintain only the last 20 entries, balancing historical awareness with performance.

## Slop-Test Gate 9: Runtime Enforcement

Before emitting any code, Hallmark executes a **57-gate slop test** documented in [[`skills/hallmark/references/slop-test.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/slop-test.md)](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/slop-test.md). Gate 9 specifically validates the structural fingerprint against the diversification log.

If the fingerprint duplicates a previous entry, the build aborts and triggers a redesign. This gating mechanism catches structural sameness early—before any UI code generation occurs. The slop test transforms the diversification rules from guidelines into hard enforcement.

The complete enforcement pipeline operates as follows:

```

Select macrostructure → Choose fingerprint (axes) → Check .hallmark/log.json → Run slop-test → Emit code (with stamp)

```

## Structural Stamping: Verification Through CSS Comments

Hallmark **stamps** the chosen macrostructure directly into generated CSS. The [`site/css/sections.css`](https://github.com/Nutlope/hallmark/blob/main/site/css/sections.css) and [`site/css/components.css`](https://github.com/Nutlope/hallmark/blob/main/site/css/components.css) files contain CSS comments encoding the selected macrostructure, enabling downstream runs to verify diversity by reading these stamps.

This stamp system creates an audit trail: any Hallmark-generated page carries machine-readable evidence of its structural origin, allowing the diversification system to function across build sessions and even between different developers on the same project.

## Summary

Hallmark enforces structural variety in generated UI through five integrated mechanisms:

- **Macrostructure catalog** – 21 predefined page shapes prevent layout homogenization
- **Structural fingerprint system** – multi-axis selection creates combinatorial uniqueness
- **Diversification log** – persistent [`.hallmark/log.json`](https://github.com/Nutlope/hallmark/blob/main/.hallmark/log.json) records prevent historical repetition
- **Slop-test gate 9** – runtime validation rejects duplicate fingerprints before code generation
- **CSS stamping** – embedded structural metadata enables cross-session verification

Together, these systems ensure that no two Hallmark pages share structural identity, even when visual styling similarities occur.

## Frequently Asked Questions

### What is a macrostructure in Hallmark?

A macrostructure is one of 21 predefined high-level page shapes defined in [`skills/hallmark/references/macrostructures.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/macrostructures.md). Each macrostructure specifies hero configuration, component placement patterns, and navigation/footer archetypes. Hallmark treats macrostructure selection as the primary axis of structural variety.

### How does Hallmark prevent generating the same page twice?

Hallmark prevents regeneration through three layers: the diversification log ([`.hallmark/log.json`](https://github.com/Nutlope/hallmark/blob/main/.hallmark/log.json)) records previous builds, the structural fingerprint system enforces unique axis combinations, and slop-test gate 9 aborts builds that would repeat a previous fingerprint. The system refuses to emit code until a novel structural configuration is found.

### Can Hallmark's variety rules be customized or disabled?

The core variety rules—particularly the "no repeat fingerprint" constraint—are hardcoded in the skill definition and enforced by the slop test. However, developers can extend the system by adding new macrostructures to [`macrostructures.md`](https://github.com/Nutlope/hallmark/blob/main/macrostructures.md) or new fingerprint axes to [`structure.md`](https://github.com/Nutlope/hallmark/blob/main/structure.md), increasing the combinatorial space without weakening enforcement.

### Where is the diversification log stored and how long is it retained?

The diversification log resides at [`.hallmark/log.json`](https://github.com/Nutlope/hallmark/blob/main/.hallmark/log.json) in the project root. It retains the last 20 build entries automatically, with older entries trimmed to prevent unbounded growth. This 20-entry window provides sufficient historical context for diversity enforcement while maintaining file size efficiency.