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

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 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 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.

<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.

<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>

.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/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.

<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>

.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/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

<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>

.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%;
  }
}

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.

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/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)

Source File Reference Map

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

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, 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 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 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.

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