# Hallmark Diversification Rule: How It Prevents Identical Structural Fingerprints

> Discover how Hallmark's diversification rule prevents identical structural fingerprints by rotating macrostructures and varying theme axes for unique builds. Learn more.

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

---

**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](https://github.com/Nutlope/hallmark) repository, this system reads project memory from [`.hallmark/log.json`](https://github.com/Nutlope/hallmark/blob/main/.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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/.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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/.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`](https://github.com/Nutlope/hallmark/blob/main/.hallmark/log.json) for future diversification checks

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

```

*This log entry from [`.hallmark/log.json`](https://github.com/Nutlope/hallmark/blob/main/.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:

```python
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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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:

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

```

Documented in [`skills/hallmark/references/verbs/redesign.md`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md) | Primary specification of the theme-diversification rule (lines 274-280) and macrostructure rotation logic |
| [`skills/hallmark/references/verbs/redesign.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/verbs/redesign.md) | Defines the inverted rule for [`design.md`](https://github.com/Nutlope/hallmark/blob/main/design.md)-locked projects |
| [`skills/hallmark/references/themes/lumen.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/themes/lumen.md) | Demonstrates how drops extend theme identity in diversification logging |
| [`skills/hallmark/references/themes/carnival.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/themes/carnival.md) | Alternative theme reference showing per-drop axis recording |
| [`.hallmark/log.json`](https://github.com/Nutlope/hallmark/blob/main/.hallmark/log.json) (generated) | Persistent state store queried on every build |

Axis values resolve from [`site/css/tokens.css`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/.hallmark/log.json), read at build start and updated on successful completion
- The rule **inverts** when [`design.md`](https://github.com/Nutlope/hallmark/blob/main/design.md) exists, locking theme consistency for multi-page applications
- All behavior is specified in [`SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/.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`](https://github.com/Nutlope/hallmark/blob/main/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).