What Is Macrostructure Diversification in Hallmark? How It Guarantees Output Variety

Macrostructure diversification in Hallmark is a deterministic rule that prevents the same page shape from being generated twice in a row by recording the previous macrostructure and forcing the next output to select a different one from its catalog of 21 named shapes.

Hallmark is an open‑source AI coding agent that generates multi‑page applications. Each page it builds combines a macrostructure (the overall layout shape), a theme, a type‑scale, and other design tokens. The macrostructure diversification rule lives at the heart of Hallmark's ability to produce visually distinct outputs across iterations. According to the Nutlope/hallmark source code, this mechanism operates through a simple but reliable stateful check.

How Macrostructure Diversification Works

The diversification rule follows a five‑step workflow defined in [SKILL.md](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md) and enforced across multiple verb implementations.

Step 1: Read the Previous Macrostructure Stamp

Hallmark looks for a durable record of the last run. This stamp appears as a comment in the generated CSS or <style> block and is also stored in /.hallmark/log.json. The stamp records the exact macrostructure name used previously—e.g., /* Hallmark · macrostructure: Bento Grid … */.

Reading this stamp gives the system ground truth about what shape was already shipped.

Step 2: Check for a design.md File

The rule adapts based on project constraints. If a design.md file exists at the project root, the diversification logic is inverted: consecutive pages must share the same macrostructure to maintain a stable system across the application. As documented in design‑md.md, this override exists for projects that prioritize consistency over variety.

Step 3: Select a Different Macrostructure

Hallmark chooses from 21 named macrostructures catalogued in [macrostructures.md](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/macrostructures.md). Unless design.md forces consistency, the selection algorithm excludes the macrostructure recorded in the previous stamp.

// Load the 21-shape catalog from macrostructures.md
const allMacros = [
  'Bento Grid',
  'Long Document',
  'Marquee Hero',
  'Split Hero',
  'Center Focus',
  'Editorial Grid',
  'Card Flow',
  'Feature Stack',
  'Minimal Cover',
  'Dashboard Grid',
  'Asymmetric Hero',
  'Narrative Scroll',
  'Gallery Masonry',
  'Service List',
  'Pricing Focus',
  'Testimonial Wall',
  'Contact Split',
  'Footer Heavy',
  'Nav + Content',
  'Sidebar Persistent',
  'Floating Panels'
];

// Filter out the previous macrostructure
const candidates = allMacros.filter(m => m !== lastMacro);

// Select from remaining options
const chosenMacro = candidates[Math.floor(Math.random() * candidates.length)];

Changing the macrostructure is the primary driver of visual variety—it guarantees the page shape itself differs from the previous output.

Step 4: Write a New Stamp for Future Runs

After generation, Hallmark persists the selected macrostructure, theme, and other tokens. This stamping mechanism is detailed in [verbs/audit.md](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/verbs/audit.md):

// Write the new stamp to /.hallmark/log.json
const newEntry = {
  timestamp: Date.now(),
  macrostructure: chosenMacro,  // e.g., "Marquee Hero"
  theme: 'lumen',
  typeScale: 'compact',
  colorAnchor: 'slate'
};

fs.appendFileSync('.hallmark/log.json', JSON.stringify(newEntry) + '\n');

The stamp also appears as a comment in the generated output, creating a human‑readable audit trail.

Step 5: Enforce the Rule on Subsequent Runs

When Hallmark starts its next run, it checks the stamp. If the algorithm would select the same macrostructure, [verbs/redesign.md](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/verbs/redesign.md) mandates that the system abort that choice and pick a different family. The document explicitly states: "consecutive pages MUST differ on macrostructure."

This enforcement prevents "slop‑test" failures—cases where two generated outputs appear visually identical despite being separate iterations.

The 21 Macrostructures That Power Variety

The complete catalog in [macrostructures.md](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/macrostructures.md) defines all legal shapes. While the full list is maintained in the source, common patterns include:

• Bento Grid – Asymmetric card‑based layouts popular in SaaS landing pages
• Marquee Hero – Full‑bleed headline with scrolling social proof
• Long Document – Dense, editorial single‑column reading experience
• Split Hero – Two‑pane composition with image/text separation
• Dashboard Grid – Data‑dense administrative interfaces

Each macrostructure represents a distinct page‑shape DNA—swapping it fundamentally restructures the information hierarchy.

Key Implementation Files

File	Role in Macrostructure Diversification
[macrostructures.md](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/macrostructures.md)	Canonical list of 21 named macrostructures; source of valid selections
[SKILL.md](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md)	Core skill document defining the diversification rule and stamping protocol
design‑md.md	Specifies when to invert the rule for system‑consistency projects
[verbs/redesign.md](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/verbs/redesign.md)	Contains the mandatory "MUST differ" enforcement language
[verbs/audit.md](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/verbs/audit.md)	Validates stamps match generated output; detects "variety drift"
[custom-theme.md](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/custom-theme.md)	Ensures custom themes still respect diversification axes

Macrostructure Diversification vs. Other Variety Mechanisms

Hallmark employs diversification across multiple axes, but macrostructure is the most impactful:

Axis	What Changes	Impact on Variety
Macrostructure	Page shape/layout	Highest – complete information hierarchy重组
Theme	Color system, component styling	Medium – visual mood shifts
Type scale	Font sizes, density	Low‑medium – readability adjustments
Color anchor	Base hue family	Low – palette temperature change

The diversification rule prioritizes macrostructure because layout is the strongest signal of visual difference to human observers.

Summary

• Macrostructure diversification is a stateful rule that records the previous page shape and forces the next output to select a different one
• The mechanism relies on stamps in /.hallmark/log.json and inline CSS comments to maintain durable state across runs
• 21 named macrostructures provide the pool of legal shapes, defined in [macrostructures.md](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/macrostructures.md)
• A design.md file inverts the rule, requiring consistency instead of variety for multi‑page applications
• Enforcement logic lives in [verbs/redesign.md](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/verbs/redesign.md), while [verbs/audit.md](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/verbs/audit.md) validates compliance

Frequently Asked Questions

What happens if Hallmark runs out of macrostructures to choose from?

Hallmark does not exhaust the pool. With 21 macrostructures and only the immediate previous run excluded, 20 options remain available at every step. The rule only prohibits consecutive repetition, not reuse across the project history. A macrostructure can reappear after one intervening generation.

Does macrostructure diversification affect performance or generation time?

No measurable impact. The diversification check is a synchronous filter operation on a small in‑memory array. According to the source code, this occurs after theme selection and before component generation—adding negligible latency compared to the LLM inference time for actual code generation.

Can I disable macrostructure diversification for a specific project?

Yes. Create a design.md file at your project root. As documented in design‑md.md, this presence signal inverts the rule: Hallmark will maintain the same macrostructure across consecutive pages to preserve system consistency. Remove or rename the file to restore diversification behavior.

How does Hallmark handle corrupted or missing stamps?

The system treats missing stamps as no previous state—allowing any macrostructure selection. For corrupted log.json entries, [verbs/audit.md](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/verbs/audit.md) defines a drift detection protocol that flags mismatches between the stamped macrostructure and the actual generated layout. The audit verb can recommend regeneration when inconsistency is detected.

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