Hallmark Macrostructures: Complete Guide to 21 Page Layout Patterns and Selection

Hallmark provides 21 distinct macrostructures—named, opinionated page layouts that bundle typography, spacing, navigation, and hero patterns into reusable stamps—to enforce design consistency and prevent repetitive layouts across consecutive pages.

Hallmark is an open-source landing page framework developed by Nutlope that codifies page architecture into Hallmark macrostructures. These pre-defined layouts range from grid-based features to long-form narratives, each defined in individual markdown files within the skills/hallmark/references/macrostructures/ directory. Understanding how to select and implement these macrostructures is essential for maintaining the framework's diversification rules and visual consistency.

What Are Hallmark Macrostructures?

Hallmark macrostructures are complete, opinionated page "shapes" that combine heading placement, body layout, divider language, button voice, image treatment, reveal patterns, navigation archetypes, and footer archetypes into a single, reusable fingerprint. According to skills/hallmark/references/macrostructures.md, the catalogue contains 21 distinct macrostructures ranging from grid-based layouts to long-form prose and highly visual hero patterns.

Each macrostructure is defined in its own markdown file (e.g., 01-bento-grid.md, 02-long-document.md) and referenced in code via a required comment stamp:

/* Hallmark · macrostructure: Bento Grid · … */

This stamp allows Hallmark to enforce the Diversification rule—consecutive pages in the same project must not reuse the same macrostructure (see macrostructures.md lines 7-10).

The 21 Hallmark Macrostructures

The following list details each macrostructure, its ideal use case, and its reference file location in the Nutlope/hallmark repository:

• Bento Grid (01-bento-grid.md) – Reach for this when showing "many small things"; ideal for feature pages and SaaS landing pages.
• Long Document (02-long-document.md) – Designed for narrative-heavy briefs, case studies, and founder posts.
• Marquee Hero (03-marquee-hero.md) – A bold, single-statement hero that dominates the viewport.
• Stat-Led (04-stat-led.md) – Data-centric stories where the metric serves as the hero element.
• Workbench (05-workbench.md) – Guided product tours with screenshots and interactive demonstrations.
• Conversational FAQ (06-conversational-faq.md) – Interview-style Q&A layouts with collapsible accordions.
• Manifesto (07-manifesto.md) – Polemical, large-type declarations for strong positioning statements.
• Photographic (08-photographic.md) – Full-bleed images that dominate each fold of the page.
• Quote-Led (09-quote-led.md) – Pull-quote hero layouts with prominent attribution.
• Specimen (10-specimen.md) – Editorial-type layouts featuring left-margin numbers and huge serif typography.
• Catalogue (11-catalogue.md) – Uniform grids for product variations or color palette displays.
• Letter (12-letter.md) – First-person, intimate notes from founders or leadership.
• Index-First (13-index-first.md) – Pure navigation lists without hero imagery.
• Narrative Workflow (14-narrative-workflow.md) – Numbered stages that tell a process timeline.
• Split Studio (15-split-studio.md) – Diptych layouts with alternating text-image sides.
• Feature Stack (16-feature-stack.md) – Sticky left pane with scroll-synced right pane for detailed comparisons.
• Type Specimen (17-type-specimen.md) – Typeface-first branding in foundry-style presentations.
• Portfolio Grid (18-portfolio-grid.md) – Filterable project cards for studios and agency homepages.
• Map / Diagram (19-map-diagram.md) – Large spatial diagrams that organize complex information.
• Ecosystem Index (20-ecosystem-index.md) – Multiple discovery surfaces featuring latest, featured, and categorized content.
• Component Playground (21-component-playground.md) – Interactive code-and-preview blocks for documentation.

When briefs are vague, start with the first ten macrostructures; they cover approximately 80% of typical SaaS or product briefs (macrostructures.md lines 11-14).

How to Select the Right Hallmark Macrostructure

Hallmark prescribes a four-step decision flow for selecting macrostructures (detailed in macrostructures.md lines 81-88):

1. Analyze the brief – Identify keywords that map to the "When to reach for it" statements in each macrostructure file (e.g., "data-heavy", "many small features", "personal note").
2. Check existing stamps – Search the codebase for existing macrostructure stamps (/* Hallmark · macrostructure: <name> · … */). If present, you must choose a different macrostructure to satisfy the diversification rule.
3. Match brief energy – Compare the brief's cues against the 21 macrostructure definitions; select the one that best aligns while being distinct from prior outputs for the same user.
4. Declare your selection – State the choice in plain text before writing code (e.g., "Macrostructure: Bento Grid.") and open the CSS with the required stamp.

Additional Selection Considerations

• Hero polish patterns – For hero-type macrostructures, you may optionally add one polish pattern (HP1–HP4) from the hero-enrichment catalogue (macrostructures.md lines 15-18).
• Navigation and footer defaults – Each macrostructure implies a navigation archetype (N1–N9) and footer archetype (Ft1–Ft8); defaults are defined in component-cookbook.md (macrostructures.md lines 19-22).
• SaaS page sequences – When using SaaS-friendly shapes (Bento Grid, Stat-Led, Workbench, Marquee Hero), follow the prescribed section order: hero → social proof → features → additional sections (macrostructures.md lines 53-66).

Implementation Example: Using the Bento Grid Macrostructure

Below is a minimal HTML and CSS implementation demonstrating the Bento Grid macrostructure, including the required comment stamp that enforces the diversification rule.

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>My Bento Grid Page</title>
  <link rel="stylesheet" href="styles.css">
</head>
<body>
  <!-- Hallmark · macrostructure: Bento Grid · version: 1.0 -->
  <header class="hero-fixed">
    <h1>All the Features, At a Glance</h1>
    <a class="chip outlined" href="#features">Explore</a>
  </header>

  <section class="bento">
    <article class="cell span-2x2">…hero feature…</article>
    <article class="cell span-1x1">…stat…</article>
    <article class="cell span-2x1">…image…</article>
  </section>
</body>
</html>

/* styles.css */
.bento { 
  display: grid; 
  gap: 1.5rem; 
  grid-template-columns: repeat(4, 1fr); 
}

.cell { 
  background: #fafafa; 
  padding: 1rem; 
}

.span-2x2 { 
  grid-column: span 2; 
  grid-row: span 2; 
}

.span-1x1 { 
  grid-column: span 1; 
  grid-row: span 1; 
}

.span-2x1 { 
  grid-column: span 2; 
  grid-row: span 1; 
}

The CSS comment stamp satisfies the diversification rule, while the irregular grid pattern follows the specifications in 01-bento-grid.md.

Key Reference Files for Hallmark Macrostructures

When working with Hallmark macrostructures, consult these source files in the Nutlope/hallmark repository:

• skills/hallmark/references/macrostructures.md – Master index containing the diversification rules and selection guidance.
• skills/hallmark/references/macrostructures/01-bento-grid.md (and 20 sibling files) – Detailed specifications for each individual macrostructure.
• skills/hallmark/references/hero-enrichment.md – Optional polish patterns (HP1–HP4) for hero macrostructures.
• skills/hallmark/references/component-cookbook.md – Default navigation archetypes (N1–N9) and footer archetypes (Ft1–Ft8).
• skills/hallmark/references/layout-and-space.md – Global spacing tokens used across all macrostructures.
• skills/hallmark/references/assets.md – Asset guidelines including logo walls referenced in SaaS sequences.

Summary

• Hallmark macrostructures are 21 pre-defined page layouts that bundle design patterns into reusable stamps stored in skills/hallmark/references/macrostructures/.
• Each macrostructure requires a specific CSS comment stamp (e.g., /* Hallmark · macrostructure: Bento Grid · … */) to enforce the diversification rule.
• The four-step selection process involves reading the brief, checking existing stamps, matching energy to patterns, and declaring the choice before coding.
• Optional hero polish patterns (HP1–HP4) and default navigation/footer archetypes (N1–N9, Ft1–Ft8) extend macrostructure capabilities.
• SaaS-friendly macrostructures follow specific section sequences defined in the reference documentation.

Frequently Asked Questions

What is the Hallmark macrostructure diversification rule?

The diversification rule prohibits consecutive pages in the same project from using the same macrostructure. This is enforced by searching for existing macrostructure stamps in the codebase; if a stamp is found, you must select a different layout from the 21 available options (as implemented in macrostructures.md lines 7-10).

How do I apply a Hallmark macrostructure to my HTML file?

Begin by selecting one of the 21 macrostructures from the reference files, then add the required CSS comment stamp at the top of your stylesheet: /* Hallmark · macrostructure: [Name] · version: 1.0 */. Match your HTML structure to the layout patterns described in the corresponding markdown file (e.g., grid definitions for Bento Grid or sticky panes for Feature Stack).

What are hero polish patterns in Hallmark?

Hero polish patterns (HP1–HP4) are optional enhancements available for hero-type macrostructures such as Marquee Hero or Photographic. These patterns provide additional visual treatments and are documented in skills/hallmark/references/hero-enrichment.md. They can be applied when the base macrostructure needs enhanced visual impact.

Where are the Hallmark macrostructure specifications stored?

All 21 macrostructure specifications are stored as individual markdown files in skills/hallmark/references/macrostructures/ within the Nutlope/hallmark repository. The master index and selection logic reside in skills/hallmark/references/macrostructures.md, while supporting documentation for components, layouts, and assets lives in adjacent files in the references/ directory.

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