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

> Understand the difference between Hallmark macrostructures and themes. Discover why structural variety is key to unique and high-quality page layouts.

- Repository: [Hassan El Mghari/hallmark](https://github.com/Nutlope/hallmark)
- Tags: deep-dive
- Published: 2026-08-13

---

**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.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/SKILL.md)](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md), the workflow explicitly isolates this step:

```js
// 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/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/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`](https://github.com/Nutlope/hallmark/blob/main/site/css/tokens.css):

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

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

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

```

This comment stamp, described in [[`structure.md`](https://github.com/Nutlope/hallmark/blob/main/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/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/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/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.