# How Hallmark Selects a Macrostructure: 5-Step Deterministic Algorithm Explained

> Learn how Hallmark selects a macrostructure using a 5-step deterministic algorithm. Discover the process for page layout selection and implementation.

- Repository: [Hassan El Mghari/hallmark](https://github.com/Nutlope/hallmark)
- Tags: how-to-guide
- Published: 2026-08-07

---

**Hallmark selects a macrostructure through a deterministic five-step process that reads the brief, checks for existing "stamps" to enforce diversification, limits candidates to the first ten shapes for common use cases, matches brief energy to layout descriptors, and declares the pick before emitting any HTML or CSS.**

Hallmark is a design-first code generation tool by Nutlope that never makes random layout decisions. Its macrostructure selection algorithm runs entirely before any markup is produced, ensuring every page follows a repeatable, rules-driven workflow grounded in the [`macrostructures.md`](https://github.com/Nutlope/hallmark/blob/main/macrostructures.md) reference documentation.

## What Is a Macrostructure in Hallmark?

A **macrostructure** is Hallmark's term for a high-level page archetype—think *Bento Grid*, *Stat-Led*, or *Long Document*. These shapes define the fundamental layout, hero treatment, navigation style, and footer pattern for a generated page.

Hallmark maintains **21 total macrostructures** in its catalogue, though the selection algorithm prioritizes the **first ten** for roughly 80% of use cases, as documented in [`skills/hallmark/references/macrostructures.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/macrostructures.md)【/cache/repos/github.com/Nutlope/hallmark/main/skills/hallmark/references/macrostructures.md#L11-L12】.

## The 5-Step Macrostructure Selection Process

The complete algorithm is encoded in the macrostructure reference file【/cache/repos/github.com/Nutlope/hallmark/main/skills/hallmark/references/macrostructures.md#L81-L88】. Each step builds on the previous to guarantee predictable, diverse output.

### Step 1: Parse the Brief for Shape Keywords

Hallmark scans the input brief for language that signals intent:

- **"data-heavy"** or **"metrics"** → *Stat-Led*
- **"personal note"** or **"story"** → *Long Document*
- **"list of links"** → *WorkBench*
- **"editorial"** or **"manifesto"** → *Marquee Hero*

These keyword-to-shape mappings align the brief's energy with the **"Reach for it"** descriptors defined for each macrostructure in the reference catalogue.

### Step 2: Check for an Existing Diversification Stamp

Before selecting anything, Hallmark searches project files for a comment stamp like:

```css
/* Hallmark · macrostructure: <NAME> · genre: editorial · theme: Manifesto-dark */

```

If found, that macrostructure name is **excluded from consideration**. This **diversification rule** prevents consecutive outputs from reusing the same shape【/cache/repos/github.com/Nutlope/hallmark/main/skills/hallmark/references/macrostructures.md#L7-L10】.

### Step 3: Limit Pool to First Ten Candidates

When the brief is vague, Hallmark constrains choices to the first ten macrostructures:

| Index | Macrostructure |
|-------|---------------|
| 01 | Bento Grid |
| 02 | Long Document |
| 03 | Marquee Hero |
| 04 | Stat-Led |
| 05 | WorkBench |
| 06 | Conversational FAQ |
| 07 | Manifesto |
| 08 | Photographic |
| 09 | Quote-Led |
| 10 | Specimen |

This optimization covers the vast majority of real-world use cases without overwhelming the selection logic【/cache/repos/github.com/Nutlope/hallmark/main/skills/hallmark/references/macrostructures.md#L11-L12】.

### Step 4: Match Brief Energy to Shape Descriptors

Hallmark compares the brief's language against each candidate's documented use cases. The shape with the strongest alignment—**that also satisfies the diversification rule**—wins.

### Step 5: Declare and Stamp the Selection

Before any code generation begins, Hallmark outputs a plain-text declaration:

```

Macrostructure: Bento Grid

```

Then it injects the diversification stamp as the **first line of the generated CSS file**, as seen in [`site/examples/wayfare/tokens.css`](https://github.com/Nutlope/hallmark/blob/main/site/examples/wayfare/tokens.css)【/cache/repos/github.com/Nutlope/hallmark/main/site/examples/wayfare/tokens.css#L1】:

```css
/* Hallmark · macrostructure: Marquee Hero · genre: editorial · theme: Manifesto-dark */

```

## How the Diversification Stamp Works in Practice

The stamp serves two critical functions: it marks the chosen macrostructure for human review, and it enables the algorithm to enforce diversity across multiple generation passes.

Example from the Wayfare demo site:

```css
/* Hallmark · macrostructure: Marquee Hero · genre: editorial · theme: Manifesto-dark */
:root {
  --color-bg: #0a0a0a;
  --color-fg: #f5f5f5;
  /* ... */
}

```

Test cases in [`site/_tests/07-foundry-compliance/style.css`](https://github.com/Nutlope/hallmark/blob/main/site/_tests/07-foundry-compliance/style.css) explicitly verify stamp presence, ensuring the rule is never violated in production【/cache/repos/github.com/Nutlope/hallmark/main/site/_tests/07-foundry-compliance/style.css#L1】.

## Implementing Macrostructure Selection in Code

The following JavaScript illustrates the complete workflow, mirroring the five-step process from the reference documentation:

```javascript
const fs = require('fs');

// Step 1: Load brief with shape keywords
const brief = { keywords: ['data', 'metrics', 'dashboard'] };

// Step 2: Extract existing macrostructure from project CSS
function getExistingMacrostructure(filePath) {
  try {
    const css = fs.readFileSync(filePath, 'utf8');
    const match = css.match(/Hallmark · macrostructure: ([^·]+)/);
    return match ? match[1].trim() : null;
  } catch {
    return null;
  }
}

// Step 3-4: Apply diversification and keyword matching
function selectMacrostructure(brief, projectCssPath) {
  const prohibited = getExistingMacrostructure(projectCssPath);
  
  // First ten macrostructures (80% use case coverage)
  const candidates = [
    'Bento Grid', 'Long Document', 'Marquee Hero', 'Stat-Led',
    'WorkBench', 'Conversational FAQ', 'Manifesto', 'Photographic',
    'Quote-Led', 'Specimen'
  ];
  
  // Keyword-to-shape mapping from reference documentation
  const energyMap = {
    'data': 'Stat-Led',
    'metrics': 'Stat-Led',
    'story': 'Long Document',
    'personal': 'Long Document',
    'links': 'WorkBench',
    'editorial': 'Marquee Hero',
    'manifesto': 'Manifesto'
  };
  
  // Find best match that isn't prohibited
  let selection = candidates.find(c => c !== prohibited); // default: first allowed
  
  for (const keyword of brief.keywords) {
    const mapped = energyMap[keyword];
    if (mapped && mapped !== prohibited && candidates.includes(mapped)) {
      selection = mapped;
      break;
    }
  }
  
  return selection;
}

// Step 5: Emit declaration and generate stamp
const chosen = selectMacrostructure(brief, 'site/css/base.css');
console.log(`Macrostructure: ${chosen}`);
console.log(`/* Hallmark · macrostructure: ${chosen} */`);

```

After selection, Hallmark loads the corresponding template from `skills/hallmark/references/macrostructures/`:

```javascript
import bentoGrid from './macrostructures/01-bento-grid.md';
import longDocument from './macrostructures/02-long-document.md';
import statLed from './macrostructures/04-stat-led.md';

const templateMap = {
  'Bento Grid': bentoGrid,
  'Long Document': longDocument,
  'Stat-Led': statLed
  // ... remaining macrostructures
};

function loadMacrostructureTemplate(name) {
  return templateMap[name] || templateMap['Bento Grid'];
}

```

Each template file contains the specific layout definition, hero polish guidelines, and navigation/footer archetypes for that shape【/cache/repos/github.com/Nutlope/hallmark/main/skills/hallmark/references/macrostructures/01-bento-grid.md】.

## Key Source Files for Macrostructure Selection

| File Path | Purpose |
|-----------|---------|
| [`skills/hallmark/references/macrostructures.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/macrostructures.md) | Complete catalogue of 21 shapes, diversification rules, and step-by-step selection algorithm【/cache/repos/github.com/Nutlope/hallmark/main/skills/hallmark/references/macrostructures.md】 |
| [`skills/hallmark/references/macrostructures/01-bento-grid.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/macrostructures/01-bento-grid.md) (and 20 others) | Individual design definitions per macrostructure |
| [`site/examples/wayfare/tokens.css`](https://github.com/Nutlope/hallmark/blob/main/site/examples/wayfare/tokens.css) | Live example of diversification stamp in generated output【/cache/repos/github.com/Nutlope/hallmark/main/site/examples/wayfare/tokens.css#L1】 |
| [`site/_tests/07-foundry-compliance/style.css`](https://github.com/Nutlope/hallmark/blob/main/site/_tests/07-foundry-compliance/style.css) | Test asserting stamp presence and format compliance【/cache/repos/github.com/Nutlope/hallmark/main/site/_tests/07-foundry-compliance/style.css#L1】 |
| [`site/js/main.js`](https://github.com/Nutlope/hallmark/blob/main/site/js/main.js) | UI badge displaying "21 macrostructures" count【/cache/repos/github.com/Nutlope/hallmark/main/site/js/main.js#L145-L151】 |

## Summary

- Hallmark's macrostructure selection is **deterministic, not random**—it follows five documented steps before any code generation.
- The **diversification stamp** enforces variety by excluding previously used shapes from consideration.
- **Brief keyword matching** aligns page intent with catalogued shape descriptors ("Reach for it" guidance).
- The **first ten macrostructures** handle ~80% of use cases, with 11 additional shapes available for edge cases.
- Every selection is **declared in plain text** and **persisted as a CSS comment** for transparency and repeatability.

## Frequently Asked Questions

### How does Hallmark prevent repeating the same macrostructure?

Hallmark embeds a comment stamp in every generated CSS file indicating which macrostructure was used. Before selecting a new shape, it scans project files for this stamp and **excludes any previously used macrostructure** from the candidate pool. This diversification rule is hardcoded in the selection algorithm【/cache/repos/github.com/Nutlope/hallmark/main/skills/hallmark/references/macrostructures.md#L7-L10】.

### What happens if a brief doesn't specify a clear shape?

When brief keywords are ambiguous, Hallmark defaults to the **first ten macrostructures**—a curated set covering approximately 80% of common page types. It then applies lightweight heuristics to choose among these ten while still respecting the diversification rule against any existing stamp【/cache/repos/github.com/Nutlope/hallmark/main/skills/hallmark/references/macrostructures.md#L11-L12】.

### Where are macrostructure templates stored?

Individual macrostructure definitions live as Markdown files in `skills/hallmark/references/macrostructures/`, numbered 01 through 21 (e.g., [`01-bento-grid.md`](https://github.com/Nutlope/hallmark/blob/main/01-bento-grid.md), [`02-long-document.md`](https://github.com/Nutlope/hallmark/blob/main/02-long-document.md)). Each file specifies layout structure, hero treatment, navigation pattern, and footer archetype for that shape【/cache/repos/github.com/Nutlope/hallmark/main/skills/hallmark/references/macrostructures/01-bento-grid.md】.

### Can the macrostructure selection be overridden manually?

The reference documentation describes the algorithm as rules-driven and deterministic, with no API exposed for manual override in the analysed source. The design-first workflow assumes brief authors influence selection through **precise keyword choice** rather than direct shape assignment, keeping the generation process consistent and repeatable.