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

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, 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:

/* 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.

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

Hallmark follows a deterministic pick-by-brief workflow outlined in 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 and component-cookbook.md:

/* 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 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.

Navigation and Footer Routing

Macrostructures implicitly select appropriate navigation and footer archetypes based on page genre. The routing tables in 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), 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.
• 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. 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. 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.

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