# How Hallmark Selects Macrostructures for Different Briefs: A Deep Dive into the Domain-Driven Pipeline

> Discover how Hallmark selects macrostructures using a domain-driven pipeline that maps keywords to categories. Learn about their efficient, history-aware process.

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

---

**Hallmark selects macrostructures through a deterministic, domain-driven pipeline that maps brief keywords to categorical trios while respecting project history and minimizing runtime overhead.**

Hallmark, an open-source page-shaping engine maintained in the [Nutlope/hallmark](https://github.com/Nutlope/hallmark) repository, transforms project briefs into concrete layout decisions using a structured selection algorithm. This article explains exactly how the system chooses between **21 distinct macrostructures**—from **Bento Grid** to **Specimen**—based on domain signals, diversification rules, and existing project stamps.

---

## Step 1: Extract Domain Keywords from the Brief

The selection process begins with brief analysis. Hallmark scans the input for **domain-defining keywords** that categorize the project type:

- `audio` / `podcast`
- `commerce` / `saas` / `fintech`
- `docs` / `agency` / `restaurant`
- `fashion` / `personal` / `design`

These keywords trigger a lookup in the internal domain-to-macrostructure mapping. In [`skills/hallmark/SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md) at [line 286](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md#L286), the skill documentation specifies this extraction as the first gate in the decision pipeline.

---

## Step 2: Generate a Categorically Diverse Trio

Once a domain is identified, Hallmark consults a **hardcoded lookup table** that maps each domain to **three macrostructures from different categorical families**:

| Domain | Sample Trio | Families Represented |
|--------|-------------|----------------------|
| `saas` | Bento Grid, Stat-Led, Workbench | Grid-led, Data-led, Document-led |
| `design` | Manifesto, Photographic, Portfolio Grid | Editorial, Hero, Grid |

This trio approach ensures **categorical diversification**—no two options share the same structural family (grid-led, document-led, poster-led, hero-led, etc.). The system avoids presenting three variations of the same layout type.

```javascript
// Simplified representation of Hallmark's domain mapping
const DOMAIN_TO_TRIO = {
  'saas': ['Bento Grid', 'Stat-Led', 'Workbench'],
  'design': ['Manifesto', 'Photographic', 'Portfolio Grid'],
  'restaurant': ['Photographic', 'Long Document', 'Quote-Led'],
  // ... additional domain mappings
};

```

---

## Step 3: Respect Existing Project Stamps

Hallmark enforces **anti-repetition rules** when a target repository already contains a macrostructure stamp. Per [`skills/hallmark/references/anti-patterns.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/anti-patterns.md) at [line 65](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/anti-patterns.md#L65):

> If the CSS contains `/* Hallmark · macrostructure: <name> */`, the next selection must be **categorically distant** from the stamped family.

This prevents sequential editorial macrostructures or back-to-back hero layouts. The filter removes same-family candidates from the trio before final selection.

```javascript
function pickMacrostructure(brief, existingStamp) {
  const domain = extractDomainKeyword(brief);
  let candidates = DOMAIN_TO_TRIO[domain] || DEFAULT_TRIO;

  // Enforce categorical distance from existing stamp
  if (existingStamp) {
    candidates = candidates.filter(m => !isSameFamily(m, existingStamp));
  }

  return rankAndSelect(candidates, brief);
}

```

---

## Step 4: Handle Vague or Delegated Briefs

When the brief lacks clear domain signals or the user explicitly defers the decision, Hallmark applies **fallback rules** defined in [`anti-patterns.md`](https://github.com/Nutlope/hallmark/blob/main/anti-patterns.md) at [line 73](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/anti-patterns.md#L73):

1. **No domain detected**: Offer three macrostructures from different default groups
2. **User says "you pick"**: Fall back to the **first-ten catalogue** (Bento Grid through Specimen) and select based on implicit tonal cues

```javascript
const FIRST_TEN_MACROSTRUCTURES = [
  'Bento Grid',      // 01
  'Long Document',   // 02
  'Marquee Hero',    // 03
  'Stat-Led',        // 04
  'Workbench',       // 05
  'Conversational FAQ', // 06
  'Manifesto',       // 07
  'Photographic',    // 08
  'Quote-Led',       // 09
  'Specimen'         // 10
];

```

---

## Step 5: Load Only the Selected Macrostructure File

After selection, Hallmark optimizes runtime performance by loading **a single definition file** rather than the full catalogue. Per [`SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/SKILL.md) at [line 266](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md#L266):

```javascript
// Load only the chosen macrostructure
loadMacrostructureFile(
  `references/macrostructures/${chosen.id}-${slug(chosen.name)}.md`
);

```

This file contains the complete specification: grid definitions, typography scale, spacing values, and component placement rules. Examples include:

- [`references/macrostructures/01-bento-grid.md`](https://github.com/Nutlope/hallmark/blob/main/references/macrostructures/01-bento-grid.md)
- [`references/macrostructures/05-workbench.md`](https://github.com/Nutlope/hallmark/blob/main/references/macrostructures/05-workbench.md)
- [`references/macrostructures/10-specimen.md`](https://github.com/Nutlope/hallmark/blob/main/references/macrostructures/10-specimen.md)

---

## Step 6: Apply Optional Hero-Polish Patterns

For hero-type macrostructures (**Marquee Hero**, **Stat-Led**, **Quote-Led**, **Letter**, **Photographic**, **Clipped**), Hallmark may layer **polish patterns (HP1-HP4)** on top of the base shape. According to [`references/macrostructures.md`](https://github.com/Nutlope/hallmark/blob/main/references/macrostructures.md) at [line 15](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/macrostructures.md#L15), this decision depends on:

- Brief tone (playful vs. authoritative)
- Visual goals specified in the project description
- Content density requirements

Polish patterns adjust decorative flourishes without altering the underlying macrostructure geometry.

---

## Key Source Files

| File Path | Purpose |
|-----------|---------|
| [[`skills/hallmark/SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md)](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md) | High-level workflow, domain-to-trio table, selection orchestration |
| [[`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.md) | Index of 21 macrostructures and polish pattern rules |
| [[`skills/hallmark/references/anti-patterns.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/anti-patterns.md)](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/anti-patterns.md) | Rules for avoiding repetition and fallback logic |
| [[`skills/hallmark/references/structure.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/structure.md)](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/structure.md) | Guidance on preferring named macrostructures over manual axis composition |
| [`references/macrostructures/XX-name.md`](https://github.com/Nutlope/hallmark/blob/main/references/macrostructures/XX-name.md) (21 files) | Individual macrostructure specifications |
| `site/_tests/**/brief.md` | Real-world selection examples |

---

## Summary

- **Hallmark selects macrostructures** through a six-step pipeline balancing domain relevance, categorical diversification, and project history
- **Domain keywords** trigger trio generation from different structural families (grid, document, poster, hero)
- **Existing stamps** enforce categorical distance to prevent repetitive layouts
- **Fallback rules** handle vague briefs via the first-ten catalogue or default trios
- **Single-file loading** optimizes performance after selection
- **Hero-polish patterns** (HP1-HP4) add tonal variation without changing base geometry

---

## Frequently Asked Questions

### What happens if a brief matches multiple domain keywords?

Hallmark prioritizes the **most specific match** in its `DOMAIN_TO_TRIO` lookup. If specificity is equal, the system uses the first matched keyword in document order. The domain extraction logic does not implement weighted scoring—it's a direct table lookup with early termination.

### Can users override the macrostructure selection?

Users can **force selection** by specifying a macrostructure name directly in the brief, or **delegate entirely** by including phrases like "you pick." In delegation mode, Hallmark falls back to the first-ten list and selects based on implicit tonal cues rather than domain mapping.

### How does Hallmark avoid choosing the same macrostructure family twice?

The `isSameFamily()` helper compares categorical metadata attached to each macrostructure. If an existingstamp identifies a macrostructure from the "editorial" family, candidates from that family are filtered out before ranking. This rule is documented in [`anti-patterns.md`](https://github.com/Nutlope/hallmark/blob/main/anti-patterns.md) and enforced during the `candidates.filter()` step.

### Why does Hallmark load only one macrostructure file instead of the full catalogue?

Loading a **single definition** minimizes token consumption in LLM-powered workflows and reduces cognitive overhead for the model. The `references/macrostructures/` directory contains 21 files; loading all would introduce irrelevant constraints and increase processing time. This optimization is explicit in [`SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/SKILL.md) line 266.