How Hallmark Ensures Structural Variety in Generated UI: The Macrostructure Strategy

Hallmark guarantees structural variety by maintaining a curated catalog of 21 distinct macrostructures and enforcing a strict diversification rule that prevents consecutive builds from sharing the same layout family, validated by 57 automated quality gates.

Hallmark, an open-source UI generation tool from the Nutlope/hallmark repository, solves the template fatigue problem by treating structural diversity as a first-class constraint. Rather than varying only colors or typography within a single layout, Hallmark ensures that every generated interface employs a fundamentally different architectural approach. This article examines the technical mechanisms—from macrostructure catalogs to slop-test gates—that enforce this structural variety.

The Macrostructure Catalog: 21 Distinct Layout Families

Hallmark defines structural variety through a fixed catalog of 21 named page shapes, each representing a complete fingerprint of UI architecture. These macrostructures determine not just visual styling, but the fundamental arrangement of headings, content composition, navigation patterns, footer placement, and optional hero enrichments.

According to skills/hallmark/references/macrostructures.md, the catalog includes patterns such as:

• Bento Grid – Asymmetric tile-based layouts
• Marquee Hero – Full-bleed animated header sections
• Stat-Led – Data-forward presentation structures
• Split Studio – Divided viewport compositions

Each macrostructure functions as a complete page blueprint, ensuring that switching from one to another produces a categorically different user experience rather than a cosmetic variation.

The Diversification Rule: Preventing Structural Repetition

The core enforcement mechanism for structural variety in generated UI is the diversification rule, documented in skills/hallmark/references/structure.md. Before generating any page, Hallmark scans the project for the comment stamp /* Hallmark · macrostructure: <name> … */ that marks the previous build's layout family.

The system then applies a hard constraint: the new build must select a different macrostructure. Two consecutive outputs cannot share the same macrostructure family, preventing the gradual convergence toward repetitive layouts that plagues template-based generators.

When no prior stamp exists—such as in first-time builds—Hallmark reads the project brief to derive a domain cue (e.g., "SaaS" or "fashion") and presents three categorically different macrostructures to the user. The selection algorithm prioritizes the option most distant from any macrostructures previously used by that user, maximizing architectural diversity from the first generation.

Slop-Test Gates: Automated Quality Enforcement

Hallmark implements 57 automated quality gates that specifically reject structural duplication. These gates, defined in skills/hallmark/references/slop-test.md, operate as pre-output validators.

Gate 40: Macrostructure Duplication Detection

Gate 40 specifically flags any attempt to reuse the same macrostructure as a previous Hallmark run. The gate reads either the existing CSS stamp or the .hallmark/log.json file to identify the previously employed layout family, blocking generation if the requested macrostructure matches the historical record.

Gate 83: Variation Knob Requirements

Even when reusing the same archetype is unavoidable (in edge cases with severe domain constraints), Gate 83 enforces that at least one variation knob must change. These knobs include parameters like tile count, accent style, or grid density, ensuring that identical macrostructures still produce perceptibly different outputs.

Stamp-Based Verification and Auditing

Every generated CSS file begins with a machine-readable stamp that records the chosen macrostructure, genre, theme, enrichment, navigation style, and footer type. As documented in skills/hallmark/references/hero-enrichment.md, this stamp serves as the canonical record of structural intent.

The CLI audit command validates that the actual markup matches the stamped macrostructure:

hallmark audit ./site/example.css

This command, detailed in skills/hallmark/references/verbs/audit.md, checks for "macrostructure drift"—instances where the generated HTML structure deviates from the stamped architectural plan. If the audit detects that the same macrostructure was used in a previous generation, it flags the violation for correction.

The stamp format follows this structure:

/* Hallmark · genre: modern-minimal · macrostructure: Bento Grid · theme: garden · enrichment: none · nav: N3 · footer: Ft2 */

Reading this stamp programmatically allows build pipelines to enforce their own diversification policies:

import fs from 'fs';

const css = fs.readFileSync('site/example.css', 'utf8');
const stamp = css.match(/\/\* Hallmark · .* macrostructure: (\w+).* \*\//);
console.log('Current macrostructure:', stamp?.[1] ?? 'none');

Preserving Variety in Custom Theme Workflows

Even when users request custom themes, Hallmark maintains structural diversity through a macrostructure-first approach. According to skills/hallmark/references/custom-theme.md, the system selects the macrostructure before applying any bespoke visual styling.

This workflow ensures that custom color palettes or typography scales are applied on top of categorically different layouts, preventing the scenario where "custom" merely means "the same structure with different colors." The diversification rules remain active, meaning a user requesting three custom-themed landing pages will receive three distinct macrostructures, each with its own custom styling.

Developers can also force specific macrostructures via CLI while still respecting diversification constraints for subsequent builds:

hallmark build --macrostructure="Split Studio" --theme="cobalt"

Summary

• Hallmark maintains 21 distinct macrostructures (Bento Grid, Marquee Hero, etc.) that define complete page architectures rather than cosmetic variations.
• The diversification rule prevents consecutive builds from using the same macrostructure family by scanning for the /* Hallmark · macrostructure: … */ stamp.
• Slop-Test Gate 40 automatically blocks macrostructure reuse, while Gate 83 enforces variation knob changes when architectural overlap occurs.
• Stamp-based auditing via hallmark audit validates that generated markup matches the declared macrostructure, catching structural drift.
• Custom themes apply visual styling only after macrostructure selection, ensuring that bespoke designs remain architecturally diverse.

Frequently Asked Questions

How does Hallmark prevent generating the same layout twice in a row?

Hallmark scans for the comment stamp left in previously generated CSS files that records the last used macrostructure. The diversification rule, enforced by Gate 40 in the slop-test suite, blocks any new build from selecting the same macrostructure family as the immediate predecessor, forcing architectural variety.

What happens if I run Hallmark in a new project with no previous stamps?

When no prior stamp exists, Hallmark analyzes the project brief to derive a domain cue (such as "SaaS" or "fashion") and presents three categorically different macrostructures to choose from. The system recommends the option most distant from your historical usage patterns, ensuring structural variety from the first generation.

Can I force a specific macrostructure while maintaining diversification for future builds?

Yes. Using hallmark build --macrostructure="Split Studio" allows explicit selection for the current build. The diversification rule only prevents consecutive reuse, so your next build will still be required to select a different macrostructure from the catalog of 21 available options.

Does using a custom theme reduce structural variety?

No. According to the custom theme workflow in skills/hallmark/references/custom-theme.md, Hallmark selects the macrostructure before applying any custom palette. This ensures that even fully bespoke visual designs sit atop categorically different layouts, preserving the tool's guarantee of structural variety in generated UI.

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