How Hallmark's 21 Macrostructures Provide Structural Variety

Hallmark generates fundamentally different page layouts while maintaining brand cohesion through a two-level "2I" system of twenty-one distinct macrostructures combined with adjustable hero enrichment knobs.

The Hallmark design system separates page-level structure from visual styling, allowing developers to create diverse layouts without breaking thematic consistency. According to the Hallmark source code, this is achieved through macrostructures—self-contained page templates that encode layout, navigation, and footer patterns. The "2I" designation refers to the two-level hierarchy: macrostructure selection plus internal archetype configuration.

Understanding the Two-Level "2I" Architecture

Level 1: Macrostructure Selection

The macrostructure determines the top-level page shape. Hallmark provides twenty-one named options, each representing a distinct layout philosophy:

• Bento Grid: Tile-based hero with irregular spans
• Long Document: Prose-dense, reading-optimized flow
• Marquee Hero: Bold, media-forward landing treatment
• Workbench: Tool-like, action-oriented interface

These macrostructures are documented in [skills/hallmark/references/macrostructures.md](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/macrostructures.md), with individual implementations like [macrostructures/01-bento-grid.md](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/macrostructures/01-bento-grid.md) specifying concrete layout parameters, component choices, and default knob values.

Selecting a different macrostructure changes:

• Heading placement and hierarchy
• Hero treatment and media handling
• Section ordering and page rhythm
• Default navigation and footer archetypes

Level 2: Hero Enrichment and Polish Patterns

Within any macrostructure, hero enrichment knobs modify internal composition without altering the outer structural identity. As defined in [skills/hallmark/references/hero-enrichment.md](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/hero-enrichment.md), these include:

• Media archetypes: "photographic," "illustration-led," "stat-led," "quote-led"
• Polish patterns: HP1–HP4 styling variants
• Layout knobs: Tile count, span irregularity, accent placement

This two-level approach yields sub-variations within each macrostructure family. A Bento Grid with tiles=6, spans=irregular, accent=corner-only reads distinctly from one with tiles=8, spans=regular, accent=full-bleed—yet both remain immediately identifiable as Bento Grid layouts.

The Diversification Rule: Enforcing Structural Variety

Hallmark's variety guarantee is codified in [skills/hallmark/references/structure.md](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/structure.md). The system enforces a strict rule: consecutive pages in the same project must share the same theme but differ in macrostructure—or, if macrostructure families match, differ in at least one enrichment knob.

This rule is implemented through macrostructure stamps embedded in generated CSS:

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

The build pipeline parses these comments to track structural fingerprints. When a stamp already exists, Hallmark automatically selects a different macrostructure family for subsequent outputs. This prevents visual repetition while maintaining thematic alignment.

Macrostructures in Practice: Code Examples

Setting a Macrostructure Stamp

The first-level declaration establishes outer page shape:

/* Hallmark · macrostructure: Marquee Hero · theme: modern-minimal */

Adding Hero Enrichment Knobs

Second-level refinements adjust internal composition:

/* Hallmark · macrostructure: Marquee Hero · H1 hero knobs: size=xxl, alignment:left-bias */

Complete Page DNA

Full structural specification combines both levels with navigation and footer archetypes:

/* Hallmark · genre: modern-minimal · macrostructure: Bento Grid · theme: garden
   · H1 hero knobs: tiles=8, spans=irregular, accent=corner-only
   · nav: N5b · footer: Ft3 */

These comments drive automatic wiring of layout components, CSS variables, and responsive behavior through Hallmark's build pipeline.

How Structural Variety Emerges from the System

Hallmark's 21 macrostructures deliver variety through three operational patterns:

1. Categorical distance in brief responses: For any project brief, Hallmark offers three macrostructures that are fundamentally different—e.g., a grid-based layout versus a document-heavy format versus a media-forward hero.

2. Single-knob adjustments: Swapping one enrichment parameter (e.g., "stat-led" to "quote-led") fine-tunes expression without structural rupture.

3. Thematic consistency across shape changes: Color, typography, and component styling remain locked to the project theme while page architecture shifts dramatically.

Each macrostructure also encodes default nav archetypes and footer archetypes from [component-cookbook.md](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/component-cookbook.md), ensuring that structural variety extends to full-page DNA rather than isolated hero treatments.

Summary

• Twenty-one macrostructures provide the foundation of Hallmark's structural variety, each representing a distinct page-level layout philosophy.
• Two-level "2I" architecture separates outer shape (macrostructure) from internal composition (hero enrichment knobs), yielding combinatorial diversity.
• Macrostructure stamps enforce the diversification rule by tracking structural fingerprints and preventing repetition within themed projects.
• Automatic archetype binding ensures navigation and footer patterns align with macrostructure selection, creating coherent full-page templates.

Frequently Asked Questions

What file contains the complete list of Hallmark's 21 macrostructures?

The index is maintained in [skills/hallmark/references/macrostructures.md](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/macrostructures.md). Individual macrostructure specifications live in the adjacent macrostructures/ directory, such as [01-bento-grid.md](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/macrostructures/01-bento-grid.md).

How does Hallmark prevent the same macrostructure from being used twice in a project?

The system parses macrostructure stamps in generated CSS headers. If a stamp match is detected, Hallmark's selection algorithm picks a different macrostructure family automatically, as documented in [skills/hallmark/references/structure.md](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/structure.md).

Can you adjust a macrostructure's appearance without changing its identity?

Yes. Hero enrichment knobs modify internal composition—media type, polish pattern, tile configuration—while preserving the macrostructure's recognizable outer shape. These are defined in [hero-enrichment.md](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/hero-enrichment.md).

What connects macrostructures to navigation and footer patterns?

Each macrostructure specifies default nav archetypes and footer archetypes that complete the page-level DNA. These component bindings are cataloged in [component-cookbook.md](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/component-cookbook.md), ensuring structural decisions propagate consistently through the entire page hierarchy.

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