Hallmark Macrostructures: 21 Complete Page-Shape Examples Explained

Hallmark provides 21 named macrostructures—complete page-shape specifications that determine heading placement, body composition, hero type, navigation, footer, and interaction patterns in a single selection.

The Hallmark open-source design system packages entire page architectures into reusable macrostructures. Rather than configuring dozens of independent layout axes, designers pick one macrostructure from the index and the system constructs the full page around that fingerprint. This guide covers all 21 Hallmark macrostructure examples, their definitions, and how to implement them in your projects.

---

What Are Hallmark Macrostructures?

A macrostructure in Hallmark is a complete page blueprint stored as a Markdown file in skills/hallmark/references/macrostructures/. Each specification dictates:

• Hero composition and visual treatment
• Body content organization
• Navigation and footer defaults
• Interaction patterns and scroll behavior

When building a page, Hallmark reads your selected macrostructure definition and assembles the corresponding CSS and component structure. The choice is recorded via a stamp comment at the top of generated stylesheets:

/* Hallmark · macrostructure: Bento Grid · genre: modern-minimal · theme: midnight · nav: N3 · footer: Ft4 */

This stamp enables auditability—future runs can detect which macrostructure governs an existing page.

---

How to Access the Macrostructure Index

The canonical list lives in skills/hallmark/references/macrostructures.md. This index maps number codes to names, descriptions, and links to full specification files. Before any build, Hallmark's design flow (documented in skills/hallmark/SKILL.md) requires consulting this index.

The macrostructure specifications are numbered 01 through 21 and stored as individual Markdown files under skills/hallmark/references/macrostructures/XX-name.md.

---

All 21 Hallmark Macrostructure Examples

Content-Focused Macrostructures

These macrostructures prioritize text, narrative, or information density over visual spectacle.

| # | Macrostructure | Core Pattern | Best For |

|---|---------------|------------|----------| | 02 | Long Document | Continuous prose with inline section heads, no marketing hero | Memos, letters, journal entries | | 06 | Conversational FAQ | Bold questions with brief answers, often collapsible | Support pages, help centers | | 07 | Manifesto | Large-type polemical declaration preceding any sell | Brand belief statements | | 12 | Letter | First-person intimate note opening with greeting | Personal announcements, founder messages |

Long Document (02-long-document.md) eliminates hero sections entirely—the page reads like a typed memo. Letter (12-letter.md) adds epistolary framing: salutations, sign-offs, and deliberately no call-to-action buttons above the fold.

Visual-First Macrostructures

These patterns lead with imagery, typography, or spatial arrangements.

| # | Macrostructure | Core Pattern | Best For |

|---|---------------|------------|----------| | 01 | Bento Grid | Irregular modular blocks mixing features, quotes, images, stats | Dashboards, feature overviews | | 08 | Photographic | Single huge image per fold, text as tiny annotation | Galleries, lookbooks, visual portfolios | | 10 | Specimen | Numbered left-margin labels, huge serif, asymmetric columns | Editorial designs, type foundries | | 17 | Type Specimen | Typography itself as the product showcase | Font sales, typographic tools |

Bento Grid (01-bento-grid.md) creates rhythm through uneven cell sizes—some blocks expand to emphasize priority content. Photographic (08-photographic.md) inverts typical hierarchy: viewers look before they read.

Hero-Centric Macrostructures

These patterns define the entire page through their above-fold treatment.

| # | Macrostructure | Core Pattern | Best For |

|---|---------------|------------|----------| | 03 | Marquee Hero | Single bold statement or visual fills viewport | Campaign landers, announcements | | 04 | Stat-Led | Giant number (metric, count, percentage) as hero | Reports, impact pages, data stories | | 09 | Quote-Led | Pull-quote with attribution as headline | Testimonials, press coverage, borrowed credibility |

Marquee Hero (03-marquee-hero.md) treats the fold as the complete message—everything below is secondary elaboration. Stat-Led (04-stat-led.md) demands precise supporting content: the number must be defensible, with qualifications following immediately.

Product-Demonstration Macrostructures

These patterns showcase software, workflows, or interactive systems.

| # | Macrostructure | Core Pattern | Best For |

|---|---------------|------------|----------| | 05 | Workbench | Screenshots in frames as primary guided tour | SaaS product pages, feature tours | | 14 | Narrative Workflow | Numbered stages showing user journey over time | Onboarding, process explanations | | 16 | Feature Stack | Sticky left pane + scroll-synced right screenshot cycling | Detailed feature breakdowns | | 21 | Component Playground | Interactive code-and-preview blocks with copy-paste | Design systems, documentation |

Workbench (05-workbench.md) frames interface screenshots as museum exhibits—context and annotation surround each image. Feature Stack (16-feature-stack.md) creates a fixed reference point: labels stay visible while proof scrolls, enabling dense explanation without disorientation.

Navigation and Discovery Macrostructures

These patterns prioritize movement between destinations over singular narrative.

| # | Macrostructure | Core Pattern | Best For |

|---|---------------|------------|----------| | 11 | Catalogue | Uniform grid of variations (typefaces, palettes, SKUs) | Indexes, browse-first experiences | | 13 | Index-First | Pure link list, no hero image or narrative flow | Directory pages, archives | | 18 | Portfolio Grid | Filterable project cards | Studio homepages, creative portfolios | | 20 | Ecosystem Index | Multiple discovery surfaces (featured, latest, by category, by people) | Platforms, marketplaces, content hubs |

Catalogue (11-catalogue.md) enforces strict uniformity—each cell contains the same information architecture, varying only in content. Ecosystem Index (20-ecosystem-index.md) deliberately fragments attention across multiple entry points, recognizing that browsing is the core value.

Spatial and Structural Macrostructures

These patterns use physical or diagrammatic metaphors.

| # | Macrostructure | Core Pattern | Best For |

|---|---------------|------------|----------| | 15 | Split Studio | Diptych layout alternating text/proof direction down page | Case studies, comparative presentations | | 19 | Map / Diagram | Large spatial diagram organizing content nonlinearly | System documentation, floor plans, network visualizations |

Split Studio (15-split-studio.md) creates rhythm through directional alternation: first text-left proof-right, then reversed. Map / Diagram (19-map-diagram.md) abandons linear scroll entirely—the page becomes a navigable space.

---

Implementing Hallmark Macrostructures in Code

Selecting a Macrostructure at Build Time

Pass the macrostructure name to Hallmark's run configuration:

const macro = "Split Studio"; // chosen from the index

await hallmark.run({
  macrostructure: macro,
  genre: "atmospheric",
  theme: "cobalt"
});

Hallmark loads skills/hallmark/references/macrostructures/15-split-studio.md and constructs the page according to its specification.

Auditing Existing Pages for Macrostructure Compliance

Verify that stamped CSS matches actual implementation:

// hallmark-audit.js – simplified example
const css = readFile("styles.css");
const stamp = css.match(/Hallmark · macrostructure: (.+?) ·/);

if (!stamp) throw "Missing macrostructure stamp!";

console.log(`Page uses macrostructure: ${stamp[1]}`);

The audit checks layout fidelity—confirming, for example, that a page stamped Split Studio actually implements diptych alternation.

---

Key Files in the Hallmark Macrostructure System

File Path	Purpose
skills/hallmark/references/macrostructures.md	Master index listing all 21 macrostructures with descriptions and links
skills/hallmark/references/macrostructures/XX-*.md	Individual specification files (21 total) containing layout rules, required components, defaults
skills/hallmark/SKILL.md	Design workflow mandating macrostructure index consultation before builds
skills/hallmark/references/structure.md	Primitive layout axes that macrostructures encapsulate; reference for custom modifications
site/_tests/*	Real-world briefs demonstrating macrostructure selections

---

Summary

• Hallmark macrostructures are 21 complete page-shape specifications that replace piecemeal layout configuration
• Each macrostructure lives in skills/hallmark/references/macrostructures/XX-name.md with full implementation rules
• Selection is recorded via CSS stamp comments enabling audit and reuse
• Categories include: Content-Focused (Long Document, Letter, Manifesto), Visual-First (Bento Grid, Photographic, Specimen), Hero-Centric (Marquee Hero, Stat-Led, Quote-Led), Product-Demonstration (Workbench, Feature Stack, Component Playground), Navigation/Discovery (Catalogue, Index-First, Ecosystem Index), and Spatial/Structural (Split Studio, Map/Diagram)
• The canonical index at skills/hallmark/references/macrostructures.md governs all valid selections

---

Frequently Asked Questions

How do I choose the right Hallmark macrostructure for my project?

Start by identifying your page's primary goal. If demonstrating software, select Workbench or Feature Stack. If establishing credibility through data, use Stat-Led. For narrative-heavy content, Long Document or Letter removes visual distraction. Consult skills/hallmark/references/macrostructures.md to compare descriptions against your content inventory.

Can I modify a macrostructure after selecting it?

Yes, through skills/hallmark/references/structure.md which documents the primitive axes each macrostructure combines. However, significant deviations may break audit compliance. For custom needs, Hallmark recommends creating a new macrostructure specification rather than hacking existing ones.

What happens if I omit the macrostructure stamp from generated CSS?

Hallmark audits will flag the file as non-compliant. The stamp enables deterministic regeneration—without it, subsequent runs cannot identify which of the 21 macrostructures governs the page, forcing manual reconstruction of layout decisions.

Where can I see macrostructures implemented in real projects?

The site/_tests/ directory contains briefs demonstrating macrostructure selections across varied contexts. These test cases show how Bento Grid, Split Studio, and Component Playground adapt to different content types while maintaining their structural integrity.

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