# Bar list

A ranked list of names and figures, each over a bar that shows its share.

A block: a ready-made arrangement of components, to copy into a project. Its own classes carry the `site-` prefix; rename it to your project's own. Status: experimental. Figma: the Figma file, https://www.figma.com/community/file/1688324308358870630. Built from: Meter.

## Examples

### Usage

Four rows, largest first, every bar measured against the same round maximum.

```html
<ol class="site-bar-list" role="list" aria-label="Spending by team, this month">
  <li class="site-bar-list__row">
    <span class="site-bar-list__top">
      <span class="site-bar-list__label">Design</span>
      <span class="site-bar-list__figure">$1,357</span>
    </span>
    <div
      class="smbk-meter smbk-meter--tone-series smbk-progress site-bar-list__bar"
      aria-hidden="true"
    >
      <div
        class="smbk-progress__track"
        role="meter"
        aria-valuemin="0"
        aria-valuemax="1500"
        aria-valuenow="1357"
        aria-label="Design"
      >
        <span class="smbk-progress__fill" style="width:90.46666666666667%"></span>
      </div>
    </div>
  </li>
  <li class="site-bar-list__row">
    <span class="site-bar-list__top">
      <span class="site-bar-list__label">Hosting</span>
      <span class="site-bar-list__figure">$1,283</span>
    </span>
    <div
      class="smbk-meter smbk-meter--tone-series smbk-progress site-bar-list__bar"
      aria-hidden="true"
    >
      <div
        class="smbk-progress__track"
        role="meter"
        aria-valuemin="0"
        aria-valuemax="1500"
        aria-valuenow="1283"
        aria-label="Hosting"
      >
        <span class="smbk-progress__fill" style="width:85.53333333333333%"></span>
      </div>
    </div>
  </li>
  <li class="site-bar-list__row">
    <span class="site-bar-list__top">
      <span class="site-bar-list__label">Tools</span>
      <span class="site-bar-list__figure">$650</span>
    </span>
    <div
      class="smbk-meter smbk-meter--tone-series smbk-progress site-bar-list__bar"
      aria-hidden="true"
    >
      <div
        class="smbk-progress__track"
        role="meter"
        aria-valuemin="0"
        aria-valuemax="1500"
        aria-valuenow="650"
        aria-label="Tools"
      >
        <span class="smbk-progress__fill" style="width:43.333333333333336%"></span>
      </div>
    </div>
  </li>
  <li class="site-bar-list__row">
    <span class="site-bar-list__top">
      <span class="site-bar-list__label">Support</span>
      <span class="site-bar-list__figure">$522</span>
    </span>
    <div
      class="smbk-meter smbk-meter--tone-series smbk-progress site-bar-list__bar"
      aria-hidden="true"
    >
      <div
        class="smbk-progress__track"
        role="meter"
        aria-valuemin="0"
        aria-valuemax="1500"
        aria-valuenow="522"
        aria-label="Support"
      >
        <span class="smbk-progress__fill" style="width:34.8%"></span>
      </div>
    </div>
  </li>
</ol>
```

```tsx
import { Meter } from './design-system/components/meter/meter.js';

<ol className="site-bar-list" role="list" aria-label="Spending by team, this month">
  <li className="site-bar-list__row">
    <span className="site-bar-list__top">
      <span className="site-bar-list__label">Design</span>
      <span className="site-bar-list__figure">$1,357</span>
    </span>
    <Meter className="site-bar-list__bar" tone="series" value={1357} max={1500} aria-label="Design" aria-hidden="true" />
  </li>
  <li className="site-bar-list__row">
    <span className="site-bar-list__top">
      <span className="site-bar-list__label">Hosting</span>
      <span className="site-bar-list__figure">$1,283</span>
    </span>
    <Meter className="site-bar-list__bar" tone="series" value={1283} max={1500} aria-label="Hosting" aria-hidden="true" />
  </li>
  <li className="site-bar-list__row">
    <span className="site-bar-list__top">
      <span className="site-bar-list__label">Tools</span>
      <span className="site-bar-list__figure">$650</span>
    </span>
    <Meter className="site-bar-list__bar" tone="series" value={650} max={1500} aria-label="Tools" aria-hidden="true" />
  </li>
  <li className="site-bar-list__row">
    <span className="site-bar-list__top">
      <span className="site-bar-list__label">Support</span>
      <span className="site-bar-list__figure">$522</span>
    </span>
    <Meter className="site-bar-list__bar" tone="series" value={522} max={1500} aria-label="Support" aria-hidden="true" />
  </li>
</ol>
```

### Six rows

Six rows; the figures carry their own unit, here a count of visits.

```html
<ol class="site-bar-list" role="list" aria-label="Visits by page, this week">
  <li class="site-bar-list__row">
    <span class="site-bar-list__top">
      <span class="site-bar-list__label">Home</span>
      <span class="site-bar-list__figure">4,812</span>
    </span>
    <div
      class="smbk-meter smbk-meter--tone-series smbk-progress site-bar-list__bar"
      aria-hidden="true"
    >
      <div
        class="smbk-progress__track"
        role="meter"
        aria-valuemin="0"
        aria-valuemax="5000"
        aria-valuenow="4812"
        aria-label="Home"
      >
        <span class="smbk-progress__fill" style="width:96.24000000000001%"></span>
      </div>
    </div>
  </li>
  <li class="site-bar-list__row">
    <span class="site-bar-list__top">
      <span class="site-bar-list__label">Pricing</span>
      <span class="site-bar-list__figure">2,940</span>
    </span>
    <div
      class="smbk-meter smbk-meter--tone-series smbk-progress site-bar-list__bar"
      aria-hidden="true"
    >
      <div
        class="smbk-progress__track"
        role="meter"
        aria-valuemin="0"
        aria-valuemax="5000"
        aria-valuenow="2940"
        aria-label="Pricing"
      >
        <span class="smbk-progress__fill" style="width:58.8%"></span>
      </div>
    </div>
  </li>
  <li class="site-bar-list__row">
    <span class="site-bar-list__top">
      <span class="site-bar-list__label">Blog</span>
      <span class="site-bar-list__figure">2,105</span>
    </span>
    <div
      class="smbk-meter smbk-meter--tone-series smbk-progress site-bar-list__bar"
      aria-hidden="true"
    >
      <div
        class="smbk-progress__track"
        role="meter"
        aria-valuemin="0"
        aria-valuemax="5000"
        aria-valuenow="2105"
        aria-label="Blog"
      >
        <span class="smbk-progress__fill" style="width:42.1%"></span>
      </div>
    </div>
  </li>
  <li class="site-bar-list__row">
    <span class="site-bar-list__top">
      <span class="site-bar-list__label">Docs</span>
      <span class="site-bar-list__figure">1,377</span>
    </span>
    <div
      class="smbk-meter smbk-meter--tone-series smbk-progress site-bar-list__bar"
      aria-hidden="true"
    >
      <div
        class="smbk-progress__track"
        role="meter"
        aria-valuemin="0"
        aria-valuemax="5000"
        aria-valuenow="1377"
        aria-label="Docs"
      >
        <span class="smbk-progress__fill" style="width:27.54%"></span>
      </div>
    </div>
  </li>
  <li class="site-bar-list__row">
    <span class="site-bar-list__top">
      <span class="site-bar-list__label">About</span>
      <span class="site-bar-list__figure">603</span>
    </span>
    <div
      class="smbk-meter smbk-meter--tone-series smbk-progress site-bar-list__bar"
      aria-hidden="true"
    >
      <div
        class="smbk-progress__track"
        role="meter"
        aria-valuemin="0"
        aria-valuemax="5000"
        aria-valuenow="603"
        aria-label="About"
      >
        <span class="smbk-progress__fill" style="width:12.06%"></span>
      </div>
    </div>
  </li>
  <li class="site-bar-list__row">
    <span class="site-bar-list__top">
      <span class="site-bar-list__label">Contact</span>
      <span class="site-bar-list__figure">218</span>
    </span>
    <div
      class="smbk-meter smbk-meter--tone-series smbk-progress site-bar-list__bar"
      aria-hidden="true"
    >
      <div
        class="smbk-progress__track"
        role="meter"
        aria-valuemin="0"
        aria-valuemax="5000"
        aria-valuenow="218"
        aria-label="Contact"
      >
        <span class="smbk-progress__fill" style="width:4.36%"></span>
      </div>
    </div>
  </li>
</ol>
```

```tsx
import { Meter } from './design-system/components/meter/meter.js';

<ol className="site-bar-list" role="list" aria-label="Visits by page, this week">
  <li className="site-bar-list__row">
    <span className="site-bar-list__top">
      <span className="site-bar-list__label">Home</span>
      <span className="site-bar-list__figure">4,812</span>
    </span>
    <Meter className="site-bar-list__bar" tone="series" value={4812} max={5000} aria-label="Home" aria-hidden="true" />
  </li>
  <li className="site-bar-list__row">
    <span className="site-bar-list__top">
      <span className="site-bar-list__label">Pricing</span>
      <span className="site-bar-list__figure">2,940</span>
    </span>
    <Meter className="site-bar-list__bar" tone="series" value={2940} max={5000} aria-label="Pricing" aria-hidden="true" />
  </li>
  <li className="site-bar-list__row">
    <span className="site-bar-list__top">
      <span className="site-bar-list__label">Blog</span>
      <span className="site-bar-list__figure">2,105</span>
    </span>
    <Meter className="site-bar-list__bar" tone="series" value={2105} max={5000} aria-label="Blog" aria-hidden="true" />
  </li>
  <li className="site-bar-list__row">
    <span className="site-bar-list__top">
      <span className="site-bar-list__label">Docs</span>
      <span className="site-bar-list__figure">1,377</span>
    </span>
    <Meter className="site-bar-list__bar" tone="series" value={1377} max={5000} aria-label="Docs" aria-hidden="true" />
  </li>
  <li className="site-bar-list__row">
    <span className="site-bar-list__top">
      <span className="site-bar-list__label">About</span>
      <span className="site-bar-list__figure">603</span>
    </span>
    <Meter className="site-bar-list__bar" tone="series" value={603} max={5000} aria-label="About" aria-hidden="true" />
  </li>
  <li className="site-bar-list__row">
    <span className="site-bar-list__top">
      <span className="site-bar-list__label">Contact</span>
      <span className="site-bar-list__figure">218</span>
    </span>
    <Meter className="site-bar-list__bar" tone="series" value={218} max={5000} aria-label="Contact" aria-hidden="true" />
  </li>
</ol>
```

## Purpose

Ranks a few things by one figure, such as spending by team or visits by page, so a reader sees at once which are largest. Each row is a name and its figure over a bar.

## Anatomy

- The block, an ordered list, its rows a medium stack apart.
- Each row: the name in the small body style and the figure in its medium weight, on one line, over a bar.
- The bar is the Meter component in the series color, carrying the block's bar class beside its own. Its length is the figure's share of the largest value the list allows.

## When to use

- For four to eight rows of one figure, largest first.
- In a card or a panel beside a chart.

## When not to use

- For figures that change over time. Use a line or bar chart.
- For a share of one whole. Use a donut chart or a meter.
- For many rows or several figures per row. Use a table.

## Behavior

The rows come in the order the page gives, largest first. Every bar uses the same maximum, so their lengths compare; give the list a round maximum just above the largest figure, or the largest figure itself, which fills the first bar.

## Accessibility

### What it does for you

- The list is an ordered list, so a screen reader says how many rows there are, and each row reads as its name and figure, such as "Design, $1,357".
- The bars repeat the figures and are hidden from assistive technology, so nothing is read twice.
- The figure is always written out, so the bar's color and length are never the only sign.

### What you must do

- Name the list for what it ranks, such as "Spending by team, this month".
- Keep `role="list"` on the list, as the examples do: some screen readers stop reading a list as a list once its numbers are hidden.

### How to test

- With a screen reader, the list says how many rows it holds, and each row reads its name and figure once.
- In a forced-color mode, every row still says its figure in words.

## Usage rules

### Do

- Sort the rows, largest first.
- Write each figure with its unit.

### Don't

- Give the bars different maximums.
- Leave out the figures and show the bars alone.

## Stylesheet

```css
/* site-bar-list — Bar list, a block: a ranked list of rows, each a name and its figure over a bar that shows its
 * share. Copy it into your project and rename site- to your project's own prefix. The bar is the Meter component
 * in the series color, given this block's bar class beside its own; the block draws only the rows. */

.site-bar-list {
  display: flex;
  flex-direction: column;
  gap: var(--smbk-space-stack-md);
  margin: 0;
  padding: 0;
  list-style: none;
}

.site-bar-list__row {
  display: flex;
  flex-direction: column;
  gap: var(--smbk-space-6);
}

.site-bar-list__top {
  display: flex;
  align-items: baseline;
  gap: var(--smbk-space-inline-md);
}

.site-bar-list__label {
  flex: 1 1 auto;
  min-width: 0;
  color: var(--smbk-color-text-default);
  font-family: var(--smbk-typography-body-sm-font-family);
  font-size: var(--smbk-typography-body-sm-font-size);
  font-weight: var(--smbk-typography-body-sm-font-weight);
  line-height: var(--smbk-typography-body-sm-line-height);
  letter-spacing: var(--smbk-typography-body-sm-letter-spacing);
}

.site-bar-list__figure {
  flex: none;
  color: var(--smbk-color-text-default);
  font-family: var(--smbk-typography-body-sm-medium-font-family);
  font-size: var(--smbk-typography-body-sm-medium-font-size);
  font-weight: var(--smbk-typography-body-sm-medium-font-weight);
  line-height: var(--smbk-typography-body-sm-medium-line-height);
  letter-spacing: var(--smbk-typography-body-sm-medium-letter-spacing);
  font-variant-numeric: tabular-nums;
}
```