Hallmark Diversification Rule: How It Prevents Identical Structural Fingerprints

Hallmark enforces a two-level diversification rule that guarantees unique structural fingerprints by rotating macrostructures and varying at least one of three theme axes (paper band, display style, accent hue) across consecutive builds.

The diversification rule is Hallmark's core mechanism for ensuring automated design generation never produces perceptually identical pages. Implemented in the Nutlope/hallmark repository, this system reads project memory from .hallmark/log.json and applies constraint-based selection to both layout and visual styling.

How the Two-Level Diversification Rule Works

Hallmark operates the diversification rule at macrostructure and theme levels independently. Each level has distinct enforcement logic documented in skills/hallmark/SKILL.md.

Level 1: Macrostructure Diversification

The macrostructure governs the overall page layout—patterns such as Stat-Led, Marquee Hero, or Bento Grid.

• Hallmark inspects either the CSS stamp /* Hallmark · macrostructure: … */ or the most recent entry in .hallmark/log.json
• The next build must select a different macrostructure than any of the last three recorded entries
• This rule prevents repetitive layout patterns that would make pages structurally indistinguishable

The macrostructure check runs before any theme selection occurs, establishing the foundational layout constraint.

Level 2: Theme-Axis Diversification

The theme defines visual character through three independent axes documented in SKILL.md lines 274-280:

Axis	Options
Paper band	light / mid / dark
Display style	high-contrast-serif, roman-serif, geometric-sans, etc.
Accent hue	warm, cool, neutral, chromatic

The rule: Two consecutive themes must differ on at least one of these three axes. If all three match, the candidate theme is rejected.

Themes supporting drops (variant palettes like night or day for the same theme) treat the drop as an extension of the theme identity—changing the drop alone satisfies the diversification requirement.

The Diversification Algorithm in Practice

Hallmark executes a four-step pipeline on every build:

1. Load project memory — Parse .hallmark/log.json for the last 3-5 entries, extracting macrostructure and theme axis values
2. Filter macrostructures — Exclude any macrostructure appearing in the last three builds
3. Filter themes — From the remaining candidates, reject any theme matching all three axes of the previous build
4. Record selection — Append the chosen configuration to .hallmark/log.json for future diversification checks

[
  {
    "date": "2026-08-13",
    "macrostructure": "Marquee Hero",
    "theme": "Lumen",
    "drop": "night"
  }
]

This log entry from .hallmark/log.json provides the source of truth for subsequent diversification decisions.

Theme Selection Implementation

The axis-comparison logic operates on normalized theme metadata. Here's how the selection works in practice:

def select_theme(catalog: list[Theme], log: list[dict]) -> Theme:
    last = log[-1] if log else None
    
    def differs_by_axis(candidate: Theme) -> bool:
        if not last:
            return True
        c_axes = candidate.axes  # {paper, display, accent}

        l_axes = get_theme_axes(last["theme"])
        return (
            c_axes.paper != l_axes.paper or
            c_axes.display != l_axes.display or
            c_axes.accent != l_axes.accent
        )
    
    valid = [t for t in catalog if differs_by_axis(t)]
    return random.choice(valid) if valid else catalog[0]

The get_theme_axes helper reads axis values from site/css/tokens.css or the theme's internal tokens block, ensuring consistent evaluation across Hallmark's 21 named themes.

The Inverted Rule for Locked Design Systems

When Hallmark detects a design.md file (created by hallmark redesign), it treats the project as an application-level design system. The diversification rule inverts:

Normal Mode	Inverted Mode (with design.md)
Rotate macrostructures	Vary macrostructures within the declared family
Vary theme axes	Lock theme, accent, and type pairing across all pages

This inversion prevents "slop split-personality"—the visual incoherence that occurs when automated diversification varies branding elements within a single application.

The inverted rule is triggered by a specific CSS stamp:

/* Hallmark · genre: app · macrostructure: Bento Grid · design-system: design.md · designed-as-app */

Documented in skills/hallmark/references/verbs/redesign.md, this behavior prioritizes brand consistency over variety for multi-page applications.

Technical Sources and Enforcement Points

File	Role in Diversification
skills/hallmark/SKILL.md	Primary specification of the theme-diversification rule (lines 274-280) and macrostructure rotation logic
skills/hallmark/references/verbs/redesign.md	Defines the inverted rule for design.md-locked projects
skills/hallmark/references/themes/lumen.md	Demonstrates how drops extend theme identity in diversification logging
skills/hallmark/references/themes/carnival.md	Alternative theme reference showing per-drop axis recording
.hallmark/log.json (generated)	Persistent state store queried on every build

Axis values resolve from site/css/tokens.css or theme-specific token blocks, making the diversification system fully auditable and reproducible.

Why Structural Fingerprint Diversification Matters

• Prevents indistinguishable outputs — Same macrostructure + same theme = identical appearance, defeating automation value
• Maintains perceptible variety — Three controlled axes yield visible change without brand drift
• Enables deterministic testing — Log-based state makes diversification behavior reproducible and verifiable
• Supports both exploration and consistency — Normal mode for landing pages, inverted mode for coherent applications

Summary

• Hallmark's diversification rule operates at macrostructure and theme levels to prevent identical structural fingerprints
• Macrostructures must differ from the last three builds; theme axes must differ by at least one of three dimensions
• Project state persists in .hallmark/log.json, read at build start and updated on successful completion
• The rule inverts when design.md exists, locking theme consistency for multi-page applications
• All behavior is specified in SKILL.md and implemented through deterministic log queries and axis comparisons

Frequently Asked Questions

What happens if only one theme exists in the catalog?

Hallmark proceeds with that theme regardless of axis matching. The diversification rule is a preference constraint, not a hard failure. If no alternative satisfies the axis-difference requirement, the system falls back to available options and logs a diagnostic.

How does the "drop" system interact with theme diversification?

Drops like night or day extend theme identity. Changing from Lumen-night to Lumen-day satisfies the diversification rule because the drop variation constitutes a perceptible difference. Each drop records separately in .hallmark/log.json with full axis values for accurate comparison.

Can I disable diversification for a specific page?

No direct disable flag exists. However, creating a design.md file through hallmark redesign inverts the rule to force theme consistency across pages. For single-page exceptions, manual CSS stamp editing would be required—though this breaks Hallmark's automated guarantees.

How many historical builds does Hallmark consider for macrostructure rotation?

Three. The macrostructure diversification rule specifically references the last three entries in the log or stamp history, while theme-axis comparison examines the immediately preceding theme (with optional lookback to 3-5 entries for complex drop sequences).

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