# How Hallmark's Macrostructure System Works: A Complete Guide to Page Layout Generation

> Discover how Hallmark's macrostructure system works. Learn its deterministic pipeline for mapping creative briefs to 21 page shapes using stamp-based diversification and machine-readable metadata.

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

---

**Hallmark's macrostructure system is a deterministic pipeline that maps creative briefs to one of 21 predefined page shapes, enforcing visual diversity through stamp-based diversification rules and machine-readable metadata.**

The Nutlope/hallmark repository implements a disciplined approach to AI-generated page design through its **macrostructure system**—a curated catalogue of 21 composable page architectures. Rather than assembling layouts from independent axes, Hallmark selects a holistic "visual fingerprint" that governs everything from section ordering to component selection.

## What Is the Macrostructure Catalogue?

The macrostructure catalogue serves as Hallmark's single source of truth for page topology. Defined in **[`skills/hallmark/references/macrostructures.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/macrostructures.md)**, this catalogue contains 21 named entries—such as *Bento Grid*, *Marquee Hero*, and *Split Studio*—that encode complete page blueprints.

Each entry bundles:
- Heading placement and body composition
- Divider language and button voice
- Image treatment and reveal patterns
- Navigation and footer archetype routing

Rather than treating these as separate decisions, Hallmark collapses them into a **single composable token** that determines the entire page silhouette.

## The Diversification Rule: Enforcing Visual Variety

Before selecting a macrostructure, Hallmark scans existing CSS files for **stamp comments**—machine-readable markers that record previously used page shapes. The system searches for comments matching this pattern:

```css
/* Hallmark · macrostructure: <name> · … */

```

If a stamp exists in the codebase, the diversification rule mandates that the new build must select a **different** macrostructure. This prevents consecutive outputs from converging on the same visual template, ensuring categorical variety across generations. The rule is documented in the "Diversification rule" section of **[`macrostructures.md`](https://github.com/Nutlope/hallmark/blob/main/macrostructures.md)**.

## The Pick-by-Brief Workflow (5-Step Process)

Hallmark follows a deterministic **pick-by-brief workflow** outlined in **[`macrostructures.md`](https://github.com/Nutlope/hallmark/blob/main/macrostructures.md)** to map project requirements to page architecture:

1. **Read the brief** – Surface cues like "data-heavy," "personal note," or "list of links" that indicate appropriate energy levels.
2. **Inspect existing stamps** – Exclude any macrostructure already present in CSS files to satisfy the diversification rule.
3. **Match energy to a macrostructure** – Select the catalogue entry whose description best aligns with the brief's semantic requirements.
4. **State the pick** – Announce the selection (e.g., "Macrostructure: Bento Grid.") before emitting any code.
5. **Build** – Generate HTML/CSS that respects the chosen macrostructure's constraints and component routing.

## Macrostructure Stamps and Machine-Readable Metadata

Every generated CSS file begins with a **macrostructure stamp**—a structured comment that records architectural decisions for future reference and diversification checks. This stamp captures:

- The selected macrostructure name
- Hero enrichment choices
- Navigation and footer archetypes
- Variation knob values for components

Example from the stamp format defined in **[`macrostructures.md`](https://github.com/Nutlope/hallmark/blob/main/macrostructures.md)** and **[`component-cookbook.md`](https://github.com/Nutlope/hallmark/blob/main/component-cookbook.md)**:

```css
/* Hallmark · macrostructure: Bento Grid ·
   F1 Bento knobs: tiles=6, spans=irregular, accent=corner-only ·
   N5 Floating pill · Ft2 Inline single line */

```

## Integration With Hero Enrichment and Component Cookbook

The macrostructure system does not operate in isolation. It interacts with three additional vocabularies to realize complete page implementations.

### Hero Enrichment

After selecting a base macrostructure, Hallmark may apply **hero enrichment**—optional hero archetypes and polish patterns that modify the primary section. These enrichments are documented in **[`skills/hallmark/references/hero-enrichment.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/hero-enrichment.md)** and combine with the macrostructure to create hybrid layouts.

### Component Archetypes and Variation Knobs

Each macrostructure determines which **component archetypes** are permitted inside the page. For example, the *Bento Grid* macrostructure specifically allows the *F1 Bento* component archetype. Each archetype exposes **variation knobs**—parameters like `tiles=6` or `spans=irregular`—that are recorded in the stamp for reproducibility. These relationships are catalogued in **[`skills/hallmark/references/component-cookbook.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/component-cookbook.md)**.

### Navigation and Footer Routing

Macrostructures implicitly select appropriate navigation and footer archetypes based on page genre. The routing tables in **[`component-cookbook.md`](https://github.com/Nutlope/hallmark/blob/main/component-cookbook.md)** map each macrostructure to specific nav/footer combinations—such as *N5 Floating pill* navigation paired with *Ft2 Inline single line* footers—ensuring semantic consistency between page structure and peripheral elements.

## Why Macrostructures Matter

By selecting whole-page shapes rather than assembling independent design axes, Hallmark achieves three critical outcomes:

- **Categorical variety** – Different macrostructures produce radically different page silhouettes, preventing the "same-y" look common in AI-generated designs.
- **Consistent semantics** – The same macrostructure reliably drives section ordering (such as the SaaS sequence defined in **[`macrostructures.md`](https://github.com/Nutlope/hallmark/blob/main/macrostructures.md)**), creating predictable information architecture.
- **Reduced slop** – The diversification rule and knob variation guards prevent the system from falling back to a single default template.

## Summary

- Hallmark's macrostructure system selects from **21 predefined page shapes** defined in **[`macrostructures.md`](https://github.com/Nutlope/hallmark/blob/main/macrostructures.md)**.
- The **diversification rule** enforces visual variety by checking existing CSS stamps before selecting a macrostructure.
- A **5-step pick-by-brief workflow** maps project requirements to appropriate page architectures.
- **Macrostructure stamps** record decisions in machine-readable CSS comments for future diversification checks.
- The system integrates with **hero enrichment**, **component archetypes**, and **nav/footer routing** to generate complete, semantically consistent pages.

## Frequently Asked Questions

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

Hallmark implements a **diversification rule** that inspects existing CSS files for stamp comments containing `/* Hallmark · macrostructure: <name> · … */`. If a stamp exists, the system must select a different macrostructure for the new build, ensuring no two consecutive outputs share the same page shape.

### What information is stored in a macrostructure stamp?

The stamp records the selected macrostructure name (e.g., *Bento Grid*), component variation knobs (like `tiles=6` or `spans=irregular`), navigation archetype (e.g., *N5 Floating pill*), and footer archetype (e.g., *Ft2 Inline single line*). This metadata enables the diversification rule and provides reproducible build parameters.

### Where are the 21 macrostructure definitions located?

The complete catalogue of 21 macrostructures—including *Bento Grid*, *Marquee Hero*, and *Split Studio*—is defined in **[`skills/hallmark/references/macrostructures.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/macrostructures.md)**. Individual macrostructure specifications may also exist in separate files within the **`skills/hallmark/references/macrostructures/`** directory.

### How do macrostructures interact with component selection?

Each macrostructure implicitly routes to specific **component archetypes** documented in **[`skills/hallmark/references/component-cookbook.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/component-cookbook.md)**. For instance, the *Bento Grid* macrostructure utilizes the *F1 Bento* component archetype, while also determining permitted navigation and footer patterns through routing tables in the same file.