Which Hallmark Macrostructure Should I Pick? A Complete Decision Guide

Choose a Hallmark macrostructure based on your content type, information hierarchy, and brand narrative, selecting from 18 opinionated layout patterns located in skills/hallmark/references/macrostructures/.

The Nutlope/hallmark repository provides a design-system-style framework that organizes page layouts into reusable macrostructures—ready-to-use Markdown files that define specific page architectures. When deciding which Hallmark macrostructure to pick, you must evaluate architectural dimensions like content rhythm, interaction density, and responsive constraints to ensure the layout aligns with your specific design goals.

Understanding Hallmark Macrostructures

Hallmark macrostructures are opinionated page layouts stored as individual Markdown files in the skills/hallmark/references/macrostructures/ directory. Each file represents a distinct architectural pattern designed to solve specific design problems, from showcasing portfolios to presenting long-form documents.

The repository contains 18 predefined macrostructures, including:

• 01-bento-grid.md for mosaic-style content cards
• 02-long-document.md for scroll-heavy text
• 03-marquee-hero.md for hero-driven landing pages
• 04-stat-led.md for data-centric presentations
• 18-portfolio-grid.md for visual work collections

Decision Criteria for Choosing a Macrostructure

When evaluating which Hallmark macrostructure to pick, consider these five architectural dimensions:

Content Type

Determine whether your primary content is a grid of items, a narrative article, or a single-page showcase. The Bento-Grid (01-bento-grid.md) suits heterogeneous content cards, while Long-Document (02-long-document.md) optimizes for progressive scrolling through text-heavy pages.

Information Hierarchy

Assess whether you need a dominant hero section or an egalitarian layout. Marquee-Hero (03-marquee-hero.md) emphasizes a visual hierarchy with large hero sections, whereas Stat-Led (04-stat-led.md) foregrounds data-driven blocks.

Interaction Density

Consider the level of micro-interactions required. Conversational-FAQ (06-conversational-faq.md) embeds interactive Q&A blocks with collapsible sections, while Quote-Led (09-quote-led.md) provides a more static, quote-centric presentation.

Brand Narrative

Match your storytelling approach to the layout. Manifesto (07-manifesto.md) supports bold typographic statements for mission statements, while Photographic (08-photographic.md) prioritizes full-bleed imagery over text.

Responsive Constraints

Evaluate mobile behavior requirements. Grid-heavy structures like Portfolio-Grid (18-portfolio-grid.md) include responsive breakpoints for multi-column layouts, while text-centric options like Index-First (13-index-first.md) tolerate narrow screens gracefully.

Matching Your Goal to the Right Macrostructure

Map your primary page goal to the appropriate macrostructure family:

1. Showcase / Portfolio → Use 18-portfolio-grid.md or 01-bento-grid.md for visual work collections and mosaic-style presentations.
2. Long-Form Reading → Select 02-long-document.md or 12-letter.md for articles and formal communications.
3. Data-Driven Presentation → Implement 04-stat-led.md or 05-workbench.md for statistics and interactive tool displays.
4. Hero-Centric Landing → Choose 03-marquee-hero.md or 09-quote-led.md for dominant hero sections.
5. Interactive FAQ / Conversational UI → Deploy 06-conversational-faq.md for collapsible question blocks.

Implementing Your Chosen Macrostructure

Once you decide which Hallmark macrostructure to pick, import it using the renderMacro function from @hallmark/core. The library parses the Markdown file and injects the appropriate HTML, CSS, and motion assets.

// Import the Hallmark core library
import { renderMacro } from '@hallmark/core';

// Select your macrostructure file
const macro = '01-bento-grid.md';

// Render into a target DOM element
renderMacro({
  macroPath: `skills/hallmark/references/macrostructures/${macro}`,
  target: document.getElementById('hallmark-root')
});

Provide a target container in your HTML:

<div id="hallmark-root"></div>

Switch macrostructures dynamically by calling renderMacro with a different filename:

function switchMacro(name) {
  renderMacro({
    macroPath: `skills/hallmark/references/macrostructures/${name}`,
    target: document.getElementById('hallmark-root')
  });
}

// Switch to Portfolio Grid
switchMacro('18-portfolio-grid.md');

These implementations assume a bundler (Vite or Webpack) configured to load Markdown files as raw strings.

Summary

• Hallmark macrostructures are opinionated layout patterns stored in skills/hallmark/references/macrostructures/ as Markdown files.
• Select based on content type, information hierarchy, interaction density, brand narrative, and responsive constraints.
• Use renderMacro from @hallmark/core to load structures like 01-bento-grid.md or 02-long-document.md.
• Grid-heavy options (Portfolio-Grid, Bento-Grid) require responsive planning, while text-centric layouts (Long-Document, Letter) adapt naturally to mobile.

Frequently Asked Questions

What exactly is a Hallmark macrostructure?

A Hallmark macrostructure is a predefined page layout pattern stored as a Markdown file in the Nutlope/hallmark repository. Each macrostructure—such as 03-marquee-hero.md or 07-manifesto.md—provides a complete architectural blueprint including HTML structure, CSS styling, and motion assets, allowing you to implement complex designs by importing a single file.

How do I switch between macrostructures in a Hallmark project?

Call the renderMacro function from @hallmark/core with a different macroPath parameter pointing to the desired file in skills/hallmark/references/macrostructures/. You can wrap this in a switcher function to change layouts dynamically without reloading the page, as shown in the code examples above.

Which Hallmark macrostructure works best for mobile-first designs?

Text-centric macrostructures like Long-Document (02-long-document.md) and Letter (12-letter.md) tolerate narrow screens naturally. If you require grid layouts, Portfolio-Grid (18-portfolio-grid.md) and Bento-Grid (01-bento-grid.md) include built-in responsive breakpoints that collapse gracefully to single columns on mobile devices.

Can I customize a macrostructure after selecting it?

Yes, while macrostructures provide opinionated defaults, you can customize them by modifying the source Markdown files in skills/hallmark/references/macrostructures/ or by overriding the injected CSS and motion assets after rendering. The renderMacro function injects standard HTML that accepts standard CSS styling.

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