How Hallmark's Macrostructure System Ensures Design Variety: Inside the 21-Shape Catalog and Diversification Rules

Hallmark guarantees unique page layouts by enforcing a diversification rule that prevents macrostructure reuse within the same family, tracked via CSS stamps and validated against a curated catalog of 21 distinct page shapes.

The Nutlope/hallmark repository implements a sophisticated macrostructure system that eliminates repetitive layouts through a combination of catalog-based selection and automated guards. Unlike traditional static site generators that rely solely on component variation, Hallmark treats entire page architectures—hero placement, navigation patterns, and grid systems—as discrete, selectable units. This approach ensures that successive builds produce genuinely distinct structural fingerprints rather than superficial theme swaps.

The Macrostructure Catalog: 21 Distinct Page Shapes

At the core of Hallmark's variety mechanism lies the macrostructure catalog, a curated registry of 21 named page shapes defined in [skills/hallmark/references/macrostructures.md](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/macrostructures.md). Each entry represents a complete "fingerprint" specifying heading placement, hero type, component layout, navigation and footer archetypes, and optional polish patterns.

Available structures include Bento Grid, Marquee Hero, and Split Studio, among others. Every macrostructure links to a detailed specification file (e.g., macrostructures/01-bento-grid.md) that codifies the exact spatial relationships and component hierarchies. This catalog serves as the single source of truth for the generation pipeline, ensuring that selections are drawn from a finite but diverse pool of architecturally distinct options.

Stamp-Based Diversification Rules

Hallmark enforces variety through a diversification rule that operates at build time. Before generating a page, the system scans the project's .hallmark/log.json and inspects existing CSS files for the /* Hallmark · macrostructure: … */ stamp. If a macrostructure has already been used, the build pipeline must select a different macrostructure from a different family—preventing consecutive "hero-led" or "grid-led" layouts unless explicitly overridden.

This rule is enforced by the slop-test gate described in [skills/hallmark/references/slop-test.md](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/slop-test.md) (line 40), which checks for macrostructure reuse. The stamp-validation logic in [skills/hallmark/references/verbs/audit.md](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/verbs/audit.md) (line 14) verifies that generated CSS files contain valid stamps recording the chosen structure and any enrichment knobs.

Every generated stylesheet begins with a machine-readable comment that acts as the single source of truth for subsequent runs:

/* Hallmark · macrostructure: Bento Grid · H1 hero knobs: size=xl, alignment=center */

This stamp prevents accidental reuse and enables the system to maintain state across builds without external databases.

Family-Level Variety Enforcement

Macrostructures are grouped by type families such as hero-led, editorial, and grid-led categories. According to the selection algorithm documented in [skills/hallmark/references/structure.md](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/structure.md) (line 156-158), the design flow deliberately excludes picking another macrostructure from the same family when the brief does not explicitly request repetition.

This categorical distance requirement ensures that consecutive pages possess distinct structural DNA. The system prioritizes cross-family selection over intra-family variation, guaranteeing that a "Marquee Hero" layout will not be followed by another hero-heavy composition, even if the specific template differs.

Theme vs. Structure Separation

Hallmark maintains strict separation between themes and macrostructures. While themes control surface-level tokens—color palettes, typefaces, and spacing scales—macrostructures determine the underlying page architecture. The diversification rule applies to macrostructures independently of themes, as detailed in [skills/hallmark/references/verbs/redesign.md](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/verbs/redesign.md) (line 215-218).

This separation means that even if a project reuses the same visual theme across multiple builds, the underlying structural variety persists. A user can generate ten pages with identical color schemes and typography, yet each will possess a unique macrostructural foundation, preventing the visual monotony associated with template-based generators.

Implementation: How the Diversification Rule Works in Code

The enforcement mechanisms rely on three core utilities that interact with the catalog and stamp system.

1. Macrostructure Selection Logic

The selection algorithm filters candidates by family to avoid consecutive similar layouts:

// utils/selectMacrostructure.js
import macroList from '../skills/hallmark/references/macrostructures.json';

/**
 * Return a macrostructure that is not the same family as the last one.
 */
export function pickMacrostructure(prevStamp) {
  const prevFamily = prevStamp?.family;
  const candidates = macroList.filter(m => m.family !== prevFamily);
  // Simple heuristic: choose the first candidate that matches the brief keywords
  return candidates.find(m => briefMatches(m.keywords));
}

The macroList is generated from the individual macrostructure files referenced in macrostructures.md, ensuring the utility always operates against the latest catalog definitions.

2. Stamp Generation

During CSS generation, the system writes the macrostructure stamp to enable future diversification checks:

// generators/cssGenerator.js
export function writeStamp(macro, knobs = {}) {
  const knobStr = Object.entries(knobs)
    .map(([k, v]) => `${k}=${v}`)
    .join(', ');
  return `/* Hallmark · macrostructure: ${macro.name} · ${knobStr} */\n`;
}

This comment is inserted at the top of every generated stylesheet, creating the audit trail required by the slop-test gate.

3. Runtime Diversification Guard

Before writing any page, the system validates against the diversification rule:

// checks/diversification.js
import fs from 'fs';
import path from 'path';

export function ensureVariety(projectRoot) {
  const logPath = path.join(projectRoot, '.hallmark', 'log.json');
  const last = JSON.parse(fs.readFileSync(logPath, 'utf8')).pop();
  const stamp = readCurrentStamp(projectRoot);
  if (stamp && stamp.macrostructure === last.macrostructure) {
    throw new Error('Diversification rule violated: reuse of macrostructure.');
  }
}

This guard mirrors the slop-test gate logic and prevents builds that would violate the variety requirements.

Summary

• Hallmark's macrostructure system maintains a catalog of 21 distinct page architectures, each defining complete layout fingerprints from hero placement to footer patterns.
• Diversification rules enforce family-level variety by preventing consecutive selections from the same macrostructure family, validated via the slop-test gate in slop-test.md.
• CSS stamps record generation choices in machine-readable comments, enabling stateful variety checks across builds without external databases.
• Theme independence ensures structural variety persists even when visual tokens remain constant, separating surface styling from page architecture.
• Runtime guards in checks/diversification.js throw errors if the diversification rule is violated, maintaining catalog integrity.

Frequently Asked Questions

What happens if Hallmark runs out of macrostructure families?

The system will allow reuse of a previously used family only after all available families have been exhausted or if the build brief explicitly overrides the diversification rule. According to the selection algorithm in structure.md, the constraint relaxes to prevent build failures, though the 21-shape catalog typically provides sufficient variety for standard project lifecycles.

How does the stamp comment prevent layout repetition?

The stamp comment acts as a deterministic marker that subsequent builds read from .hallmark/log.json and the CSS file headers. When ensureVariety() detects a stamp matching the last used macrostructure, it throws a diversification error before generation begins, forcing the selection logic in pickMacrostructure() to choose from a different family.

Can developers add custom macrostructures to the catalog?

Yes. Developers can create new specification files following the schema defined in macrostructures.md and register them in the master catalog. The macroList imported in utils/selectMacrostructure.js is generated from these definitions, making custom shapes immediately available to the diversification algorithm provided they include valid family classifications.

Does theme selection affect macrostructure variety?

No. As implemented in the redesign logic documented in redesign.md (line 215-218), themes and macrostructures operate on independent axes. A project can reuse the same theme across multiple pages while the diversification rule guarantees each page receives a distinct macrostructure from a different family, ensuring true structural variety regardless of visual consistency.

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