# Donut chart

> Two to four shares of one whole around a ring: the budget above the line, production and post, with the total in the hole and every share written beside it.

Source: https://kwark.space/designSystem/components/donut-chart

## Usage

### What it is
A ring cut into the shares of one meaningful whole, with the whole written in the hole. People read rings poorly for small differences, so Kwark always writes every share beside it: the ring is the picture, the list is the information.

The specimen is the budget's three parts, the same figures as the [Budget top sheet](https://kwark.space/designSystem/components/budget-top-sheet.md): above the line, production, post. Producers and financiers ask this first.

### When to use
- Two to four shares of one whole that means something: the budget's parts, day and night scenes, interior and exterior pages.

### When not to
- More than four parts, or parts close in size. Use a [Bar chart](https://kwark.space/designSystem/components/bar-chart.md).
- Two rings side by side to compare. Angles do not compare; use bars.
- **Never as a progress ring** for creative work (*Draft 72% complete*). Kwark does not grade the work (Decision 0002).

### Anatomy in use
- Ring slices in Palette No. 300 order (coral, aqua, mango, mint), each followed by a 0.4-unit gap so neighbouring slices never touch.
- Starts at twelve o'clock, runs clockwise, in the same order as the list.
- The total in the hole with its unit; shares in the list with percentage and amount.

### Writing
Percentages round to whole numbers that add to 100. The reading picks the one fact: *Production takes just over half.*

**Do:** Three slices, the total in the hole, each share as *53% · 31,25,000*.

**Don't:** A seven-slice pie with a legend in a different order and no amounts.

## Style

### Anatomy

1. **Ring**: 136px (112px on a phone), stroke 7 units of a 42-unit viewBox, track `--k-raise`.
2. **Hole**: figure 20px 600 tabular, unit 12px `--k-text-2`.
3. **List**: rows 36px; a 10px square key, name 14px 500, share 14px 600 tabular, amount 12px tabular `--k-text-2`.
4. **Layout**: ring left, list right, 24px apart; stacked on a phone.

### Tokens

| Token | Light | Dark |
|---|---|---|
| `--k-chart-coral` | #bf5d45 | var(--k-brand-coral) |
| `--k-chart-aqua` | #509ca0 | var(--k-brand-aqua) |
| `--k-chart-mango` | #b4802e | var(--k-brand-mango) |
| `--k-raise` | #f1f5f9 | #252525 |
| `--k-surface` | #ffffff | #1a1a1a |
| `--k-text` | #0f172a | #e3e3e3 |
| `--k-text-2` | #5b6779 | #9ca3af |
| `--k-radius-card` | 10px |  |
| `--k-fs-meta` | 12px |  |
| `--k-fs-head` | 20px |  |

### States
| State | Look |
|---|---|
| Rest | As drawn |
| One part only | No ring; a sentence with the amount |
| A share under 2% | Drawn at 2% so it can be seen; the list gives the true figure |

## Code

### React

Use the HTML below with `kwark.css`. The example shows the markup and styling. Supply any application behavior described on this page.

### HTML and CSS

Works anywhere with `kwark.css`.

```html
<figure class="kw-viz kw-viz--compact">
  <figcaption class="kw-viz__head"><div><p class="kw-viz__title">Budget by part · INR</p><p class="kw-viz__reading">Production takes just over half of the ₹59.45 lakh budget.</p></div><label class="kw-viz__switch"><input class="kw-visually-hidden" type="checkbox" role="switch" aria-label="Show budget shares as a table"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><rect x="3" y="4" width="18" height="16" rx="2"/><path d="M3 10h18M3 15h18M9 10v10"/></svg><span>Table</span></label></figcaption>
  <div class="kw-viz__plot">
    <div class="kw-donut2">
      <div class="kw-donut2__ring" aria-hidden="true">
        <svg viewBox="0 0 42 42"><circle class="kw-donut2__track" cx="21" cy="21" r="15.9" pathLength="100"/><circle cx="21" cy="21" r="15.9" pathLength="100" style="--kw-c:var(--k-chart-coral)" stroke-dasharray="30.2 69.8" stroke-dashoffset="-0.4"/><circle cx="21" cy="21" r="15.9" pathLength="100" style="--kw-c:var(--k-chart-aqua)" stroke-dasharray="52.2 47.8" stroke-dashoffset="-31.4"/><circle cx="21" cy="21" r="15.9" pathLength="100" style="--kw-c:var(--k-chart-mango)" stroke-dasharray="15.2 84.8" stroke-dashoffset="-84.4"/></svg>
        <span><strong>59.45</strong><small>lakh INR</small></span>
      </div>
      <ul class="kw-donut2__shares" aria-hidden="true">
        <li style="--kw-c:var(--k-chart-coral)"><b>Above the line</b><span>31%</span><em>18,40,000</em></li>
        <li style="--kw-c:var(--k-chart-aqua)"><b>Production</b><span>53%</span><em>31,25,000</em></li>
        <li style="--kw-c:var(--k-chart-mango)"><b>Post-production</b><span>16%</span><em>9,80,000</em></li>
      </ul>
    </div>
  </div>
  <div class="kw-viz__table"><table><caption>Budget by part, INR</caption><thead><tr><th scope="col">Part</th><th scope="col" class="num">Share</th><th scope="col" class="num">Amount</th></tr></thead><tbody><tr><th scope="row">Above the line</th><td class="num">31%</td><td class="num">18,40,000</td></tr><tr><th scope="row">Production</th><td class="num">53%</td><td class="num">31,25,000</td></tr><tr><th scope="row">Post-production</th><td class="num">16%</td><td class="num">9,80,000</td></tr><tr><th scope="row">Total</th><td class="num">100%</td><td class="num">59,45,000</td></tr></tbody></table></div>
</figure>
```

### Drawing slices
Use circles with `pathLength="100"`; each slice's dasharray is its share less the gap, and its dashoffset is minus the sum of the shares before it. Rotate the SVG −90° so the first slice starts at twelve.

## Accessibility

### Screen readers
The ring and list are `aria-hidden`; the table holds part, share and amount, and the reading line says the finding.

### Colour
Every share is written in words, so the ring can be read without telling colours apart.

## For agents

### Rules

- **Never** use more than four slices.
- **Must** write every share with its amount beside the ring.
- **Never** use a ring to show progress on creative work.
- **Must** start at twelve o'clock and keep the list in ring order.

### AI readiness test

**Task:** Show interior against exterior pages on the schedule summary.

**Give the agent:** Donut chart, Stripboard strip, Data visualisation.

**Constraint:** Two shares; pages in eighths.

**A reliable answer:**
- Two slices with a gap
- Total pages in the hole
- Shares as % and eighths
- Table switch
