@ithaka/bonsai/documentation/pages/components/hero.md

ITHAKA core styling

---
title: Hero
description: A visually engaging area at the top of the page that introduces a product, collection, or service.
sass: ./scss/_hero.scss
---

## How to Use

The `.hero` banner is very simply comprised of a `.hero-heading` and a `.hero-description`. The default background
color is `$bonsai-primary` with `$bonsai-white` as the text color. Using the `-background` and `-color` utility
classes [on the color page](colors.html), the hero component can take any color scheme from the color pallet. Adding
the `.small` class will reduce the padding of the Hero by half.

```html_example
<div class="hero">
    <h1 class="hero-heading">I am a standard Hero</h1>
    <p class="hero-description">This is some descriptive text related to the Hero.</p>
</div>

<div class="hero mtl black-background">
    <h1 class="hero-heading">I am a dark Hero module</h1>
    <p class="hero-description">This is some descriptive text related to the Hero.</p>
</div>

<div class="hero mtl light-blue-background black-color small">
    <h1 class="hero-heading">I am a small, light Hero module</h1>
    <p class="hero-description">This is some descriptive text related to the Hero.</p>
</div>
```

## Variations
### Image Hero

To add an image to a hero, create a class that defines the `background-image` property and add that to the same
container as `.hero`.

```html_example
<div class="hero image-example">
    <h1 class="hero-heading">I am an Image Hero</h1>
    <p class="hero-description">This is some descriptive text related to the Hero.</p>
</div>
```

### Split Hero

In some cases, there is a desire to have an image background on the left with a solid color on the right. Adding the
`.split` class along with your custom class to define the desired background image.

```html_example
<div class="hero split image-example">
    <div class="row collapse">
        <div class="small-12 medium-6 columns hero-section">
            <h1 class="hero-heading">
                Hero Split
            </h1>
        </div>
        <div class="small-12 medium-5 medium-offset-1 columns hero-section">
            <p>
                I am a Hero Split
            </p>
        </div>
    </div>
</div>
```

The full color utility classes [on the color page](colors.html) are also supported to get the best
look to go with your background image.

```html_example
<div class="hero split green-image dark-green-background">
    <div class="row collapse">
        <div class="small-12 medium-6 columns hero-section">
            <h1 class="hero-heading">
                Hero Split
            </h1>
        </div>
        <div class="small-12 medium-5 medium-offset-1 columns hero-section">
            <p>
                I am a Hero Split, but with a <span class="bold">GREEN</span> background!!!
            </p>
        </div>
    </div>
</div>
```


### Reverse Split Hero

To reverse and have the color on the left and the image on the right, use `.split-reverse`

```html_example
<div class="hero split-reverse image-example">
    <div class="row collapse">
        <div class="small-12 medium-6 columns hero-section">
            <h1 class="hero-heading">
                Hero Split
            </h1>
        </div>
        <div class="small-12 medium-5 medium-offset-1 columns hero-section">
            <p>
                I am a Hero Split but <span class="bold">REVERSED!!</span>
            </p>
        </div>
    </div>
</div>
```


## Guidelines
1. The image can be an illustration or photograph that is related to the content of the page. Work with a visual
designer to obtain the best image based on the content and brand guidelines.
2. The height should not exceed 200px so that page content is not pushed down the page.
3. The image and title text will show for mobile, but the support text will disappear.
4. The Heading 1 text should overlay on the image
5. The short marketing description to the right should be about 140 characters
6. The link that took the user to the page should have some or all the words within the title/header


## Avoid
1. Do not have more than one 'hero' component on a single page.
2. Due to their size and command of attention, hero banners should not be used on pages with a high degree of
   technical and functional complexity (e.g., search results).

## Accessibility
1. The color contrast for the color field, monochromatic image, and text should be adhere to the level AA,
requiring a contrast ratio of at least 4.5:1 for normal text and 3:1 for large text.
2. A screen reader should read out the text, but does not need to describe the image unless it contains relevant
information.
3. Choose images that allow for readable text.