# How Hallmark Ensures Structural Variety in Generated Designs: The Complete Guide

> Discover how Hallmark generates diverse designs by separating style from structure and applying strict diversification rules across 21 macrostructures and six structural axes. Learn more.

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

---

**Hallmark eliminates AI-generated UI sameness by decoupling visual styling from page architecture and enforcing strict diversification rules across 21 macrostructures and six orthogonal structural axes.**

Hallmark, an open-source design generation system by Nutlope, solves the persistent problem of "AI-generated UI fingerprint"—that tell-tale sameness across AI-built interfaces. This article explains the technical mechanisms Hallmark uses to guarantee structural variety in every generated design, drawing directly from the project's source code and configuration files.

## Macrostructures: 21 Atomic Page Shapes

Hallmark's primary defense against repetitive layouts starts with **macrostructures**—named, prescriptive page architectures that bundle complete layout decisions into single units.

Each macrostructure encapsulates:
- Section-heading placement
- Body composition
- Divider style
- Button voice
- Image treatment
- Reveal pattern

Hallmark ships **21 named macrostructures**, including:
- **Bento Grid** – dense, modular grid systems
- **Long Document** – editorial, scroll-heavy layouts
- **Marquee Hero** – oversized typography with horizontal motion
- **Stat-Led** – data-dense landing pages

According to [[`macrostructures.md`](https://github.com/Nutlope/hallmark/blob/main/macrostructures.md)](skills/hallmark/references/macrostructures.md), selecting a macrostructure is **mandatory before any code is emitted**: "Pick one before you write code."

### The Macrostructure Diversification Rule

Hallmark enforces that **no two consecutive outputs in the same project may reuse the same macrostructure**. The system scans target codebases for existing stamp comments like:

```css
/* Hallmark · macrostructure: Bento Grid · version: 1.0 */
:root {
  /* macrostructure-specific tokens, e.g. grid gap, column ratios */
}

```

If a stamp is found, the new design **must select a different macrostructure**. This guarantee persists across successive pages within the same project.

## Six Orthogonal Structural Axes

When macrostructure-level variety isn't sufficient, Hallmark falls back to the **six structural axes** defined in [[`structure.md`](https://github.com/Nutlope/hallmark/blob/main/structure.md)](skills/hallmark/references/structure.md):

| Axis | Controls |
|:---|:---|
| Section-heading placement | Where titles anchor relative to content |
| Body composition | Overall content flow and containment |
| Divider language | Visual separators between sections |
| Button voice | Call-to-action prominence and style |
| Image treatment | How imagery integrates with layout |
| Reveal pattern | Entrance animations and scroll behaviors |

A **structural fingerprint** consists of one choice from each axis, yielding approximately **42,000 possible combinations**.

### Anti-Repetition Guard for Axis-Based Fingerprints

Hallmark enforces a strict rule when building fingerprints from axes: **no two consecutive pages may share more than three of the six axis choices**. This forces substantive change across at least three structural dimensions between any two generated pages.

## Forbidden AI-Template Patterns

Hallmark hard-codes a catalog of **anti-patterns**—common "AI slop" layouts that it actively rejects. These include:

- Centered-hero-with-CTA-and-fade-up (the generic SaaS hero)
- Three-feature-row grids
- Universal footer templates

As documented in [[`structure.md`](https://github.com/Nutlope/hallmark/blob/main/structure.md)](skills/hallmark/references/structure.md): "Reject these structural fingerprints. They are the AI-template fingerprint." The generation pipeline treats these as "slop-test gates" and blocks any matching fingerprint.

## Theme Decoupling: Visual Surface vs. Page Shape

Hallmark's **themes** (Almanac, Brutal, Terminal, and others) supply default fingerprints, but critically:

> "Themes describe visual surface, macrostructures describe page shape."

— [[`structure.md`](https://github.com/Nutlope/hallmark/blob/main/structure.md)](skills/hallmark/references/structure.md)

This separation ensures that even pages sharing a visual theme will differ structurally when assigned different macrostructures. The theme controls **how** elements look; the macrostructure controls **where** they go.

## Practical Implementation

### CLI Usage with Automatic Diversification

```bash

# Rebuilds the page with a new macrostructure enforced by stamp detection

hallmark redesign ./src

```

### Brief-Based Macrostructure Hinting

```markdown

## Brief

Create a landing page for a data-heavy SaaS product.  
**Macrostructure:** Stat-Led

```

### Programmatic Axis Override (Rarely Needed)

```javascript
import { setStructureAxis } from '@hallmark/structure';

// Forces bold CTA treatment regardless of macrostructure default
setStructureAxis('buttonVoice', 'oversizedSolid');

```

## Key Source Files

| Purpose | Path |
|:---|:---|
| Structural axes and anti-patterns | [[`skills/hallmark/references/structure.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/structure.md)](skills/hallmark/references/structure.md) |
| 21 macrostructure definitions | [[`skills/hallmark/references/macrostructures.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/macrostructures.md)](skills/hallmark/references/macrostructures.md) |
| Theme-specific defaults | [`skills/hallmark/references/themes/`](skills/hallmark/references/themes/) |
| CLI documentation | [[`README.md`](https://github.com/Nutlope/hallmark/blob/main/README.md)](README.md) |

## Summary

- **Macrostructures** provide 21 named page architectures with mandatory diversification across consecutive outputs.
- **Six structural axes** generate ~42,000 fingerprint combinations with a maximum 3-of-6 overlap rule.
- **Anti-pattern gates** block generic AI-template layouts at the generation level.
- **Theme/macrostructure decoupling** ensures visual consistency never compromises structural variety.
- **Stamp-based detection** enforces rules automatically within existing codebases.

## Frequently Asked Questions

### What is a structural fingerprint in Hallmark?

A structural fingerprint is Hallmark's complete layout specification. When derived from macrostructures, it's a single named architecture; when built from axes, it's a six-element tuple (heading placement, body composition, divider language, button voice, image treatment, reveal pattern) that uniquely identifies a page's structural identity.

### How does Hallmark prevent the same layout from appearing twice?

Hallmark enforces diversification at two levels: **macrostructure selection** cannot repeat until all alternatives are exhausted, and **axis-based fingerprints** may share no more than three of six choices with any preceding page. The system reads `/* Hallmark · macrostructure: <name> */` stamps in target codebases to track previous selections.

### What are the forbidden "AI slop" patterns Hallmark blocks?

Hallmark explicitly rejects centered hero sections with fade-up CTAs, three-column feature grids, and universal footer patterns—layouts that dominate generic AI-generated SaaS sites. These anti-patterns are hard-coded in [[`structure.md`](https://github.com/Nutlope/hallmark/blob/main/structure.md)](skills/hallmark/references/structure.md) as structural fingerprint rejections.

### Can I force a specific layout structure in Hallmark?

Yes. You can hint a macrostructure in your brief file using `**Macrostructure:** <name>` syntax, or programmatically override individual axes with `setStructureAxis()`. However, the diversification rules still apply—if your specified macrostructure matches a recent stamp, Hallmark will require an alternative.