Anatomy of a hero section that converts

Most advice about the hero section stops at the ingredient list: headline, subheadline, image, button. That list is correct and it is not enough, because the part that goes wrong is never "we forgot the button." It is copy that outgrows its slot, a second call to action competing with the first, or an image that arrives a second and a half after everything else.

This is the hero section taken apart slot by slot: what each part is for, how much it can hold, and what to check once it exists as code.

What is a hero section for?

The hero is the first section of a page, above everything else, and it answers three questions before a reader decides whether to keep going: what is this, who is it for, and what happens if I click.

That is a smaller job than it is usually given. The hero does not have to explain the product. It has to make the next scroll worth it.

The fold still shapes this, though less absolutely than the old advice implies. Nielsen Norman Group's eyetracking research found users spent about 57% of page-viewing time above the fold and 74% in the first two screenfuls, down from the 80% above-the-fold figure their 2010 study recorded (NN/g, Scrolling and Attention). People scroll. They still weight the top heavily. Design for both: the hero carries the claim, and the sections under it carry the argument.

What goes in a hero section?

Six slots, in the order a reader meets them:

1. Tagline (optional). A short label above the headline: category, audience, or launch status. It is the cheapest way to add context without spending headline words.
2. Headline. One h1. The claim, stated plainly.
3. Description. One or two sentences that expand the claim into a benefit.
4. Primary CTA. The one action you want.
5. Secondary CTA (optional). The lower-commitment path for readers who are not ready.
6. Media. Product screenshot, video, or illustration that shows the thing being described.

Real proof can join this set when you have it: a rating, a logo row, a customer count. Only when you have it. Placeholder testimonials and invented numbers are the fastest way to lose a reader who was still deciding.

How much copy can each slot hold?

This is the constraint most hero sections violate, and it is the difference between a section that looks designed and one that looks generated.

The rule Initium's skill pack gives an agent is a headline budget: every heading fits on at most two visual lines in its block. Size the copy to the budget, not the block to the copy. A headline that wraps to four lines on a laptop is not a long headline, it is a layout bug that got shipped as copy.

In practice that lands around six to ten words for a hero h1 at heading-xl size, and two sentences for the description. Check it at three widths, not one: a headline that fits on two lines at 1440px can hit five on a 375px phone, where the hero is doing most of its work.

Buttons follow the same discipline. Two or three words each, and the two labels should not read as the same commitment. "Get started" next to "Learn more" reads as one primary path and one escape hatch. "Get started" next to "Start free" reads as a fork, and forks cost clicks.

One CTA or two?

Two, in most marketing heroes, with a visible difference in weight.

The reason is that a hero receives two kinds of reader at once: the one who arrived convinced and the one who arrived curious. A single primary button serves the first and strands the second, who then has nothing to do but scroll or leave. A secondary CTA gives them somewhere to go, as long as it is clearly subordinate.

Subordinate means visual, not verbal. In a shadcn setup that is the default button variant against outline or ghost, same size, same row. Once both buttons are solid and the same color, you no longer have a primary action, you have two suggestions.

What breaks a hero in implementation?

Four things, all of them invisible in a design file and obvious in a Lighthouse run.

The hero image is usually the LCP element. Largest Contentful Paint measures the render time of the largest image or text block in the viewport, which on a marketing page is almost always the hero visual. Google's guidance: aim for 2.5 seconds or less at the 75th percentile, never lazy-load the LCP image, and set fetchpriority="high" on the image you expect to be it (web.dev, Optimize LCP). One or two images at most, or the priority signal stops meaning anything.

If you are on Next.js 16, the prop for this changed: priority is deprecated in favor of preload on next/image (Next.js Image docs). Agents trained on older examples will still write priority, so it is worth checking.

Unreserved space shifts the layout. Cumulative Layout Shift comes from images and videos with unknown dimensions, fonts that render at a different size than their fallback, and content injected above existing content. The target is 0.1 or less (web.dev, CLS). A hero is exposed on all three counts, which is why Initium's Media component takes an aspectRatio and renders inside AspectRatio: the box exists before the image does.

Heading order. One h1 per page, then h2, and never a skipped level. MDN is direct about it: a page should generally have a single h1 describing the content, and you should not skip levels, because screen reader users navigating by heading are left wondering where the missing one went (MDN, Heading elements). The hero owns the h1. Every section below it starts at h2. When a hero gets copy-pasted into a docs page or a preview grid, this is the first thing to break.

Mobile order. On a split hero, decide deliberately whether the media stacks above or below the text on small screens. Whatever the grid does by default is a decision someone made for a different page.

How do you build one from blocks?

Install a hero, then edit the props rather than the markup:

npx shadcn@latest add @initium/hero-section-1

The block lands in your repo as a component you own, with the slots above exposed as props:

<HeroSection1
  taglineText="For product teams"
  title="Ship a landing page your designer would sign off on"
  description="Install the blocks, set a style preset, and let your agent assemble the page inside rules that keep it coherent."
  primaryCta={{ label: "Get started", href: "/docs/getting-started" }}
  secondaryCta={{ label: "Browse blocks", href: "/blocks" }}
  media={{
    type: "image",
    src: "/hero.png",
    alt: "Initium block library",
    aspectRatio: 16 / 9,
    sizes: "(min-width: 1024px) 512px, 100vw",
  }}
/>

Two details in that snippet do real work. aspectRatio reserves the box, which is the CLS fix. sizes tells the image pipeline the rendered width at each breakpoint, so a phone does not download a 1024px-wide asset. Anything else you pass in media reaches next/image directly, which is where the preload signal goes.

The general shape of hero variants is worth knowing before you pick one: split layouts with media on one side, centered layouts with the media below, and text-only heroes for pages where the product is hard to photograph. The choice is not aesthetic. A centered hero pushes the media below the fold on most laptops, which is the right call when the copy is the argument and the wrong call when the screenshot is.

How do you keep it intact when an agent edits it?

Heroes decay under editing more than any other section, because they are the section people ask to change. The copy gets longer, the second button gets promoted, a badge appears above the tagline, and three rounds later the two-line headline is four lines.

The fix is to hand the agent the constraints as rules rather than restating them per prompt. That is what agent skills are for: the headline budget, the one-h1 rule, the zigzag rhythm between adjacent sections, and the hard rule against invented proof all live in the skill pack, and the agent reads them before it edits. A rule that exists in a file survives; a rule that exists in a chat message from twenty minutes ago does not.

The check afterward is short, and it is the same one every time. Two lines or fewer on the headline at 375px, 768px, and 1440px. One h1. One clearly primary button. Media box reserved and preloaded. Nothing in the section that you cannot prove.

If you want to see the variants side by side before committing to one, the hero sections category has them, and the full section order explains what belongs directly under the one you pick.