# Understanding the Hero Enrichment Hierarchy in HallMark: From Typography to Lottie

> Explore the hero enrichment hierarchy in Hallmark, from typography to Lottie animations. Discover the six-tier system for choosing the right visual elements for your projects.

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

---

**The hero enrichment hierarchy in HallMark is a six-tier decision system that starts with typography-only (Tier 0) and escalates through custom CSS art, hand-built SVG, generated illustrations, library assets, and finally Lottie animations (Tier E) only when complex motion is absolutely required.**

HallMark treats the hero section as the most visible surface on any page, enforcing a disciplined workflow that separates *layout* (macro-structure), *enrichment* (media), and *polish* (typographic styling). The system lives in [`skills/hallmark/references/hero-enrichment.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/hero-enrichment.md) and ensures enrichment is *earned* rather than added by default.

## Image-Need Detection: The Gatekeeper

Before any hero enrichment hierarchy selection begins, every brief must pass through **image-need detection**.

The default state is **Tier 0—typography-only**. Only briefs that explicitly demand imagery—such as e-commerce, photography portfolios, or SaaS product tours—move past this gate. The detection table in [`hero-enrichment.md § Image-need detection`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/hero-enrichment.md#image-need-detection) defines which project types justify media enrichment.

This gate prevents visual bloat. According to the HallMark source code, skipping this step and defaulting to imagery is considered "templated" behavior and is actively discouraged.

## The Six Tiers of Hero Enrichment

Once imagery is required, the hero enrichment hierarchy mandates selecting the **lowest tier** that satisfies the brief. Jumping to higher tiers without justification violates the system's discipline rules.

### Tier 0: Typography Only

The strongest fallback. No media, just headline, lede, and optional CTA.

```html
<section class="hero hero--marquee">
  <div class="hero__copy">
    <p class="hero__eyebrow">Studio · 2026</p>
    <h1 class="hero__display">A working archive.</h1>
    <p class="hero__lede">Twelve years. Selected projects, in their own time.</p>
    <a class="btn" href="/portfolio">Explore</a>
  </div>
</section>

```

*No media element is present; the hero relies solely on type and spacing.*

### Tier A: Custom-Built CSS Art

Pure CSS shapes, gradients, and clip-paths—zero external assets. Use for geometric or glyph-style decoration that can be expressed with code rather than images.

```html
<header class="hero hero--rail">
  <p class="hero__rail" aria-hidden="true">STUDIO · 2026 · WORK · LETTERS</p>
  <div class="hero__body">
    <h1 class="hero__display">A working archive.</h1>
    <p class="hero__lede">Twelve years. Selected projects, in their own time.</p>
  </div>
</header>

```

```css
.hero--rail {
  display: grid;
  grid-template-columns: auto 1fr;
  gap: var(--space-2xl);
  padding: var(--space-2xl) var(--page-gutter);
  align-items: end;
}

.hero__rail {
  writing-mode: vertical-rl;
  text-orientation: mixed;
  font-family: var(--font-display);
  font-size: var(--text-sm);
  letter-spacing: 0.18em;
  color: var(--color-ink-2);
}

```

See [[`custom-craft.md`](https://github.com/Nutlope/hallmark/blob/main/custom-craft.md)](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/custom-craft.md) for CSS art construction patterns.

### Tier B: Hand-Built SVG

SVG designed in tools like Figma and hand-optimized. Reserved for complex illustrations—loaves, mascots, diagrams—that exceed CSS capabilities but must remain lightweight and crisp.

### Tier C: Generated Illustration

AI-generated raster assets from Nanobanana, Recraft V4, or Midjourney with post-processing. Deploy when a specific character or scene is needed but hand-drawing is too costly.

### Tier D: Library Illustration

Pre-made libraries (Storyset, Humaaans, unDraw) recolored to match branding. Appropriate for tight deadlines where generic illustration suffices, provided it is customized rather than dropped in raw.

### Tier E: Lottie Animation—Last Resort Only

JSON-based animation used **only** when complex character motion cannot be achieved with CSS or SVG. As implemented in HallMark, this tier requires explicit justification.

```html
<section class="hero hero--lottie">
  <div class="hero__copy">
    <h1 class="hero__display">Track every trace.</h1>
    <p class="hero__lede">Real‑time observability for modern systems.</p>
  </div>
  <figure class="hero__media">
    <lottie-player src="/animations/traceflow.json"
                   background="transparent"
                   speed="1"
                   loop
                   autoplay
                   style="width:100%;height:auto"
                   aria-label="Traceflow animation"></lottie-player>
  </figure>
</section>

```

```css
.hero--lottie .hero__media {
  width: 100%;
  max-width: 48rem;
}

@media (prefers-reduced-motion: reduce) {
  .hero--lottie lottie-player { display:none; }
}

```

The Lottie is only approved after tiers A-D have been ruled out and the brief explicitly demands complex motion (e.g., a mascot loop). Accessibility fallbacks via `prefers-reduced-motion` are mandatory, as specified in [[`motion.md`](https://github.com/Nutlope/hallmark/blob/main/motion.md)](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/motion.md).

## Hero Shape Polish Patterns

After selecting an enrichment tier (or none), the hero enrichment hierarchy allows **one** of four structural polish patterns. These affect layout or motion, not decoration:

| Pattern | Effect | When to Use |
|---------|--------|-------------|
| **HP1 – Vertical-rail title** | Adds vertical text rail beside hero body | Centered or marquee-shaped heroes needing anchoring |
| **HP2 – Marquee-overflow** | H1 overflows viewport width for manifesto feel | Short, punchy headlines on Brutal or Manifesto genres |
| **HP3 – Cursor-spotlight** | Radial gradient follows cursor, scoped to hero | Atmospheric SaaS or dark-mode pages |
| **HP4 – Decorative-numeral** | Large edition/issue number in corner | Pages with semantic numbers (magazine issues, versions) |

Mixing patterns creates visual chaos. Only one polish pattern may be applied per hero.

### Implementing HP3 Cursor Spotlight

```html
<header class="hero hero--spotlight">
  <div class="hero__spotlight" aria-hidden="true"></div>
  <div class="hero__body">
    <h1 class="hero__display">Distributed tracing that explains itself.</h1>
    <p class="hero__lede">Open one trace. See the whole story.</p>
  </div>
</header>

```

```css
.hero--spotlight {
  position: relative;
  isolation: isolate;
  padding: var(--space-2xl) var(--page-gutter);
  overflow: hidden;
}

.hero__spotlight {
  position: absolute;
  inset: 0;
  z-index: -1;
  background: radial-gradient(
    600px circle at var(--mx, 50%) var(--my, 30%),
    color-mix(in oklch, var(--color-accent) 22%, transparent),
    transparent 60%
  );
  transition: background 200ms var(--ease-out);
}

@media (prefers-reduced-motion: reduce) {
  .hero__spotlight {
    transition: none;
    --mx: 50%;
    --my: 30%;
  }
}

```

```javascript
const hero = document.querySelector('.hero--spotlight');
hero?.addEventListener('pointermove', e => {
  const r = hero.getBoundingClientRect();
  hero.style.setProperty('--mx', `${e.clientX - r.left}px`);
  hero.style.setProperty('--my', `${e.clientY - r.top}px`);
});

```

Full polish pattern definitions are in [`hero-enrichment.md § Hero shape polish`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/hero-enrichment.md#hero-shape-polish).

## Complete Decision Flow

The hero enrichment hierarchy integrates into HallMark's broader hero construction process:

1. **Choose macro-structure**—Marquee, Stat-Led, Quote-Led, Letter, Photographic, or Clipped (see [[`macrostructures.md`](https://github.com/Nutlope/hallmark/blob/main/macrostructures.md)](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/macrostructures.md))

2. **Run image-need detection gate**

3. **Pick zero-or-one enrichment archetype** (E1–E8) following tier hierarchy

4. **Pick zero-or-one polish pattern** (HP1–HP4)

5. **Apply hero space discipline rules**—height, asymmetric padding, single animation limit, etc.

6. **Stamp choices into macro-structure comment block** (see "Output stamp" example in [`hero-enrichment.md`](https://github.com/Nutlope/hallmark/blob/main/hero-enrichment.md))

## Source File Reference Map

| File | Role | Link |
|------|------|------|
| [`skills/hallmark/references/hero-enrichment.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/hero-enrichment.md) | Core hierarchy, image-need detection, tier table, polish patterns | [View](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/hero-enrichment.md) |
| [`skills/hallmark/references/macrostructures.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/macrostructures.md) | Six macro-structure definitions | [View](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/macrostructures.md) |
| [`skills/hallmark/references/custom-craft.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/custom-craft.md) | Tier A CSS art and Tier B SVG construction | [View](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/custom-craft.md) |
| [`skills/hallmark/references/assets.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/assets.md) | Tiers C-E: generated assets and library illustrations | [View](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/assets.md) |
| [`skills/hallmark/references/motion.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/motion.md) | Animation discipline, reduced-motion fallbacks | [View](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/motion.md) |
| [`site/_tests/README.md`](https://github.com/Nutlope/hallmark/blob/main/site/_tests/README.md) | Test suite validating enrichment decision flow | [View](https://github.com/Nutlope/hallmark/blob/main/site/_tests/README.md) |
| [`site/css/components.css`](https://github.com/Nutlope/hallmark/blob/main/site/css/components.css) | CSS snippets for hero components | [View](https://github.com/Nutlope/hallmark/blob/main/site/css/components.css) |

## Summary

- The **hero enrichment hierarchy** enforces a six-tier system from typography (Tier 0) to Lottie (Tier E), always selecting the lowest sufficient tier.

- **Image-need detection** gates all enrichment—typography-only is the default, not a fallback.

- **Tiers A through D** prioritize performance: CSS art, hand-built SVG, generated illustrations, and customized library assets all outperform raster alternatives.

- **Tier E Lottie** is explicitly last-resort, reserved for complex character motion that cannot be achieved through lighter means.

- **One polish pattern maximum** (HP1-HP4) may be applied after enrichment selection; mixing patterns is prohibited.

- Every decision is stamped into the macro-structure comment block for traceability and testing validation.

## Frequently Asked Questions

### Why does HallMark discourage using Lottie animations by default?

According to the HallMark source in [`hero-enrichment.md`](https://github.com/Nutlope/hallmark/blob/main/hero-enrichment.md), defaulting to Lottie is considered "templated" behavior that adds unnecessary payload and complexity. The hierarchy demands that complex motion (Tier E) be justified only after CSS art (Tier A), hand-built SVG (Tier B), generated illustrations (Tier C), and library assets (Tier D) have been ruled out. This discipline keeps heroes performant and purposeful.

### How do I decide between Tier A CSS art and Tier B hand-built SVG?

Choose **Tier A** when the decorative element can be expressed with geometric shapes, gradients, or clip-paths without external assets. Move to **Tier B** when the illustration requires complex organic forms, detailed mascots, or intricate diagrams that exceed CSS capabilities. The [`custom-craft.md`](https://github.com/Nutlope/hallmark/blob/main/custom-craft.md) file provides construction patterns for both tiers.

### Can I combine multiple polish patterns on one hero?

No. The hero enrichment hierarchy explicitly prohibits mixing polish patterns, as this creates "visual chaos." Only one of HP1 (vertical-rail), HP2 (marquee-overflow), HP3 (cursor-spotlight), or HP4 (decorative-numeral) may be applied per hero. Select the pattern that best serves the brief's atmospheric and structural needs.

### Where does accessibility fit into the enrichment hierarchy?

Reduced-motion fallbacks are mandatory at every tier. The [`motion.md`](https://github.com/Nutlope/hallmark/blob/main/motion.md) specification requires that all animations respect `prefers-reduced-motion`, and Tier E Lottie implementations must include CSS rules that hide the animation when this preference is active. The hierarchy prioritizes static-first design, ensuring heroes remain functional and legible without motion.