Components › States & feedback › Loading › Progress

Progress

canon

The one canonical progress bar: work that takes minutes — the step in words, an optional number, time left, optional steps; running, done or failed.

Product owner 25 Sep 2026 (FA202): approved as THE one progress bar, 6 px (--sp-2) like .tl-prog instead of the 4 px candidate; the product-extraction bar (.pr-ex) was migrated onto it in acrm !3883, the other scattered bars were inventoried on 26 Sep 2026 (wave B): static ratios moved to Meter (acrm !3898, !3900), .tf-progress/.tf-subs-bar were dead CSS and removed (acrm !3901), .tl-prog in Task list turned out to be dead API and was deleted (acrm !3947). Estimates are written in words ("asi 23 %").

Used in 5 files · 4 areas · 5× — components/mail, components/meetings, components/running, pages/ProduktDetailPage

@acrm/ui <Progress>.acrm-progress .pg-head .pg-label .pg-val +8SourceStory
ExamplesCodeUsageAccessibilityChangelog

The progress of work that takes minutes while the user walks away — a meeting transcript being processed, documents being read, a large upload, a bulk operation. It says in words and in numbers what is running, how much is done, how much is left and, optionally, which steps come before and after. React <Progress> (packages/ui/src/components/Progress.tsx) emits .acrm-progress (apps/web/src/ds/progress.css).

Approved by the product owner on 25 September 2026 (candidate FA202, DS MR !4) as the one canonical progress bar of the app.

When to use

  • A wait long enough that the user leaves the screen — the Loader's own usage sends this case here.
  • Work with a measurable share (parts, bytes, documents) or at least an honest estimate.
  • Work made of named steps the user benefits from seeing (transcript → name correction → minutes).
  • A job that can end in success or failure and must say which, with the reason.

When not to use

  • A short wait — a button, a dialog, an inline save: that is Loader.
  • Loading or paging a long listing: that is List loader.
  • Content of a known shape arriving: that is the skeleton.
  • A static ratio to a limit or a goal (budget drawn, occupancy, KPI, progress to promotion, project done / total): that is Meter (AD 26 Sep 2026 — the same pair as HTML <meter> vs <progress>). Progress is for work that runs now and ends in done or failed.

Anatomy

  • Container .acrm-progress: a grid, gap --sp-2, full width of its host — the host decides the width (360 px in a detail panel, 100 % in a toast).
  • Head .pg-head: the step in words .pg-label (--label, --fg) and, optionally, the number .pg-val (--small, tabular numerals, --fg-secondary).
  • Track .pg-track[role=progressbar]: height --sp-2 (6 px), --radius-pill, background --border. Fill .pg-fill coloured by tone: --accent running · --positive done · --critical failed; width transitions 600 ms.
  • Indeterminate (value unknown, e.g. in a queue): a 30 % segment runs along the track in 1.4 s; no number.
  • Meta .pg-meta (--hint, --fg-secondary): time left, what is happening, or — when failed — the reason in --critical-ink.
  • Steps ol.pg-steps (optional): li.pg-step.is-done green check (--positive-ink) · .is-run canonical Loader at icon size (--accent) · .is-todo circle-dashed (--fg-muted); a detail such as „6 z 15" on the right. Rows use --label (22 px).

Content

  • The label names the step ("Oprava jmen", "Čtu podklady"), never a generic "Zpracovává se".
  • A measured value is written plainly ("61 %"); an estimate in words — "asi 23 %", never a tilde (AD 25 Sep 2026).
  • A value that cannot be honestly expressed as a percentage (a synthetic bar width) is not shown; say "3 z 7 dokumentů" in meta instead.
  • Time left in words: "zbývá asi 7 min".

Best practices

Do
  • Put Progress straight under the section heading — no tinted box, no icon tile around it; the tone of the fill carries the state (RULES §0).
  • End every run in a terminal state: tone="done" with the result, or tone="failed" with the reason in meta.
  • Keep the steps list short and in the order the work happens.
Don’t
  • A second progress bar with its own height or colours — there is one; migrate the old ones onto it.
  • A spinner next to a progress bar — the running step already carries the Loader.
  • A percentage made up to fill the slot.
  • Loader — short waits; also the running-step glyph inside Progress.
  • List loader, Skeleton — loading listings and known shapes.
  • Task list — .tl-prog ratio bar, to be migrated onto Progress.

Source: docs/loading/progress.usage.md · GitLab