# Progress Indicator System

## Objective

Tell people how far along the work is, in the same way every time.

A consistent set of bars, rings, step trackers, and accompanying text for work that takes measurable time.

## Before You Begin

This feature is being added to an application that already exists and already
works. Do not scaffold a new project, and do not assume a blank slate.

Inspect the codebase first and establish:

- The existing application structure and where code of this kind already lives.
- The framework and version in use.
- The existing design system — colours, spacing, typography, and component conventions.
- Existing UI components you can reuse instead of writing new ones.
- The existing database structure, if this feature needs to persist anything.
- The existing authentication and authorization system, if this feature is user-scoped.
- Dependencies already installed, so you don't add a library that duplicates one.
- The existing test setup and conventions.

Only start writing code once you understand the above. If the application
already implements part of this feature, extend it rather than replacing it.

## Implementation Instructions

1. Identify every operation in the app that takes long enough to need feedback — uploads, imports, exports, batch actions, multi-step flows — and decide for each whether its progress is genuinely measurable.
2. Use a determinate form only when a real proportion is known. Where the total is unknown, use an indeterminate form and say what is happening in words rather than inventing a percentage.
3. Pair every indicator with text that names the operation and its current position, so the information survives for someone who cannot see the graphic.
4. Define paused, failed, and cancelled as first-class endings with their own treatment, and make it clear whether partial work was kept or discarded.
5. Do not conflate this with the pending state of a single button, which is owned by Async Button. That brief covers a request in flight; this one covers work with duration and measurable position.

## UI and UX Requirements

Match the application's existing design system exactly. Reuse its components,
spacing, and typography. This feature should look like it was always there.

## Responsive Requirements

Works on mobile, tablet, and desktop. Touch targets are large enough to hit on a
phone, and nothing overflows horizontally at 320px.

## Accessibility Requirements

- Fully keyboard navigable.
- Correct semantic elements and ARIA roles.
- Visible focus states.
- Meets WCAG AA contrast.
- Dynamic changes are announced to screen readers.
- Respects prefers-reduced-motion.

## Edge Cases

- A determinate bar showing a fabricated percentage is worse than an honest indeterminate one, because it sets an expectation the system cannot meet and stalls visibly at ninety-nine percent.
- Progress must be announced to assistive technology at meaningful intervals only. Announcing every increment floods the screen reader; announcing nothing leaves the user with no idea the work is proceeding.
- Paused, failed, and cancelled each need a distinct end state saying what happened to the work already done. A bar that simply stops moving is indistinguishable from a hung process.
- Work continuing in the background must remain discoverable after the user navigates away, through a persistent indicator they can return to rather than a toast that has already gone.
- Progress that goes backwards, or that jumps to complete without passing through the middle, undermines every subsequent indicator in the app.
- Step trackers must show which steps are done, which is current, and which remain, and must not let a user believe a skipped optional step was completed.
- Users who have asked for reduced motion must still see progress; replace the animation, not the information.

## Testing

Exercise the feature end to end in the running application. Cover every edge case
above, then run the existing test suite and confirm nothing regressed.

## Acceptance Criteria

- [ ] Every operation over the defined duration threshold shows progress feedback.
- [ ] Determinate indicators are used only where a true proportion is known.
- [ ] Each indicator is accompanied by text naming the operation and its position.
- [ ] Paused, failed, and cancelled states are visually distinct and state the fate of partial work.
- [ ] Background work remains discoverable after navigating away from the originating view.
- [ ] Progress is announced at meaningful intervals and remains legible under reduced-motion settings.
- [ ] The feature matches the existing design system.
- [ ] No existing functionality is broken.

## Adaptation Rules

- Match the existing design system. Do not introduce a new colour palette,
  spacing scale, or component library.
- Reuse existing components and utilities wherever they fit.
- Follow the naming, file layout, and code style already present.
- Do not upgrade, replace, or remove existing dependencies to make this
  feature fit. Adapt the feature to the app, not the app to the feature.
- Do not break existing functionality. If a change is genuinely required in
  existing code, make the smallest one that works and say so.
- If something in these instructions conflicts with how the application is
  built, follow the application and explain the deviation.

## Final Verification

Before you report the work as done:

1. Re-read the acceptance criteria above and check each one against what you
   actually built.
2. Run the application and exercise the feature end to end.
3. Run the existing test suite and confirm you have broken nothing.
4. Check the feature on mobile, tablet, and desktop widths.
5. Check keyboard navigation and focus handling.
6. Summarize what changed: files added, files modified, and anything you
   deliberately did differently because of how this application is built.

If any acceptance criterion is unmet, fix it before reporting completion.