How Many Named Page Shapes (Macrostructures) Does Hallmark Have? Complete 2024 Guide

Hallmark defines exactly 21 named page-shape macrostructures, documented in the centralized index at references/macrostructures.md.

This guide breaks down where these macrostructures live, how they're numbered, and how to programmatically verify the count from the Nutlope/hallmark repository. Whether you're auditing the design system or building tooling around it, the 21-macrostructure taxonomy is the foundation of Hallmark's page architecture.

The 21 Hallmark Macrostructures Explained

Each macrostructure represents a distinct page-level layout pattern with its own design-system rules. The complete list spans from 01 · Bento Grid through 21 · Component Playground, giving designers and developers a standardized vocabulary for page composition.

Where the Count Is Documented

The authoritative source is [skills/hallmark/references/macrostructures.md](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/macrostructures.md), which contains:

• A heading explicitly stating "The 21 macrostructures – index"
• An enumerated list (lines 29-49) with all 21 entries
• Zero-based sequential numbering from 01 to 21

According to the Hallmark source code, this file serves as the master index that the rest of the design system references for page-shape validation and linting rules.

Example Macrostructure Definition

Individual macrostructures have dedicated documentation files. For instance, 01 · Bento Grid is fully specified in [skills/hallmark/references/macrostructures/01-bento-grid.md](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/macrostructures/01-bento-grid.md), including:

• Layout constraints and grid specifications
• Allowed child components
• Responsive behavior rules
• Accessibility requirements

How to Programmatically Count Hallmark Macrostructures

You can verify the 21-macrostructure total directly from the source files. Here's a Node.js script that reads the index and extracts the exact count:

// Load the macrostructure index and count the entries
import fs from 'fs';
import path from 'path';

// Path to the macrostructures index (relative to project root)
const idxPath = path.resolve(
  __dirname,
  'skills/hallmark/references/macrostructures.md'
);

// Read the file and extract lines that start a macrostructure entry
const lines = fs.readFileSync(idxPath, 'utf8').split('\n');
const macroLines = lines.filter(l => /^\s*-\s*\d{2}\s·/.test(l));

console.log(`Hallmark defines ${macroLines.length} macrostructures.`);
// → Hallmark defines 21 macrostructures.

How it works:

• Reads macrostructures.md as UTF-8
• Filters for list items matching the pattern "- 01 ·" (two-digit number, space, middle dot)
• Returns the array length, which equals 21

Key Files for Macrostructure Reference

File	Purpose
[skills/hallmark/references/macrostructures.md](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/macrostructures.md)	Master index enumerating all 21 macrostructures
[skills/hallmark/references/macrostructures/01-bento-grid.md](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/macrostructures/01-bento-grid.md)	Sample macrostructure definition (Bento Grid)
[skills/hallmark/SKILL.md](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md)	High-level documentation referencing the macrostructure system

Summary

• Hallmark has 21 named page shapes (macrostructures), not 20 or an open-ended list
• The canonical count is hardcoded in references/macrostructures.md with explicit heading confirmation
• Each macrostructure (01-21) has dedicated documentation in references/macrostructures/
• Programmatic verification is straightforward via regex matching on the index file

Frequently Asked Questions

Does Hallmark support custom macrostructures beyond the 21 defined?

No. The 21 macrostructures form a closed taxonomy according to the source files. The index at macrostructures.md is exhaustive, and the linting rules in SKILL.md enforce that pages must use one of these predefined shapes.

What is the first and last macrostructure in Hallmark's system?

01 · Bento Grid is the first macrostructure, and 21 · Component Playground is the last. The sequential numbering implies room for expansion, but no 22nd macrostructure currently exists in the repository.

How are macrostructures validated in Hallmark projects?

The SKILL.md file documents that Hallmark's linting tools cross-reference page layouts against the 21-entry index in macrostructures.md. Any page shape not matching one of the enumerated 21 triggers a validation error.

Is the 21-macrostructure count version-dependent?

As of the latest commit in Nutlope/hallmark, the count has remained stable at 21. The commit history shows macrostructures.md was structured with "The 21 macrostructures – index" as a deliberate architectural decision rather than an emergent property.

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