components / progress

Progress

Linear progress meter with tone-aware fill, readable labels, and restrained motion.

Overview

What it is

This section explains the intent of the component before the implementation details.

  • Progress communicates ongoing completion without becoming an interactive control.
  • Use it when a task, upload, or workflow has a measurable fraction complete.

Aliases

progress bar

Decision guide

How to choose it

Use these notes to decide quickly whether this is the right DK component for the job.

Decision guide

  • Choose Progress when the interaction should feel deliberate, documented, and reusable across product surfaces.
  • If the scenario is more specialized than the current Progress contract, prefer a simpler component or build a dedicated workflow on top of the lower-level DK primitives.

Do

  • Keep the Progress label, value, or status language direct enough to scan quickly.
  • Use the documented size and state recipes instead of inventing one-off variants in product code.

Do not

  • Do not hide the main purpose of Progress behind decorative copy or overloaded surface treatments.
  • Do not stretch Progress into a workflow it was not designed to handle just because the visuals are close.

Usage

When to use

Prefer these situations when choosing this component.

  • Use Progress for determinate work with a meaningful numeric or percentage state.
  • Use the label to clarify what is moving, not just how much.

Usage

When not to use

These patterns are better served by a different component or a simpler surface.

  • Do not use Progress for binary status; use Badge or Alert instead.
  • Do not use it when no reliable progress value exists; use a quieter loading treatment.

Anti-patterns

  • Using Progress as a generic layout container instead of a purpose-built interaction or content surface.
  • Forking the documented recipe in product code instead of extending the shared DK contract.

Migration notes

  • Migrate legacy progress usage by mapping existing variants and states onto the documented DK props before porting any custom styling.
  • Treat the docs examples as the reference contract for accessibility and event behavior during adoption.

Anatomy

Structural parts

The anatomy explains which pieces matter to the recipe and accessibility model.

meter shell

root

Wraps label, track, and fill.

progress label

label

Names the work being measured.

background track

track

Shows the full extent of the work.

current value

fill

Represents the completed portion of the work.

API

Public interface

The docs contract distinguishes props, DOM events, and slots so integration behavior is explicit.

Props

NameTypeDefaultDescription
tone'brand' | 'success' | 'warning''brand'Chooses the semantic fill treatment.
size'sm' | 'md''md'Chooses the compiled size recipe for the component.
valuenumber—Current determinate progress value from 0 to 100.
labelstring—Visible description of the in-progress work.
themeThemeContract—Overrides the compiled DK theme used to resolve tokens and recipes for this component.

Slots

NameDescription
defaultOptional inline label content override.

Recipes

Variants, sizes, and states

These notes summarize the intended recipe surface rather than exposing raw implementation detail first.

Variants

  • brand: General-purpose progress.
  • success: Positive completion context.
  • warning: Cautious progress where the work carries risk.

Sizes

  • sm: Compact inline progress.
  • md: Default reading size for most surfaces.

States

  • rest: Current measured value.
  • complete: Work has reached the end state.

Accessibility

Accessibility contract

This is the behavior the component promises to assistive tech and keyboard users today.

Semantics

  • Exposes progress semantics through the meter structure and visible label.

Keyboard

  • No custom keyboard model because the meter is not interactive.

Screen readers

  • Label and current value should be understandable without relying on color.

Checklist

  • Verify the visible label or title still produces a clear accessible name.
  • Verify focus remains obvious in every supported state and size.
  • Verify disabled, selected, and error states do not rely on color alone.

Implementation

Tokens and slot vars

This section shows the representative compiled slot variables that the runtime consumes for the selected design system.

root

--dk-progress-gap
clamp(0.75rem, 0.6875rem + 0.278vw, 0.938rem)

header

--dk-progress-header-gap
clamp(1.333rem, 1.2222rem + 0.494vw, 1.667rem)

label

--dk-progress-label-color
#16181c
--dk-progress-label-size
clamp(1.333rem, 1.2222rem + 0.494vw, 1.667rem)
--dk-progress-label-weight
650

value

--dk-progress-value-color
#16181c
--dk-progress-value-size
clamp(0.75rem, 0.6875rem + 0.278vw, 0.938rem)

track

--dk-progress-track-bg
#e5e8ed
--dk-progress-track-radius
999px
--dk-progress-track-block-size
12px

indicator

--dk-progress-indicator-bg
#2072e4
--dk-progress-indicator-radius
999px

Implementation notes

  • Progress is deliberately determinate in this first-party contract; ambiguous loading should use quieter placeholder patterns.

Implementation checklist

  • Use the public component API first and only drop to lower-level primitives when the component contract genuinely does not fit.
  • Keep theme overrides token-driven so proofs and recipes stay meaningful.
  • Verify the shipped examples and proof fixtures still represent the real product scenario you are implementing.

Examples

Copy-paste examples

Each example is intentionally practical, grouped by starter, common pattern, and edge-case coverage.

Examples
3
Depth
baseline

Starter

1 example

starter

Starter: migration progress

A default progress meter with one label and determinate value.

Copy snippet

<Progress tone="brand" value={68} label="Migration progress" />

Common patterns

1 example

common

Common: task nearly done

Use success tone when the work is finishing positively.

Copy snippet

<Progress tone="success" value={92} label="Import complete" />

Edge cases

1 example

edge

Edge: risky workflow

Use warning only when the work itself is cautionary, not just because it is slow.

Copy snippet

<Progress tone="warning" value={40} label="Reindexing critical data" />

Verification

Curated proof fixtures

Proofs stay visible in the docs so the system shows what it can guarantee, not just what it can render.

brand-md

pass

size=md|tone=brand

  • Contrast: 98.5 Lc
  • Layout: 0 / 180, 280, 360

success-sm

pass

size=sm|tone=success

  • Contrast: 98.5 Lc
  • Layout: 0 / 180, 280, 360

danger-md

pass

size=md|tone=danger

  • Contrast: 98.5 Lc
  • Layout: 0 / 180, 280, 360