How Hallmark's Macrostructure Diversification Prevents Template-Like Output

Hallmark eliminates generic, copy-paste AI output by building each page around a distinct macrostructure from a curated catalog of 21 named page shapes, enforcing strict diversification rules through design stamps, project logs, and automated slop-test gates.

Hallmark's macrostructure diversification is the architectural backbone that stops AI-generated web pages from feeling templated. Instead of toggling independent layout axes or following a rigid hero-features-CTA pipeline, Hallmark selects a complete "page skeleton" that encodes heading placement, component layout, and navigation archetypes. This approach ensures every output has fundamentally different structural DNA from the previous one.

The 21-Shape Macrostructure Catalog

At the heart of Hallmark's diversification strategy lies a curated catalog of 21 complete page-shape definitions. These named macrostructures—including Bento Grid, Long Document, Marquee Hero, and others—provide high-level page skeletons rather than composable layout options.

According to the Hallmark source code in skills/hallmark/references/macrostructures.md, picking a macrostructure is categorically more varied than toggling independent axes. Each macrostructure implicitly selects compatible navigation and footer archetypes, guaranteeing that surrounding chrome aligns with the chosen skeleton. Changing the macrostructure automatically swaps in matching navigation and footer sets, further differentiating the page's visual identity.

Design Stamps: The Single Source of Truth

Hallmark records every macrostructure selection through design stamps—structured comments inserted at the top of each generated CSS file:

// utils/writeStamp.js
export function writeMacrostructureStamp(cssPath, macroName, extra = {}) {
  const stamp = `/* Hallmark · macrostructure: ${macroName} · ${Object.entries(extra)
    .map(([k, v]) => `${k}: ${v}`)
    .join(' · ')} */\n`;
  const css = fs.readFileSync(cssPath, 'utf8');
  fs.writeFileSync(cssPath, stamp + css);
}

The stamp format follows a consistent pattern: /* Hallmark · macrostructure: <name> · ... */. This becomes the single source of truth that subsequent runs read to determine what has already been shipped.

The .hallmark/log.json Feedback Loop

Hallmark maintains project-wide history through .hallmark/log.json, a JSON log storing historic stamps across all builds. When a new generation starts, the system scans this log to enforce the "different-from-last" rule.

The extraction logic in utils/readMacrostructure.js parses the latest entry:

// utils/readMacrostructure.js
import fs from 'fs';
import path from 'path';

export function getLastMacrostructure(projectRoot) {
  const logPath = path.join(projectRoot, '.hallmark', 'log.json');
  if (!fs.existsSync(logPath)) return null;

  const log = JSON.parse(fs.readFileSync(logPath, 'utf8'));
  const latest = log[log.length - 1];
  const stamp = latest?.stamp ?? '';
  const match = stamp.match(/macrostructure:\s*([^·]+)·/);
  return match ? match[1].trim() : null;
}

This function returns the previously used macrostructure name, which feeds directly into selection filtering.

Macrostructure Selection with Exclusion Logic

The chooseMacrostructure function in utils/pickMacrostructure.js guarantees diversification by filtering out the previous selection before scoring candidates:

// utils/pickMacrostructure.js
import macroCatalog from '../skills/hallmark/references/macrostructures.json';
import { getLastMacrostructure } from './readMacrostructure.js';

export function chooseMacrostructure(projectRoot, brief) {
  const last = getLastMacrostructure(projectRoot);
  // Critical diversification step: remove previous macrostructure
  const candidates = macroCatalog.filter(m => m.name !== last);

  const scored = candidates.map(m => ({
    ...m,
    score: brief.includes(m.keywords) ? 1 : 0,
  }));
  scored.sort((a, b) => b.score - a.score);
  return scored[0];
}

By removing last from the candidate pool, Hallmark structurally prevents immediate repetition regardless of brief similarity.

Slop-Test Gate 8: The Enforcement Mechanism

Even with filtering logic, Hallmark implements slop-test gate 8 as a final safeguard. Located in skills/hallmark/references/slop-test.md, this gate asks: "Does the page reuse a structure it shouldn't?"

The simplified validation implementation aborts generation if diversification fails:

// utils/slopTest.js
export function validateDiversification(projectRoot, newMacro) {
  const last = getLastMacrostructure(projectRoot);
  if (last && last === newMacro) {
    throw new Error(
      `Slop‑test failed: macrostructure "${newMacro}" was used in the previous build.`
    );
  }
}

This hard stop guarantees that two consecutive outputs never share macrostructures, preventing template drift even when selection logic malfunctions.

The Diversification Feedback Loop

These mechanisms form a continuous four-step feedback loop:

1. Read the brief — infer the most suitable macrostructure based on content requirements
2. Check existing stamps and log — exclude any macrostructure already used in the project
3. Select a new macrostructure — choose from filtered candidates and embed a fresh stamp
4. Run slop-test gates — abort if the diversification rule is violated

Because the macrostructure serves as the primary driver of page shape, Hallmark never degrades into generic pipeline output. Each page emerges purpose-built rather than templated.

Inverted Rules for designed-as-app Pages

Hallmark's diversification logic adapts for multi-page applications. According to skills/hallmark/references/verbs/redesign.md, when a design.md file exists, the system inverts its approach: the macrostructure becomes the main variable while the theme stays constant.

This enforces structural variety across app pages while preserving visual coherence. The result prevents app interfaces from collapsing into single repeated patterns without sacrificing brand consistency.

Summary

• Macrostructure catalog — 21 complete page shapes provide fundamentally different structural DNA versus axis-based composition
• Design stamps — embedded CSS comments create auditable records of every structural decision
• Project logging — .hallmark/log.json maintains history across all builds for cross-page diversification
• Selection filtering — automatic exclusion of previously used macrostructures at the candidate stage
• Slop-test enforcement — hard gate 8 aborts generation if diversification rules are violated
• Adaptive inversion — designed-as-app mode preserves structural variety while locking visual themes

Frequently Asked Questions

What exactly is a macrostructure in Hallmark?

A macrostructure is a complete, named page-shape definition that encodes heading placement, component layout, navigation archetype, and footer patterns in a single selection. Hallmark's catalog contains 21 such shapes—examples include Bento Grid, Long Document, and Marquee Hero—each providing a fundamentally different skeleton rather than composable layout options.

How does Hallmark guarantee consecutive pages use different macrostructures?

Hallmark combines three enforcement layers: selection-time filtering that removes the previous macrostructure from candidate pools, project-wide logging through .hallmark/log.json that persists choices across builds, and slop-test gate 8 which throws an error and aborts generation if the same macrostructure is detected. This redundancy ensures diversification even if individual components fail.

Why use macrostructures instead of independent layout axes?

Independent axes—toggling hero style, feature grid density, footer variant separately—produce combinatorial variety but lack structural coherence. Macrostructures, as implemented in skills/hallmark/references/structure.md, guarantee that navigation, content hierarchy, and footer align as unified systems. This approach eliminates the subtle "same-ness" that persists even in combinatorially varied axis-based generators.

What happens when building multi-page applications with Hallmark?

For designed-as-app projects containing a design.md file, Hallmark inverts its diversification rule: the theme remains constant across pages while macrostructures vary. This structural variety prevents app pages from feeling repetitive without sacrificing visual consistency, as documented in skills/hallmark/references/verbs/redesign.md.

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