# Hero

Hero guidelines for marketing landings. Reference implementations: `components/hero-section.tsx`, `hero-50.tsx`, `hero-213.tsx`.

This design system does **not** invent a new hero—it constrains future heroes to the same layout, token, and motion language.

## First-viewport budget

Prefer:

1. Brand / logo presence (via global header).
2. One headline (`type.display` or `type.h1`).
3. One short supporting sentence.
4. One CTA group (primary + optional secondary).
5. One dominant visual (background or product image).

Avoid packing stats, schedules, address blocks, or promo chips into the first viewport.

## Layout

```tsx
<section className="bg-background"> {/* or bg-gradient-hero */}
  <div className="relative pt-24 md:pt-36">
    <Container>
      <div className={typeSpacing.heroStack}>
        <h1 className={type.display}>…</h1>
        <p className={cn(type["body-lg"], "text-muted-foreground")}>…</p>
        <div className="flex flex-wrap items-center gap-3">
          <Button size="lg">…</Button>
          <Button size="lg" variant="secondary">…</Button>
        </div>
      </div>
    </Container>
  </div>
</section>
```

Rules:

- Clearance under fixed header: at least `pt-24` / `md:pt-36` (or `layout.sectionTopWithHeader` on simpler pages).
- Content width: site `<Container>` — do not invent `max-w-7xl` shells for new work (legacy heroes being migrated should move to `Container`).
- Full-bleed **background** images are encouraged; foreground copy stays constrained.
- No detached floating badges/stickers on top of hero media.

## Backgrounds

Allowed:

- `bg-gradient-hero` utility.
- Theme-aware `next/image` backgrounds (`dark:block` / `hidden dark:…`).
- Soft radial washes inside a clipped absolute layer.

See [gradients.md](./gradients.md). Decorative layers must not cause horizontal scroll.

## Motion

- Entrance: opacity + translateY (+ optional blur) via `AnimatedGroup` / `TextEffect` / `MotionReveal`.
- Prefer spring or `blockEase` from `lib/block-motion.ts`.
- Respect `prefers-reduced-motion` (MotionReveal already does).
- Do not animate layout width/height for entrance—use transform/opacity.

## CTA rules

- Primary = `Button` default `size="lg"`.
- Secondary = `variant="secondary"` or `outline`.
- On dark brand panels use `surface="brand"`.

## Imagery

- Provide explicit `width` / `height` or `fill` + sized parent to avoid CLS.
- Use `sizes` appropriate to viewport (`100vw` for full-bleed backgrounds).
- `object-cover` for atmospheric photos; keep focal point sensible for RTL crops.

## Forbidden

- Card-wrapped heroes.
- Inset rounded media as the only hero treatment when a full-bleed treatment is the site norm.
- Extra containers that misalign with the header.

## Related

- [navbar.md](./navbar.md)
- [buttons.md](./buttons.md)
- [images.md](./images.md)
- [motion.md](./motion.md)