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

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 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 at line 286, 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.

// 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 at line 65:

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.

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 at line 73:

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

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 at line 266:

// 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
• references/macrostructures/05-workbench.md
• 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 at line 15, 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)	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)	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)	Rules for avoiding repetition and fallback logic
[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 (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 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 line 266.

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