aragrp/docs/design-system/hero.md

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

<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. 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
• buttons.md
• images.md
• motion.md