# Facts

> The key facts of one item in a bordered panel, with its one primary action and an optional note.

- Block class: `.hs-facts`
- CSS: `components/facts.css` (also inside https://brand.honorsociety.org/brand.css)
- JS: none
- Status: decided
- Decision record: https://brand.honorsociety.org/decisions/directories-round.html
- Variants: Scholarship, external, Benefit, ready to use, Benefit, locked
- HTML page: https://brand.honorsociety.org/components/facts/

## What it is

A plain bordered panel: an optional title, a list of three to six facts (label over value, between hairlines), one primary button and an optional small note. The first fact can carry a large value. It is the aside of the [Detail layout](/components/detail/).

## When to use

- The aside of a scholarship, benefit or university page: amount, offered by, deadline, membership needed, how to redeem, location.

## When not to use

- Facts inside a navy award hero: the [Award hero](/components/award-hero/) has its own facts.
- A member's credential: use the [Credential](/components/credential/).
- Two to three headline figures in a band: use the [Stat](/components/stat/).

## Rules

- Markup: `div.hs-facts` > optional `h2.hs-facts__title`, `dl.hs-facts__list` > `div.hs-facts__item` > `dt` + `dd`, then `div.hs-facts__action` and an optional `p.hs-facts__note`.
- Three to six facts. Skip a fact with no data; never print an empty value or a guess.
- The amount or the discount goes first, with `.hs-facts__item--value`. Only when it comes from data.
- A `dd` may hold a [Status](/components/status/), a [Tier badge](/components/tier-badge/) or one plain link.
- One action: `a.hs-button.hs-button--block`, gold by default. Use navy (`a.hs-button.hs-button--navy.hs-button--block`) only when a gold element already sits in the same viewport inside the page content. The site header's Join button is chrome and does not count. The label is verb + noun ("Apply on examplefoundation.org", "Get the code", "See tiers"). No arrows.
- An action that leaves the site gets `rel="noopener"` and the note "You leave honorsociety.org." in `.hs-facts__note`.
- A benefit above the viewer's tier: the membership fact shows a `--locked` status and the action routes to the tier page.
- Dates are `<time datetime>` from the one stored value.

## Accessibility

- `dl`, `dt`, `dd` pair each label with its value for a screen reader.
- The title names the aside landmark (`aria-labelledby` on the `aside`).
- Label slate 6.2:1, value ink 13.0:1, large value navy 12.4:1, note slate 6.2:1 on white.
- The button is 48px tall and fills the panel.

## Variants

### Scholarship, external

A directory scholarship that is applied for on the provider's site.

```html
<div class="hs-facts">
  <h2 class="hs-facts__title">Key facts</h2>
  <dl class="hs-facts__list">
    <div class="hs-facts__item hs-facts__item--value"><dt>Amount</dt><dd>$1,000</dd></div>
    <div class="hs-facts__item"><dt>Offered by</dt><dd>examplefoundation.org</dd></div>
    <div class="hs-facts__item"><dt>Who it&rsquo;s for</dt><dd>Graduate students</dd></div>
  </dl>
  <div class="hs-facts__action">
    <a class="hs-button hs-button--block" href="https://examplefoundation.org/apply" rel="noopener" data-ph-capture-attribute-cta="apply-external" data-ph-capture-attribute-cta-loc="detail">Apply on examplefoundation.org</a>
  </div>
  <p class="hs-facts__note">You leave honorsociety.org.</p>
</div>
```

### Benefit, ready to use

The redeem area of a benefit the viewer can use now.

```html
<div class="hs-facts">
  <h2 class="hs-facts__title">Key facts</h2>
  <dl class="hs-facts__list">
    <div class="hs-facts__item hs-facts__item--value"><dt>Value</dt><dd>20% off</dd></div>
    <div class="hs-facts__item"><dt>Category</dt><dd>Test prep</dd></div>
    <div class="hs-facts__item"><dt>Membership needed</dt><dd><span class="hs-status hs-status--ready">Ready to use</span></dd></div>
    <div class="hs-facts__item"><dt>How to redeem</dt><dd>Enter the code at checkout on the partner site.</dd></div>
  </dl>
  <div class="hs-facts__action">
    <a class="hs-button hs-button--block" href="/benefits/example-learning-co/redeem" data-ph-capture-attribute-cta="redeem" data-ph-capture-attribute-cta-loc="detail">Get the code</a>
  </div>
</div>
```

### Benefit, locked

A benefit above the viewer's tier: the status names the tier and the action routes to the tier page.

```html
<div class="hs-facts">
  <h2 class="hs-facts__title">Key facts</h2>
  <dl class="hs-facts__list">
    <div class="hs-facts__item hs-facts__item--value"><dt>Value</dt><dd>$50 off</dd></div>
    <div class="hs-facts__item"><dt>Category</dt><dd>Travel</dd></div>
    <div class="hs-facts__item"><dt>Membership needed</dt><dd><span class="hs-status hs-status--locked">Bronze and up</span></dd></div>
  </dl>
  <div class="hs-facts__action">
    <a class="hs-button hs-button--block" href="/membership-tiers" data-ph-capture-attribute-cta="membership-tiers" data-ph-capture-attribute-cta-loc="detail">See tiers</a>
  </div>
</div>
```