# How Hallmark's 21 Macrostructures Provide Structural Variety

> Discover how Hallmark's 21 macrostructures create diverse page layouts with brand cohesion using a two-level 2I system and hero enrichment knobs for stunning structural variety.

- Repository: [Hassan El Mghari/hallmark](https://github.com/Nutlope/hallmark)
- Tags: deep-dive
- Published: 2026-08-14

---

**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](https://github.com/Nutlope/hallmark), 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)](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/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)](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)](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:

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

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

```

### Adding Hero Enrichment Knobs

Second-level refinements adjust internal composition:

```css
/* 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:

```css
/* 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/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)](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/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)](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/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/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.