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

> Explore 21 Hallmark macrostructures including Bento Grid, Marquee Hero, and Split Studio. Discover page layout, navigation, and interaction patterns in the Nutlope hallmark system.

- Repository: [Hassan El Mghari/hallmark](https://github.com/Nutlope/hallmark)
- Tags: api-reference
- Published: 2026-07-16

---

**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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/05-workbench.md).

6. **Conversational FAQ** — Bold questions paired with brief answers; often rendered as collapsible accordions. Defined in [`06-conversational-faq.md`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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:

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

```javascript
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`](https://github.com/Nutlope/hallmark/blob/main/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:

```javascript
// 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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md) — High-level design flow documentation; mandates reading the macrostructure index before any build operation.

- [`skills/hallmark/references/structure.md`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/XX-custom-name.md), then add the entry to [`skills/hallmark/references/macrostructures.md`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/01-bento-grid.md), [`15-split-studio.md`](https://github.com/Nutlope/hallmark/blob/main/15-split-studio.md)). The master index at [`skills/hallmark/references/macrostructures.md`](https://github.com/Nutlope/hallmark/blob/main/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.