What Is a Macrostructure in Hallmark? A Guide to Page Layout Architecture

A macrostructure in Hallmark is a high-level page shape that bundles layout decisions, visual hierarchy, and interaction patterns into one of 21 named templates, ensuring every landing page has a distinct fingerprint.

In the Nutlope/hallmark repository, the macrostructure serves as the foundational architectural decision for generating landing pages. This system allows designers to lock in a coherent page fingerprint by selecting from 21 predefined high-level layouts that determine everything from grid behavior to component placement.

What Defines a Macrostructure?

A macrostructure is not merely a grid system; it is a complete page-shape that dictates heading placement, body composition, divider language, button voice, image treatment, and reveal patterns. When you select a macrostructure, you instantly constrain the design space to a specific visual rhythm—such as an asymmetric Bento Grid or a full-bleed Marquee Hero—ensuring the output aligns with the brief’s tone and stands distinct from other Hallmark-generated sites. These definitions live in skills/hallmark/references/macrostructures.md, which catalogs all available layouts and their behavioral constraints.

The 21 Hallmark Macrostructures and Selection Rules

Named Layout Templates

The Hallmark system provides exactly 21 distinct macrostructures, each representing a unique landing page archetype. Examples include Bento Grid, Marquee Hero, Stat-Led, Quote-Led, and Specimen (lines 25–49 of macrostructures.md). Each name encodes a specific spatial logic; for instance, the Bento Grid macrostructure creates an asymmetric tile layout where tile sizes vary to establish visual rhythm (lines 29–33).

The Diversification Rule

Hallmark enforces architectural variety through a strict diversification check. Before selecting a macrostructure, the generator scans the codebase for an existing comment stamp matching the pattern /* Hallmark · macrostructure: <name> … */. The new selection must differ from any previously used macrostructure in the same project (lines 7–10 of macrostructures.md). This prevents visual repetition across pages generated within the same brief.

Every Hallmark output file begins with a mandatory CSS comment that records the chosen macrostructure and its configuration knobs:

/* Hallmark · macrostructure: Bento Grid · F1 Bento knobs: tiles=6, spans=irregular, accent=corner-only · ... */

Layering Enrichments and Polish Patterns

Decision Sequence

The macrostructure is always chosen first in the design pipeline, establishing the foundational "shape" of the page. Only after this commitment does Hallmark layer optional enrichment archetypes (E1–E8) and polish patterns (HP1–HP4) on top (lines 13–18 of macrostructures.md). This sequencing ensures that decorative enhancements respect the underlying structural logic rather than fighting it.

Hero Enrichments and Polish

For hero sections specifically, the skills/hallmark/references/hero-enrichment.md file defines how to apply the eight enrichment archetypes (E1–E8) and four Hallmark polish patterns (HP1–HP4). These layers adjust micro-interactions and visual finishes without altering the core macrostructure grid.

Navigation and Footer Archetypes

Each macrostructure implies default navigation and footer components drawn from standardized archetype libraries. The system automatically routes to specific navigation styles (N1–N13) and footer variants (Ft1–Ft8) based on the selected macrostructure, as defined in the routing tables of skills/hallmark/references/component-cookbook.md (lines 19–22). This ensures that auxiliary components match the structural energy of the main content area.

Implementing Macrostructures in Code

The Selection Workflow

Hallmark prescribes a rigorous five-step workflow for applying a macrostructure (lines 81–88 of macrostructures.md):

1. Read the brief to understand tonal requirements.
2. Check for existing /* Hallmark · macrostructure: ... */ stamps to enforce diversification.
3. Match the brief’s energy to one of the 21 macrostructures.
4. State the pick explicitly in the design log.
5. Write the code with the required stamp comment.

Layout Implementation

Once selected, the macrostructure drives the HTML structure. A Bento Grid implementation uses specific CSS classes that map to the macrostructure’s grid logic:

<!-- Hero section (macrostructure‑specific) -->
<section class="hero bento-grid">
  <div class="tile tile--large">Feature 1</div>
  <div class="tile tile--small">Feature 2</div>
  <div class="tile tile--medium">Feature 3</div>
  <!-- …additional tiles… -->
</section>

The .bento-grid class is defined in Hallmark’s design system primitives (referenced in skills/hallmark/references/structure.md) to create the asymmetric grid behavior specified by the macrostructure definition.

Summary

• A macrostructure is one of 21 high-level page shapes in Hallmark that bundles layout, hierarchy, and interaction patterns into a single named choice.
• The system enforces the diversification rule by scanning for /* Hallmark · macrostructure: ... */ stamps to prevent layout repetition across pages.
• Selection follows a strict sequence: macrostructure first, then optional E1–E8 enrichments, then HP1–HP4 polish patterns.
• Each macrostructure implies specific N1–N13 navigation and Ft1–Ft8 footer archetypes from the component cookbook.
• Implementation requires a mandatory CSS comment stamp and adherence to the five-step selection workflow defined in macrostructures.md.

Frequently Asked Questions

What are the 21 macrostructures available in Hallmark?

The catalog includes layouts such as Bento Grid, Marquee Hero, Stat-Led, Quote-Led, and Specimen, among others. These are fully enumerated in lines 25–49 of skills/hallmark/references/macrostructures.md. Each represents a distinct spatial logic for organizing landing page content.

How does Hallmark prevent duplicate macrostructures in the same project?

Hallmark enforces a diversification rule that scans existing files for the comment stamp /* Hallmark · macrostructure: <name> … */. The generator rejects any macrostructure already present in the project, ensuring visual variety across multiple generated pages (lines 7–10 of macrostructures.md).

What comes after selecting a macrostructure?

After locking in the macrostructure, designers may layer enrichment archetypes (E1–E8) for content variation and polish patterns (HP1–HP4) for micro-interaction details. These optional layers are applied sequentially and are defined in hero-enrichment.md and related reference files.

Where are the navigation and footer archetypes defined?

The N1–N13 navigation and Ft1–Ft8 footer archetypes are defined in skills/hallmark/references/component-cookbook.md (lines 19–22). Each macrostructure maps to specific defaults in these routing tables, ensuring that header and footer components align with the page’s overall structural energy.

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