Determinate progress — how much of a known total is done. The fill's width is the value and the only thing that moves; the bar itself carries no number, so the count or percentage is host text beside it. If the total is unknown, that is a Spinner, not a bar with invented motion.
The label and the percentage are host text; the bar states proportion only. The width and aria-valuenow are written in the same update — nothing in the component keeps them agreeing.
Height is the only dimension a bar has, so it is the only thing the size axis moves. One sm/md/lg dialect on the spacing scale; the default is medium.
| Example | Size | Modifier | Height | Usage |
|---|---|---|---|---|
| Small | --sm | space.1 | Inside dense rows and cards, under a line of text | |
| Medium | ds-progress | space.1-5 | The default — panels, forms, upload rows | |
| Large | --lg | space.2 | Feature areas where the bar is the subject of the view |
Every value is the same recipe at a different width — there is no empty state, no complete state, and no variant. What changes is the number the host writes into both the width and aria-valuenow.
| Example | Value | Reads as | Usage |
|---|---|---|---|
| 0 | Track only | Started but nothing done yet — still honest, still determinate | |
| 45 | Partial fill | The ordinary case the component is shaped around | |
| 100 | Full track | Done — the host removes the bar or swaps in its result, the bar has no finished look |
A bar says "this much of a known total is done" — and only that.
| Verdict | Rule |
|---|---|
| Do | Set the fill's width and aria-valuenow together in one update — a bar whose width and value disagree lies to one audience or the other. |
| Do | Put the number in host text beside the bar when the value matters; the bar states proportion, not quantity, and never carries copy of its own. |
| Do | Give every bar an accessible name with aria-label or aria-labelledby — progressbar alone does not say what is progressing. |
| Don’t | Use a bar when the total is unknown — that is a Spinner; a value-less bar misreports what the system knows. |
| Don’t | Make a progress bar interactive. A draggable or clickable track is a Slider, with its own contract, states, and keyboard map. |