Macrostructure Stamp Format in Hallmark: A Complete Technical Guide

The macrostructure stamp format in Hallmark is a standardized CSS comment placed at the top of every generated file that encodes the chosen macrostructure, tone, and anchor hue for pages—or the component type, genre, theme, and interaction states for components—creating a machine-readable audit trail for diversification enforcement.

Hallmark (Nutlope/hallmark) implements a durable logging system to track every structural decision it makes during code generation. This macrostructure stamp format serves as the backbone of that system, embedding critical metadata directly into the generated CSS to ensure subsequent runs can enforce diversification rules and avoid repeating previous architectural choices.

Page-Level Macrostructure Stamp Format

Hallmark records the structural choice for every generated page in a specially-formatted comment that appears as the first non-empty line of the CSS file or inline <style> block.

The syntax follows this exact pattern:

/* Hallmark · macrostructure: <name> · tone: <tone> · anchor hue: <hue> */

The stamp contains three distinct metadata fields:

• <name> – The selected macrostructure from the 21-entry catalogue (e.g., Bento Grid, Marquee Hero, Long Document).
• <tone> – The tonal direction applied to the design, such as editorial, modern-minimal, atmospheric, or playful.
• <anchor hue> – The color hue anchoring the theme, specified as warm, cool, or neutral.

According to the skills/hallmark/SKILL.md source file at line 461, Hallmark reads this comment on subsequent runs to ensure the next macrostructure differs from the previous one, satisfying the core diversification rule.

Component-Level Stamp Format

Components require a richer stamp format because they must enumerate the eight required interaction states and document accessibility compliance.

The component stamp uses a multi-line comment structure:

/* Hallmark · component: <type> · genre: <genre> · theme: <theme>
 * states: default · hover · focus · active · disabled · loading · error · success
 * contrast: pass (46–50)
 */

This format includes five critical elements:

• <type> – The component type identifier (e.g., button, card).
• <genre> – The genre classification, using the same set as pages.
• <theme> – The theme name or custom theme identifier.
• states: – A checklist of the eight required interaction states: default, hover, focus, active, disabled, loading, error, and success.
• contrast: – The contrast gate result from the slop-test, indicating accessibility compliance (e.g., pass (46–50)).

As documented in skills/hallmark/SKILL.md between lines 31 and 34, this component-level stamp signals to future Hallmark runs that the artifact is component-scoped and should not affect page-level diversification decisions.

Code Examples

Page Generated with the Bento Grid Macrostructure

When Hallmark generates a page using the Bento Grid macrostructure, it emits the following stamp at the top of the CSS file:

/* Hallmark · macrostructure: Bento Grid · tone: modern-minimal · anchor hue: cool */
:root {
  --color-paper: oklch(95% 0 0);
  --color-accent: oklch(55% 0.12 210);
  /* … tokens … */
}

/* page layout … */

This stamp tells the next Hallmark run to avoid reusing Bento Grid for this project while maintaining the modern-minimal tone with a cool accent hue.

Component Button with Full State Coverage

For a button component implementing all eight interaction states, Hallmark generates:

/* Hallmark · component: button · genre: editorial · theme: Specimen
 * states: default · hover · focus · active · disabled · loading · error · success
 * contrast: pass (46–50)
 */
.button {
  background: var(--color-paper-1);
  color: var(--color-accent);
}
.button:hover,
.button.is-hover { background: var(--color-paper-2); }
/* … other state selectors … */

The stamp confirms the component belongs to the editorial genre, uses the Specimen theme, and implements all required visual variants including hover, focus, and disabled states.

Key Implementation Files

The macrostructure stamp system is defined and enforced across these specific source files:

• skills/hallmark/SKILL.md – Defines the exact stamp syntax for both pages and components, and explains the diversification logic that reads these comments (lines 31-34 and 461-466).
• site/_tests/01-tide-podcast/brief.md – Contains concrete examples of macrostructure stamps in production test cases (see "Step 6 · Macrostructure stamp" at line 51).
• skills/hallmark/references/macrostructures.md – Indexes all 21 available macrostructure names that Hallmark can write into the stamp (lines 27-30).

Summary

• The macrostructure stamp format is a standardized CSS comment that records architectural decisions in machine-readable form.
• Page stamps appear as the first line of CSS files and contain macrostructure name, tone, and anchor hue.
• Component stamps include additional metadata for the eight interaction states and contrast test results.
• Hallmark uses these stamps to enforce diversification rules, preventing the same macrostructure from being reused in subsequent runs.
• All stamp definitions are centralized in skills/hallmark/SKILL.md.

Frequently Asked Questions

What exactly is a macrostructure stamp in Hallmark?

A macrostructure stamp is a specially-formatted CSS comment that Hallmark places at the top of every generated CSS file or <style> block. It acts as a durable, machine-readable log encoding the structural choices made during generation, including the macrostructure name, tonal direction, and color anchor for pages, or the component type and state coverage for UI elements.

Why does Hallmark place the stamp as the first non-empty line?

Hallmark requires the stamp to be the first non-empty line to ensure deterministic parsing during subsequent runs. This positioning allows the system to quickly query the previous architectural state without scanning the entire file, enabling efficient enforcement of diversification rules that prevent macrostructure repetition.

How does the component stamp differ from the page stamp?

While page stamps use a single-line format tracking macrostructure, tone, and anchor hue, component stamps use a multi-line format that additionally enumerates the eight required interaction states (default, hover, focus, active, disabled, loading, error, success) and documents the contrast gate results from accessibility testing. This distinction prevents component-level decisions from interfering with page-level diversification.

Where can I find the list of valid macrostructure names?

The complete catalogue of 21 valid macrostructure names is defined in skills/hallmark/references/macrostructures.md (lines 27-30). This reference file serves as the authoritative index that Hallmark queries when selecting a macrostructure name to write into the stamp.

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