Progress bar

Problem Context

• The operation has a known total such as file bytes, records, items, stages, or server-reported completion percentage.
• Users may need to keep working, cancel, retry, move the job to background, or decide whether a wait is acceptable.
• The product must distinguish client transfer, server processing, scanning, validation, commit, and final acceptance.
• Progress may be local, remote, batched, queued, or multi-stage, and each stage may expose different measurement quality.

Selection Rules

• Choose progress bar when the system can report a meaningful value toward a bounded operation.
• Use percent when the total is stable and the value maps cleanly to 0 through 100.
• Use count helper text such as 840 of 1200 rows when counts are more useful than a bare percent.
• Use byte helper text for upload, download, or file transfer when users recognize the file size.
• Use stage text such as Uploading, Scanning, Processing, or Finalizing when one visible bar spans multiple system phases.
• Use loading spinner when the operation is active but progress cannot yet be detected and the expected wait is short.
• Use loading skeleton when users are waiting for predictable content layout rather than monitoring an operation.
• Use step navigation when people move through task milestones and completion depends on user action or validation.
• Use error state when the operation has failed, timed out, or cannot continue from the current value.
• Do not use a progress bar when values are guessed, decorative, manually advanced by user steps, or likely to move backward during one operation.

Required States

• Idle state before the operation starts.
• Active determinate state with label, value, and helper text.
• Indeterminate handoff state only while measurement is not yet available.
• Paused or waiting state when the system needs network, permission, queue, or user action.
• Cancelled state that explains what was stopped and what data remains.
• Success state after the operation is truly complete, including server acceptance when relevant.
• Error state with retained value, reason, retry, cancel, support, or report actions.
• Background state for long work that continues after the current surface is closed.

Interaction Contract

• The progress bar appears only after the operation starts and is scoped to the affected file, job, card, dialog, or page region.
• The label identifies the operation and affected object, such as Uploading evidence.zip or Validating 1200 rows.
• The value advances monotonically during one operation unless a new operation clearly starts with a new label or reset explanation.
• The bar does not reach 100% until the user-facing operation is actually complete, including server-side processing when that matters.
• Cancel, retry, pause, resume, or move-to-background actions are available when the operation duration or risk justifies them.
• Unrelated work remains available unless the entire surface depends on the operation.
• Assistive technology receives an accessible name, current value, min/max, useful value text when percent is insufficient, and a resolved or failed state.

Implementation Checklist

• Define the measurable unit, total, stages, ownership of truth, update frequency, timeout threshold, cancellation policy, retry behavior, background behavior, and terminal states before rendering the bar.
• Use native progress where practical or recreate progressbar semantics with accessible name, minimum, maximum, current value, and useful value text.
• Keep label, bar, helper text, status, and actions visually grouped and programmatically related to the affected region.
• Throttle announcements so assistive technology users are not interrupted on every small percentage change.
• Keep progress monotonic within a single operation and explain any reset as a new attempt, resumed job, or new stage.
• Separate upload transfer, server processing, scanning, validation, and final acceptance when 100% transfer is not the same as done.
• Show success, error, cancelled, paused, or background states after progress stops instead of leaving an active bar on screen.
• Test slow network, failed network, retry, page refresh, background job return, multiple simultaneous jobs, reduced motion, and screen reader value announcements.

Common Generated-UI Mistakes

• Fabricating progress values just to make users feel movement.
• Letting a bar reach 100% before server processing, virus scanning, validation, or commit is done.
• Using one page-level bar for several unrelated operations.
• Resetting a bar backward without explaining that a new attempt or stage began.
• Hiding the label or placing it far away from the bar.
• Using a progress bar for user journey steps rather than system operation progress.
• Leaving the bar active after failure instead of showing recovery.

Critique Questions

• What exact operation owns this bar, and what unit is being measured?
• Can the backend or client honestly report the value, or is the bar pretending?
• What does 100% mean: transfer finished, processing finished, scan passed, data committed, or user-visible result ready?
• What should users do if the bar stalls, fails, or takes longer than expected?
• Does the bar belong to the smallest affected region, and can unrelated work continue?
• How will screen reader users hear the label, value, and terminal state without excessive announcements?