Hero section

6 min · Pattern

Every marketing page starts with a hero: eyebrow, headline, description, and actions — optionally with a subtle ambient glow.

Anatomy

A Once UI hero has four layers:

Optional ambient glow — full-bleed Background outside maxWidth
Eyebrow — label-default-s in brand color
Headline — display-strong-l or display-strong-xl
Actions — Row of buttons, stacking on mobile

Basic hero (no decoration)

<Column fillWidth horizontal="center" paddingY="80">
  <Column maxWidth="m" gap="24" horizontal="center">
    <Text variant="label-default-s" onBackground="brand-medium" align="center">
      EYEBROW
    </Text>
    <Heading variant="display-strong-l" align="center">
      Build faster with Once UI
    </Heading>
    <Text variant="body-default-m" onBackground="neutral-weak" align="center">
      A semantic design system for humans and agents.
    </Text>
    <Row gap="16" horizontal="center" s={{ direction: "column" }}>
      <Button href="/start">Get started</Button>
      <Button variant="secondary" href="/docs">Documentation</Button>
    </Row>
  </Column>
</Column>

Hero with glow (optional)

Add one ambient layer on the full-bleed wrapper, not inside maxWidth:

<Column fillWidth horizontal="center" paddingY="80">
  <Background
    position="absolute" top="0" left="0" fill pointerEvents="none"
    gradient={{
      display: true,
      colorStart: "brand-alpha-medium",
      colorEnd: "static-transparent",
      x: 50, y: 0,
      width: 150, height: 80,
      opacity: 60,
    }}
    dots={{ display: true, color: "neutral-alpha-weak", size: "2", opacity: 40 }}
  />
  <Column zIndex={1} maxWidth="m" gap="24" horizontal="center">
    {/* hero content */}
  </Column>
</Column>

Typography hierarchy

Element	Variant
Eyebrow	`label-default-s` + `onBackground="brand-medium"`
Headline	`display-strong-l` (or `xl` for landing pages)
Description	`body-default-m` + `onBackground="neutral-weak"`

Never use heading-* for the main hero title.

Decoration budget

ambient layer per hero section

6 min · Pattern

Every marketing page starts with a hero: eyebrow, headline, description, and actions — optionally with a subtle ambient glow.

Anatomy

A Once UI hero has four layers:

Optional ambient glow — full-bleed Background outside maxWidth
Eyebrow — label-default-s in brand color
Headline — display-strong-l or display-strong-xl
Actions — Row of buttons, stacking on mobile

Basic hero (no decoration)

<Column fillWidth horizontal="center" paddingY="80">
  <Column maxWidth="m" gap="24" horizontal="center">
    <Text variant="label-default-s" onBackground="brand-medium" align="center">
      EYEBROW
    </Text>
    <Heading variant="display-strong-l" align="center">
      Build faster with Once UI
    </Heading>
    <Text variant="body-default-m" onBackground="neutral-weak" align="center">
      A semantic design system for humans and agents.
    </Text>
    <Row gap="16" horizontal="center" s={{ direction: "column" }}>
      <Button href="/start">Get started</Button>
      <Button variant="secondary" href="/docs">Documentation</Button>
    </Row>
  </Column>
</Column>

Hero with glow (optional)

Add one ambient layer on the full-bleed wrapper, not inside maxWidth:

<Column fillWidth horizontal="center" paddingY="80">
  <Background
    position="absolute" top="0" left="0" fill pointerEvents="none"
    gradient={{
      display: true,
      colorStart: "brand-alpha-medium",
      colorEnd: "static-transparent",
      x: 50, y: 0,
      width: 150, height: 80,
      opacity: 60,
    }}
    dots={{ display: true, color: "neutral-alpha-weak", size: "2", opacity: 40 }}
  />
  <Column zIndex={1} maxWidth="m" gap="24" horizontal="center">
    {/* hero content */}
  </Column>
</Column>

Typography hierarchy

Element	Variant
Eyebrow	`label-default-s` + `onBackground="brand-medium"`
Headline	`display-strong-l` (or `xl` for landing pages)
Description	`body-default-m` + `onBackground="neutral-weak"`

Never use heading-* for the main hero title.

Decoration budget

ambient layer per hero section

✅ Once UI way	❌ Common mistake
`display-strong-l` for headline	`heading-strong-xl` for hero
Glow outside `maxWidth` column	Glow clipped inside narrow container
`pointerEvents="none"` on Background	Clickable decoration blocking buttons
One glow per hero	Multiple competing gradient layers

Anatomy

Basic hero (no decoration)

Hero with glow (optional)

Typography hierarchy

Decoration budget

Anatomy

Basic hero (no decoration)

Hero with glow (optional)

Typography hierarchy

Decoration budget

Write this / not this

Check yourself

Hero section

Anatomy

Basic hero (no decoration)

Hero with glow (optional)

Typography hierarchy

Decoration budget

Anatomy

Basic hero (no decoration)

Hero with glow (optional)

Typography hierarchy

Decoration budget

Write this / not this

Check yourself

Related