Macrostructure vs Theme in Hallmark: How Page Shape Differs from Visual Style

Macrostructures control the layout skeleton of a Hallmark page, while themes control its visual surface; structural variety matters more because it creates perceptual uniqueness and prevents repetitive, low-quality output.

In the Hallmark system, two distinct layers govern how a page looks and feels. Understanding their separation is essential for anyone building with this open-source design framework. According to the Hallmark source code, macrostructures and themes serve fundamentally different purposes—confusing them leads to stale designs and missed opportunities for true visual differentiation.

What Are Macrostructures in Hallmark?

Macrostructures define the page shape—the structural vocabulary that determines how content is organized and presented.

They answer questions like:

• What is the hero type?
• How are sections arranged?
• Where does the main content live?
• Which structural primitives apply (grid, document, manifesto, etc.)?

Hallmark maintains a catalogue of 21 named macrostructures in [skills/hallmark/references/macrostructures.md](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/macrostructures/macrostructures.md). Examples include:

• Bento Grid – Modular, card-based layouts
• Stat-Led – Data-forward hero with prominent metrics
• Photographic – Image-dominant composition
• Quote-Led – Editorial, pull-quote driven
• Manifesto – Dense, statement-heavy pages
• Index-First – Navigation and hierarchy emphasized

The system loads only one macrostructure per page. In [SKILL.md](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md), the workflow explicitly isolates this step:

// Step 2 – Macrostructure pick (excerpt from SKILL.md)
if (brief.isVague) {
  // Offer three categorically different macrostructures
  offerMacrostructures(['01-bento-grid', '02-long-document', '07-manifesto']);
}
const macro = userChoice;               // e.g. "05-workbench"
loadMacroFile(`references/macrostructures/${macro}.md`);

This selective loading ensures the macrostructure acts as the foundational decision that shapes everything that follows.

What Are Themes in Hallmark?

Themes control the visual language—the surface-level aesthetic properties applied atop any macrostructure.

Each theme lives as a standalone markdown file in skills/hallmark/references/themes/. For example:

• [hum.md](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/themes/hum.md) – Warm, organic palette with rounded forms
• [lumen.md](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/themes/lumen.md) – Bright, clinical, high-contrast system

Themes define:

• Colour palette
• Paper band treatments
• Typography stacks
• Radius and shadow choices
• Motion signatures

Implementation happens through CSS tokens in site/css/tokens.css:

/* Theme applied via data attribute */
[data-theme="hum"] {
  --color-bg: #faf6f0;
  --color-text: #2a2520;
  --radius-base: 12px;
  /* ... additional tokens */
}

Theme loading occurs in Step 3 of the SKILL pipeline:

// Step 3 – Theme load (excerpt from SKILL.md)
const theme = 'hum';
document.documentElement.dataset.theme = theme;

Unlike macrostructures, themes are designed for consistency across pages—swapping themes for variety is explicitly discouraged.

Why Structural Variety Matters More Than Theme Variety

Hallmark's architecture embeds a strict prioritization: macrostructure drives variety more than theme. This principle appears directly in [structure.md](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/structure.md): "themes describe visual surface, macrostructures describe page shape; the latter drives variety more". Four mechanisms enforce this hierarchy.

1. Perceptual Impact of Page Shape Changes

A new theme redecorates the same room; a new macrostructure redesigns the floor plan. Users perceive structural changes—hero repositioning, section reordering, grid density shifts—more immediately than colour or typeface swaps. Hallmark's diversification rule capitalizes on this: consecutive builds must not reuse the same macrostructure.

The system embeds macrostructure identity into generated CSS for enforcement:

/* Hallmark · macrostructure: 05-workbench · theme: hum */

This comment stamp, described in [structure.md](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/structure.md), enables automated checks that "two consecutive outputs should never be from the same family".

2. Anti-Slop Protection

"Slop"—generic, template-like AI output—triggers when systems fall back to safe defaults. Hallmark treats repeated macrostructures as a slop indicator. By forcing structural rotation, the system prevents models from churning out visually identical pages with only token changes. The macrostructure requirement acts as a quality gate.

3. Domain-Appropriate Selection

When briefs lack specificity, Hallmark intentionally surfaces categorically different macrostructures:

• One grid-led option
• One document-led option
• One poster-led option

This approach, documented in [structure.md](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/structure.md), ensures the final design aligns with purpose while maintaining freshness. A product marketing site might receive Bento Grid, Workbench, and Photographic as alternatives—each serving the same content through radically different organizational logic.

4. Controlled Theme Consistency

Theme drift—arbitrary theme switching—breaks brand cohesion. Hallmark explicitly warns against this in [verbs/redesign.md](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/verbs/redesign.md): "the variety lives in macrostructure / archetype choice, not theme".

The recommended pattern:

• Theme: Locked per project or page family
• Macrostructure: Varied per page to create narrative rhythm

This separation yields coherent systems with diverse expressions—not fragmented visual identities.

Summary

• Macrostructures = page skeleton (21 options, one per page, drives structural variety)
• Themes = visual surface (applied via CSS tokens, kept consistent across pages)
• Structural variety matters more because it creates perceptual uniqueness, prevents slop, enables domain-fit selection, and preserves brand coherence
• The separation is enforced through: diversification rules, CSS comment stamps, vague-brief triangulation, and anti-theme-drift guidelines

Frequently Asked Questions

Can I use multiple macrostructures on one page?

No. The Hallmark SKILL pipeline explicitly loads only one macrostructure file per page build. The loadMacroFile() call in Step 2 accepts a single path, and the system architecture treats macrostructures as mutually exclusive page-defining choices. Attempting to layer macrostructures would create conflicting layout primitives.

How do I add a new macrostructure to Hallmark?

Create a new markdown file in skills/hallmark/references/macrostructures/ following the 21 existing patterns (e.g., 22-[name].md). Define the hero type, section arrangement, and structural primitives. Register it in [macrostructures.md](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/macrostructures/macrostructures.md) and ensure it responds to the diversification system's family classification for anti-repetition enforcement.

What happens if I violate the diversification rule?

The build system reads CSS comment stamps (e.g., /* Hallmark · macrostructure: 05-workbench... */) to track recent outputs. Repeated macrostructures trigger slop-test gates, potentially blocking generation or flagging output for review. The rule operates as a quality safeguard, not a hard technical limit—manual override is possible but discouraged.

Why can't I just swap themes for variety?

Swapping themes changes colours and typefaces while preserving identical page architecture. Users perceive this as "the same page with a different skin"—the definition of template fatigue. Hallmark's design philosophy embeds variety at the structural level because page shape creates deeper differentiation than surface styling. Theme consistency, conversely, builds recognizable brand systems across structurally varied pages.

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