What Are the Available Hallmark Macrostructures? 21 Page Layout Patterns Explained

Hallmark provides 21 named macrostructures—complete page-shape specifications including Bento Grid, Marquee Hero, Split Studio, and Type Specimen—that define layout, navigation, footer placement, and interaction patterns in the Nutlope/hallmark system.

The Hallmark design system treats pages as complete compositional units rather than collections of independent components. Instead of manually configuring layout axes, designers choose from a catalog of Hallmark macrostructures stored in skills/hallmark/references/macrostructures.md, each defining a distinct page fingerprint that determines hero behavior, content flow, and structural hierarchy.

The 21 Available Hallmark Macrostructures

Each macrostructure lives in its own Markdown definition file under skills/hallmark/references/macrostructures/ and is referenced via a stamp comment in generated CSS. The following 21 options constitute the complete Hallmark macrostructure index:

1. Bento Grid — Modular blocks of varying sizes laid out as an irregular grid; each block can be a feature, quote, image, or stat. Defined in 01-bento-grid.md.

2. Long Document — Reads like a memo, letter, or journal entry – continuous prose with inline section heads, no marketing hero. Defined in 02-long-document.md.

3. Marquee Hero — The hero is the page above the fold: a single bold statement or visual fills the viewport; the rest of the page follows. Defined in 03-marquee-hero.md.

4. Stat-Led — Hero is a giant number (metric, count, percentage); everything after supports or qualifies it. Defined in 04-stat-led.md.

5. Workbench — Product screenshots in frames are the primary content; the page is a guided tour of the app in use. Defined in 05-workbench.md.

6. Conversational FAQ — Bold questions paired with brief answers; often rendered as collapsible accordions. Defined in 06-conversational-faq.md.

7. Manifesto — Polemical, large-type declaration; the page tells the reader what to believe before it sells. Defined in 07-manifesto.md.

8. Photographic — A single huge image dominates each fold; text is tiny annotation, the design says look before read. Defined in 08-photographic.md.

9. Quote-Led — Hero is a pull-quote with attribution; the headline is borrowed credibility rather than brand voice. Defined in 09-quote-led.md.

10. Specimen — Numbered left-margin labels, huge serif display, asymmetric column spans, typographic-only CTA; editorial/foundry energy. Defined in 10-specimen.md.

11. Catalogue — Uniform grid of variations of the same thing (typefaces, colour palettes, product SKUs); a visual index. Defined in 11-catalogue.md.

12. Letter — First-person, intimate note; opens with a greeting ("Dear friend,"); no buttons in the fold. Defined in 12-letter.md.

13. Index-First — Pure navigation: the page is a list of links, no hero image or narrative flow. Defined in 13-index-first.md.

14. Narrative Workflow — Numbered stages tell a step-by-step story of how a user works with the product over time. Defined in 14-narrative-workflow.md.

15. Split Studio — Diptych layout: each major content block divides the screen (text ↔ proof) and alternates direction down the page. Defined in 15-split-studio.md.

16. Feature Stack — Sticky left pane (label / description) + scroll-synced right pane (screenshots cycling through related details). Defined in 16-feature-stack.md.

17. Type Specimen — The typeface is the design; a foundry-style showcase where typography itself is the product. Defined in 17-type-specimen.md.

18. Portfolio Grid — Filterable cards of projects; typical for studios or designer homepages where the work is the product. Defined in 18-portfolio-grid.md.

19. Map / Diagram — A large spatial diagram (flowchart, floor plan, network graph, system map) organises the page instead of linear text. Defined in 19-map-diagram.md.

20. Ecosystem Index — Multiple discovery surfaces (featured, latest, by category, by people) for platforms where browsing is the primary value. Defined in 20-ecosystem-index.md.

21. Component Playground — Interactive code-and-preview blocks are the page's primary content; each block shows a component with copy-paste instructions. Defined in 21-component-playground.md.

How to Reference Hallmark Macrostructures in Code

Hallmark macrostructures are declared in CSS via stamp comments and consumed by build scripts. The index file at skills/hallmark/references/macrostructures.md serves as the single source of truth for available options.

Adding a Macrostructure Stamp

When generating CSS, include the macrostructure name in the Hallmark stamp comment:

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

This stamp appears at the top of the generated stylesheet and informs future Hallmark runs about the page's structural identity.

Selecting a Macrostructure Programmatically

To build a page using a specific macrostructure, reference it by name in your skill script:

const macro = "Split Studio"; // chosen from the index
await hallmark.run({
  macrostructure: macro,
  genre: "atmospheric",
  theme: "cobalt"
});

The run call reads the chosen macrostructure's definition file (references/macrostructures/15-split-studio.md) and constructs the page according to that specification's layout rules, required components, and navigation defaults.

Auditing Pages for Macrostructure Compliance

To verify that a CSS file declares its macrostructure correctly:

// 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 that the stamp matches the actual layout implementation (e.g., verifying diptych layout for Split Studio).

Key Files in the Hallmark Macrostructure System

The following files define and maintain the macrostructure catalog in the Nutlope/hallmark repository:

• skills/hallmark/references/macrostructures.md — Master index of the 21 macrostructures containing names, short descriptions, and links to full definitions.

• skills/hallmark/references/macrostructures/XX-*.md (21 files) — Full specification for each macrostructure, detailing layout rules, required components, and default nav/footer configurations.

• skills/hallmark/SKILL.md — High-level design flow documentation; mandates reading the macrostructure index before any build operation.

• skills/hallmark/references/structure.md — Describes the primitive axes that macrostructures encapsulate; useful for understanding how to customize or extend existing patterns.

• site/_tests/* — Test cases demonstrating macrostructure selections in real-world briefs and validating output against specifications.

Summary

• Hallmark provides 21 distinct macrostructures that serve as complete page-shape specifications, eliminating the need to configure individual layout axes.
• Each macrostructure is defined in its own file under skills/hallmark/references/macrostructures/ and indexed in macrostructures.md.
• Pages declare their macrostructure via CSS stamp comments formatted as /* Hallmark · macrostructure: [Name] · ... */.
• Build scripts consume the macrostructure name to load the appropriate definition file and construct the page layout accordingly.
• The system supports auditing to ensure that stamped macrostructures match actual page implementation.

Frequently Asked Questions

What is the difference between a macrostructure and a template?

A macrostructure is a high-level page fingerprint that dictates the relationship between content zones (hero, body, navigation, footer), while a template typically refers to a specific implementation file. In Hallmark, macrostructures define how the page behaves compositionally—whether it uses a diptych layout (Split Studio) or a giant metric (Stat-Led)—whereas templates are the rendered output. The macrostructure system lives in skills/hallmark/references/macrostructures/ and provides the rules that generate the final template.

How do I add a custom macrostructure to Hallmark?

To extend the system, create a new Markdown file in skills/hallmark/references/macrostructures/ following the naming convention XX-custom-name.md, then add the entry to skills/hallmark/references/macrostructures.md. You must define the layout rules, required components, and default navigation/footer settings. However, the current system is designed around the canonical 21 macrostructures; custom additions should reference skills/hallmark/references/structure.md to ensure they properly encapsulate the primitive axes used by the build pipeline.

Can I use multiple macrostructures on one page?

No, the Hallmark system assigns exactly one macrostructure per page to maintain compositional coherence. The CSS stamp comment expects a single macrostructure name (e.g., macrostructure: Bento Grid), and the hallmark.run() method accepts only one macrostructure parameter. If you need hybrid behaviors, you should select the macrostructure that best matches the dominant page pattern and adjust via genre and theme parameters rather than mixing macrostructures.

Where does Hallmark store the macrostructure definitions?

The definitions are stored in the skills/hallmark/references/macrostructures/ directory as individual Markdown files (e.g., 01-bento-grid.md, 15-split-studio.md). The master index at skills/hallmark/references/macrostructures.md links to all 21 definition files. When you invoke a macrostructure in code, Hallmark reads the corresponding file from this directory to determine the specific layout rules, heading placement, and interaction patterns required for that page type.

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