> For the complete documentation index, see [llms.txt](https://docs.devlaunchers.org/dl-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.devlaunchers.org/dl-docs/universal-design-system/universal-design-system/components/uds-components/progress.md).

# Progress

Github Tracker

{% embed url="<https://github.com/dev-launchers/dev-launchers-platform/issues/2477>" %}

Figma Reference \
<https://www.figma.com/design/14ySC6RFgp4hxDcHfRbGSO/UDS---in-progress--?node-id=24823-34667&t=ygzvHHtz157q3TAy-4>

## Progress Bar

### Overview:

* The Progress Bar component visually communicates the status of an ongoing operation such as loading, uploading, or file transfers. It reassures users that a process is active and provides visibility into completion progress through percentage indicators and contextual labels.
* Progress bars should be used when a task duration is known and expected to take longer than one second. They provide clear feedback through high-contrast colors, consistent labeling, and determinate states that show measurable progress toward completion.

<br>

## Usage Guidelines

* Use progress bars to inform users that a system action is actively processing and to communicate how much of the task has been completed.

**When to use**

* Operations that take **longer than 1–2 seconds**
* Loading or fetching data
* File uploads or transfers
* Saving or processing system tasks
* Any process where completion percentage can be calculated

**When not to use**

* Very fast operations (under one second)
* Actions that complete instantly without noticeable delay
* Situations where progress cannot be measured or estimated

**Best practices**

* Always include **text labels** to provide context (e.g., *Loading*, *Uploading files*, *Processing request*)
* Display **percentage values** when the completion progress is measurable
* Maintain **high contrast colors** for readability and accessibility
* Avoid **indeterminate states** when the duration is known
* Ensure consistent placement and alignment of labels across layouts

<br>

## Component Properties

style (enum)Options: grey, cta, alert

**Purpose:**\
Controls the visual color treatment of the progress bar.

**Usage:**

* grey → neutral progress state
* cta → emphasized progress using Dev Launchers CTA colors (Cosmic / Nebula)
* alert → communicates status feedback such as warning, success, error, or info

**Context:**\
Styles align with existing **Dev Launchers CTA and alert color tokens** to maintain consistency across the design system.

\ <mark style="color:$danger;">status (enum)</mark>

<mark style="color:$danger;">**Options:**</mark>\ <mark style="color:$danger;">default, warning, success, error, info</mark>

<mark style="color:$danger;">**Purpose:**</mark>\ <mark style="color:$danger;">Represents the semantic meaning of the progress state when using the alert style.</mark>

<mark style="color:$danger;">**Usage:**</mark>

* <mark style="color:$danger;">success → operation completed successfully</mark>
* <mark style="color:$danger;">warning → process requires attention</mark>
* <mark style="color:$danger;">error → operation failed</mark>
* <mark style="color:$danger;">info → informational progress feedback</mark>

<mark style="color:$danger;">**Context:**</mark>\ <mark style="color:$danger;">Helps communicate system state clearly through color and iconography.</mark>

\
progress-value (number)

**Purpose:**\
Defines the completion percentage of the progress bar.

**Usage:**

0–100 → indicates percentage of completion

**Context:**\
Displayed visually through the progress fill and communicated textually through the percentage label.

\ <mark style="color:$danger;">label-text (string)</mark>

<mark style="color:$danger;">**Purpose:**</mark>\ <mark style="color:$danger;">Provides contextual information about the operation being performed.</mark>

<mark style="color:$danger;">**Usage examples:**</mark>

* <mark style="color:$danger;">Loading assets</mark>
* <mark style="color:$danger;">Uploading files</mark>
* <mark style="color:$danger;">Processing request</mark>

<mark style="color:$danger;">Context:</mark>\ <mark style="color:$danger;">Helps users understand what task the progress bar represents.</mark>

\ <mark style="color:red;">breakpoint (enum)</mark>

<mark style="color:red;">**Options:**</mark>\ <mark style="color:red;">mobile-tablet, desktop-laptop</mark>

<mark style="color:red;">**Purpose:**</mark>\ <mark style="color:red;">Controls layout responsiveness.</mark>

<mark style="color:red;">**Usage:**</mark>

<mark style="color:red;">mobile-tablet → optimized for smaller screens</mark>\ <mark style="color:red;">desktop-laptop → optimized for larger layouts</mark>

<mark style="color:red;">**Context:**</mark>\ <mark style="color:red;">Automatically adapts when placed into responsive breakpoints.</mark>

<br>

## Appearance Modes

The Progress Bar supports the following variable **collections:**

style

**Semantic color variations:**

* grey → neutral default state
* cta → emphasized progress using Dev Launchers CTA palette (Cosmic / Nebula)
* alert → status-driven feedback colors

**Alert substyles include:**

* warning
* success
* error
* info

These styles allow the component to support multiple use cases while maintaining consistency with **Dev Launchers design tokens and system alerts**.

**breakpoint**

Layout responsiveness for different screen sizes:

* mobile / tablet → optimized spacing and scaling for smaller devices
* desktop / laptop → standard layout for larger screens

The component automatically adjusts when placed into responsive design breakpoints.

<br>

## Label Placement

Progress labels follow consistent alignment rules for clarity and readability.

Labels are placed **to the right of the progress bar**, with:

* Top label → contextual text description
* Bottom label → percentage value

Labels are intentionally **not placed inside the progress bar** to maintain maximum readability and avoid contrast issues as progress fill changes.

Consistent right alignment prevents visual confusion and keeps information predictable across layouts.

<br>

## Nested Components

The Progress Bar contains several nested elements:

**Text Label Component**\
Provides contextual information about the operation.

**Percentage Text Component**\
Displays the completion value (e.g., 45%).

**Circle Check Icon**\
Appears in completion states such as success to reinforce visual confirmation.

<br>

## Accessibility Considerations ♿

Labeling All progress bars include descriptive labels to communicate state changes such as:

* Loading
* Error
* Complete

These labels provide context for assistive technologies.Screen Reader Support

Progress values should be announced using ARIA attributes.

Recommended implementation:

```
role="progressbar"
aria-valuemin="0"
aria-valuemax="100"
aria-valuenow="progress value"
aria-label="Loading progress"
```

This ensures screen readers correctly communicate progress updates.Contrast

All styles maintain **WCAG AA compliant contrast ratios** to ensure readability across themes and backgrounds.

**State Communication**

Color should not be the only indicator of status. Icons and labels should reinforce meaning.

<br>

## Developer Notes

This component is **non-interactive** and should only communicate system status.

Implementation guidelines

**Progress bars should:**

Be updated dynamically through application state\
Reflect accurate completion percentages\
Update text labels alongside percentage values

Responsive behavior

When placed into layout breakpoints, the progress bar automatically adjusts to:

* Mobile / Tablet layouts
* Desktop / Laptop layouts

Spacing and alignment follow system tokens for consistency across screen sizes.

<br>

## Unsupported Behaviors

The Progress Bar component is **not designed to be interactive**.

Users should not:

* Click
* Drag
* Adjust
* Manipulate progress values manually

Progress updates must be controlled entirely by the system or application state.

<br>

## Deferred Enhancements

The following enhancements are planned for future iterations:

**Predictive timing**

Interactive labels displaying estimated time remaining.

**Behavioral optimization**

Data-driven progress behavior that adapts to real usage patterns.

**Segmented progress states**

Multi-stage progress indicators such as:

* Draft
* Review
* Approved

**Adaptive animation**

Progress animations that move faster during early stages and slow as they approach completion to create perceived responsiveness.

<br>

## Known Issues

No known issues.

<br>

## Reference Links

WCAG 2.1 – Progress Indicator Accessibility\
ARIA Authoring Practices – Progressbar Pattern\
Dev Launchers Design Tokens (Color, Spacing, Radius)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.devlaunchers.org/dl-docs/universal-design-system/universal-design-system/components/uds-components/progress.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.