How Hallmark Handles Hero Enrichment and Its Hierarchy: A Design System Deep Dive

Hallmark treats hero enrichment as an optional, tiered decision-tree that prioritizes typography-only fallbacks and escalates through CSS art, SVG, generated imagery, and animation only when the brief explicitly demands it.

Hallmark is a disciplined design system that treats every visual element as a deliberate choice. When it comes to hero enrichment, the system follows a strict hierarchy to ensure that imagery serves the content without overwhelming it. This process occurs after a macro-structure has been selected (as defined in [skills/hallmark/references/macrostructures.md](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/macrostructures.md)) and is governed by the rules in [skills/hallmark/references/hero-enrichment.md](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/hero-enrichment.md).

Phase 1: Image-Need Detection (The Gate)

Before any visual asset is considered, Hallmark checks whether the brief actually requires imagery. This gate prevents unnecessary enrichment and keeps the hero section focused on copy and CTAs when appropriate.

The system maintains a table of brief signals that map keywords to an image strategy. For example:

• "e-commerce" → real product photos
• "API" → no imagery (typography-only)
• "SaaS landing" → kit-led imagery

The default strategy is typography-only (Tier 0). If the brief lacks visual cues, the enrichment pipeline stops early, enforcing the principle that enrichment must be justified. According to hero-enrichment.md (lines 11-26), this gate ensures designers do not reach for imagery out of habit.

The Enrichment Hierarchy (Tiers 0, A-E)

When imagery is required, Hallmark walks through a strict tiered hierarchy and selects the highest tier the brief supports within the time budget. The rule is simple: If you can do it in Tier A, do it in Tier A.

Tier	Type	Use Case
0	Typography only	No visual enrichment; pure copy and CTA. Always acceptable and the strongest fallback.
A	Custom-built CSS art	Pure-CSS shapes, gradients, and clip-paths for simple geometric decoration. Implementation details live in [custom-craft.md](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/custom-craft.md).
B	Hand-built SVG	Figma-designed, optimized, declarative SVG for complex illustrations impossible with CSS alone.
C	Generated illustration	AI-generated raster (Nanobanana, Midjourney) with provenance and post-processing for characters or scenes.
D	Library illustration	Storyset, Humaaans, or unDraw assets, recolored to brand. Budget-tight shortcuts never used unmodified.
E	Lottie animation	Complex motion (e.g., mascot loops) only when CSS/SVG cannot achieve the needed animation.

Asset sources for Tiers C through E are catalogued in [skills/hallmark/references/assets.md](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/assets.md). As documented in hero-enrichment.md (lines 41-53), this hierarchy forces designers to stay at the lowest possible tier that satisfies the brief, ensuring performance and maintaining design discipline.

Enrichment Archetypes (E1-E8)

Within a chosen tier, Hallmark defines eight concrete enrichment archetypes that specify what sits next to the headline. Each archetype includes "use when / avoid when" guidance and configurable knobs like clip side and aspect ratio.

Key archetypes include:

• E1 – Demo Video (clipped-by-viewport-edge): Best for SaaS demos with real product footage.
• E3 – Mock App Screenshot (browser-framed split): For clean web-app screenshots.
• E5 – Custom Illustration Centerpiece: Hand-built SVG or generated raster for brand stories.
• E8 – Hero Photography: Single tightly-cropped product or location photo.

The hierarchy ensures teams reach for the highest tier the brief permits but never skip a lower tier that already satisfies the need (hero-enrichment.md, lines 86-98). Concrete implementations of these archetypes appear in the test pages under site/_tests/.

The Decision Protocol: Eyeball or Ask

Hallmark implements a two-path algorithm for selecting enrichment. First, the system scans for explicit visual cues in the brief. Keywords like "demo," "platform," or "shop" map directly to archetypes (E1 for demos, E8 for shops).

If the brief remains ambiguous, the protocol asks a single clarifying question rather than guessing. When uncertain, it defaults to typography-only. This "Eyeball or ask" approach prevents inappropriate enrichment.

// Pseudocode from Hallmark's brief-parser logic
if (brief.includes('demo') || brief.includes('product tour')) {
  enrichment = 'E1';      // demo video
} else if (brief.includes('shop') || brief.includes('catalogue')) {
  enrichment = 'E8';      // hero photography
} else {
  // ambiguous – ask the user (default to typography)
  askUser('Add a demo video, illustration, or keep it typography-only?');
  enrichment = userChoice || '0';
}

This logic appears in the decision flow documentation (hero-enrichment.md, lines 58-78).

Discipline and Quality Gates

After selecting enrichment, Hallmark validates assets against eight pre-flight questions to ensure the hero remains performant and accessible. These gates verify:

• Asset size under 2MB
• Reduced-motion fallback availability
• Communication value justification
• Layout rules compliance (hero-footprint, asymmetric padding, single polish pattern)

These checks guarantee that enrichment has earned its place in the design (hero-enrichment.md, lines 31-34 and 84-92). Runtime logic for polish patterns (like the cursor-splight effect) resides in [site/js/main.js](https://github.com/Nutlope/hallmark/blob/main/site/js/main.js).

Implementation Examples by Tier

Tier A: Custom CSS Art

For geometric or gradient-based decoration without external assets:

<section class="hero hero--bg">
  <div class="hero__copy">
    <h1 class="hero__display">Design that speaks.</h1>
    <p class="hero__lede">Pure-CSS art, no external assets.</p>
  </div>
  <div class="hero__bg" aria-hidden="true"></div>
</section>

.hero--bg { 
  position: relative; 
  isolation: isolate; 
  min-height: clamp(60vh, 75dvh, 88dvh); 
}

.hero__bg {
  position: absolute; 
  inset: 0; 
  z-index: -1;
  background: linear-gradient(135deg,
    oklch(95% 0.02 30deg),   /* paper-like */
    oklch(90% 0.03 210deg));
}

This Tier A approach uses only CSS gradients, generated entirely in the browser with zero HTTP requests for imagery.

Tier E1: Demo Video with Reduced Motion Fallback

For product demos requiring video content:

<section class="hero hero--clipped">
  <div class="hero__copy">
    <h1>Plan, build, ship.</h1>
    <p>Observability that explains itself.</p>
    <a class="btn" href="/signup">Try it free</a>
  </div>
  <figure class="hero__media">
    <video autoplay muted loop playsinline preload="metadata"
           poster="/hero-poster.webp" fetchpriority="high"
           aria-label="Dashboard tour">
      <source src="/hero.av1.mp4" type='video/mp4; codecs="av01.0.05M.08"'>
      <source src="/hero.vp9.webm" type="video/webm">
    </video>
  </figure>
</section>

.hero--clipped {
  display: grid;
  grid-template-columns: minmax(20rem, 1fr) 1.4fr;
  gap: var(--space-2xl);
  align-items: center;
  overflow: visible;
}

.hero__media { 
  width: calc(100% + 12vw); 
  aspect-ratio: 16/10; 
  border: var(--rule-hair) solid var(--color-rule); 
}

@media (max-width: 60rem) { 
  .hero--clipped { 
    grid-template-columns: 1fr; 
  } 
  .hero__media { 
    width: 100%; 
  } 
}

@media (prefers-reduced-motion: reduce) { 
  .hero__media video { 
    display: none; 
  } 
  .hero__media {
    background: url('/hero-poster.webp') center/cover; 
  } 
}

This example demonstrates the E1 archetype with accessibility considerations, including reduced-motion fallbacks and AV1/VP9 codec prioritization for performance.

Summary

• Hallmark treats hero enrichment as optional, defaulting to typography-only (Tier 0) unless the brief explicitly demands imagery.
• The system follows a strict tiered hierarchy (0, A-E) that prioritizes lightweight solutions (CSS art) over heavy assets (Lottie, video), with implementation guidance split between hero-enrichment.md, custom-craft.md, and assets.md.
• Eight enrichment archetypes (E1-E8) provide concrete patterns for specific content types, from demo videos to hero photography.
• The "Eyeball or ask" protocol prevents inappropriate enrichment by requiring explicit brief signals or user confirmation.
• Quality gates enforce performance budgets (under 2MB), accessibility standards, and layout discipline to ensure enrichment earns its place.

Frequently Asked Questions

What is the default hero enrichment tier in Hallmark?

The default tier is 0 (Typography only). According to the source code in skills/hallmark/references/hero-enrichment.md, Hallmark starts with pure copy and CTA elements, adding visual enrichment only when the brief explicitly signals a need for imagery through specific keywords like "shop," "demo," or "platform."

Why does Hallmark prioritize CSS art (Tier A) over SVG or generated images?

Hallmark prioritizes Tier A (Custom-built CSS art) because it eliminates HTTP requests, reduces bundle size, and maintains crisp rendering at any resolution. The hierarchy rule states: "If you can do it in tier A, do it in tier A." This discipline ensures teams exhaust lightweight, code-based solutions before resorting to external assets that impact Core Web Vitals.

How does Hallmark handle ambiguous briefs that don't specify imagery needs?

When briefs lack explicit visual cues, Hallmark follows the "Eyeball or ask" protocol. The system maps clear keywords to specific archetypes (E1-E8), but if ambiguity remains, it prompts users with a single clarifying question and defaults to typography-only (Tier 0). This prevents unnecessary visual clutter and maintains design discipline.

What are the quality gates for hero enrichment in Hallmark?

After selecting enrichment, assets must pass eight pre-flight questions including size under 2MB, reduced-motion fallback availability, and justification of communication value. Additionally, layout rules enforce hero-footprint constraints, asymmetric padding, and a single polish pattern. These gates are documented in skills/hallmark/references/hero-enrichment.md (lines 31-34 and 84-92).

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