# Ring

Shows one value over a goal, or the shares of a total, as half a ring over the figure that says it.

### Known issues
None known.

### Copy the markup
Link `components/ring.css` of `@luz-ds/catalog` after `luz.css`. One value over a goal:

Ring markup
```html
<figure class="luz-ring" style="--v1: 1260; --max: 2000">
  <figcaption>Visitors this month</figcaption>
  <p class="luz-ring__value">
    <span class="luz-ring__figure">1,260</span>
    <span class="luz-ring__label">of 2,000 visitors</span>
  </p>
</figure>
```

Series that add up to a total, with a legend:

Stacked ring markup
```html
<figure class="luz-ring" style="--v1: 1260; --v2: 570">
  <figcaption>Visitors by device, this month</figcaption>
  <p class="luz-ring__value">
    <span class="luz-ring__figure">1,830</span>
    <span class="luz-ring__label">visitors</span>
  </p>
  <ul class="luz-ring__legend">
    <li class="luz-ring__item"><span class="luz-ring__name">Desktop</span> <span class="luz-ring__figure">1,260</span></li>
    <li class="luz-ring__item"><span class="luz-ring__name">Mobile</span> <span class="luz-ring__figure">570</span></li>
  </ul>
</figure>
```

### Variants and options
- `--v1`: The first series, a plain number (1260, not 1,260). `--v2` to `--v4` add up to three more, in the order of the legend
- `--max`: The goal. Without it, or when the series add up to more, they fill the ring
- `--luz-ring-size`: The widest the half ring gets, 18rem by default; it shrinks to its box
- `--luz-ring-color`: The colour of the first series, such as `var(--luz-chart-5)`; the others keep `--luz-chart-2` to `--luz-chart-4`

### How it works
The text is the data: the caption, the figure and its label, and for series a legend. The ring is a picture of it, drawn by the two pseudo-elements of the paragraph (the track and the series, each cut to a band by a mask), so assistive technology never meets it.

Each series takes its `--v` over `--max`, or over the sum of the values with no `--max`, and `--luz-chart-1` to `--luz-chart-4` in order, the colours of the legend's swatches. It runs from the left, clockwise, in every language, as a clock does. The inline `style` sets only numbers; with a strict `style-src`, set them in a rule of your own.

The figure is a size container: under 14em the text goes under the arc, not inside it. On paper the ring is left out and the text prints.

### Without JavaScript
It needs none. Without the stylesheet it reads as its caption, the figure and its label, and the legend; there is no ring.

### Keyboard and ARIA
Nothing takes focus and there is no ARIA: a screen reader reads the caption, the figure, its label and the legend, in that order. Write the goal into the label (“of 2,000 visitors”): the ring alone does not say it.

In forced colors the track is the background, so the gaps between series are too; the series and the swatches take the same system colours, and each swatch shows its series number.

### When to use
Use it in a panel for how far one value is to its goal (a quota, a budget, a storage limit), or how a total splits in two or three parts, when the figure is the point and the ring a glance at it.

### When not to use
Do not use it to compare values (use a [bar list](https://nandovejer.github.io/luz/docs/catalog/bar-list/) or a [column chart](https://nandovejer.github.io/luz/docs/catalog/column-chart/): a length reads better than an angle), for more than four series (use a [stacked bar](https://nandovejer.github.io/luz/docs/catalog/stacked-bar/)), or for a value in running text or a form (use a [meter](https://nandovejer.github.io/luz/docs/components/meter/)).