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

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 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【/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:

/* 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【/cache/repos/github.com/Nutlope/hallmark/main/site/examples/wayfare/tokens.css#L1】:

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

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

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/:

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	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 (and 20 others)	Individual design definitions per macrostructure
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	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	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, 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.

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