Skip to content
Cloaked Design SystemStatus

Progress

A determinate progress family in three shapes: a linear Bar, a segmented Steps counter, and a circular Ring.

Implementation preview
COMPLETE STORYBOOK REFERENCE

Every example. In one place.

Explore every named example, including states, compositions, and theme variants.

10 stories
SELECTED EXAMPLE

Bar

Open controls
Bar selectedOpen canvas
Example sourcepackages/design-system/src/components/status/Progress/Progress.stories.tsxExport Bar

Implementation preview Local Storybook build 0.2.0-preview.1. Source specification status does not approve this runtime.

Stories + source JSON ↗

Local specification source status: preview. Implementation preview pending sign-off.

A determinate progress family in three shapes: a linear Bar, a segmented Steps counter, and a circular Ring.

Design-owned component contract ↗Version 0.2.0-preview.1 · Implementation preview pending sign-off
Implementation API 3 entry points · source-derived preview

Read the actual callable API and preserve its composition constraints. Each union branch is a complete alternative; props marked forbidden cannot be supplied.

import { Progress } from '@cloakedinc/design-system';
Progress.BarProgressBarProps

packages/design-system/src/components/status/Progress/ProgressBar/ProgressBar.tsx:13

PropTypePresenceNotes
valuenumberRequiredProgress value from 0 to 100.
sizeProgressSize | undefinedOptionalNamed size for the track height. Defaults to `sm` for the compact existing treatment.Source default: 'sm'
pulsingboolean | undefinedOptionalPulses the fill to signal an active/indeterminate state.Source default: false
labelReactNodeOptionalOptional caption shown above the bar.
valueLabelReactNodeOptionalExplicit visible value shown opposite the label.
showValueboolean | undefinedOptionalShows a rounded percentage value when `valueLabel` is not provided.Source default: false
ariaLabelstring | undefinedOptionalAccessible name for the value; omit when the bar is purely decorative.
testIdstring | undefinedOptionalOptional test selector. Lands on the track itself, not the label group.
Progress.StepsProgressStepsProps

packages/design-system/src/components/status/Progress/ProgressSteps/ProgressSteps.tsx:14

PropTypePresenceNotes
totalnumberRequiredStep count; truncated to a whole number and clamped to 1-12.
completednumberRequiredSteps finished so far; clamped to `0..total`.
sizeProgressSize | undefinedOptionalNamed marker size. Defaults to `sm` for the compact existing treatment.Source default: 'sm'
showActiveStepboolean | undefinedOptionalMarks the next incomplete step as active.Source default: false
labelReactNodeOptionalOptional caption shown above the steps.
valueLabelReactNodeOptionalExplicit visible value shown opposite the label.
showValueboolean | undefinedOptionalShows a compact completed/total value when `valueLabel` is not provided.Source default: false
showStepNumbersboolean | undefinedOptionalRenders step numbers inside each marker.Source default: false
stepLabelsreadonly ReactNode[] | undefinedOptionalOptional compact labels shown beneath each step marker.
ariaLabelstring | undefinedOptionalAccessible name for the value; omit when the markers are purely decorative.
testIdstring | undefinedOptionalOptional test selector. Lands on the step row itself, not the label group.
Progress.RingProgressRingProps

packages/design-system/src/components/status/Progress/ProgressRing/ProgressRing.tsx:13

PropTypePresenceNotes
valuenumber | undefinedOptionalProgress value from 0 to 100.Source default: 0
sizeProgressSize | undefinedOptionalNamed ring size. Defaults to `sm` for the compact existing treatment.Source default: 'sm'
labelReactNodeOptionalOptional caption shown beneath the ring.
valueLabelReactNodeOptionalExplicit visible value shown inside the ring.
showValueboolean | undefinedOptionalShows a rounded percentage value inside the ring when `valueLabel` is not provided.Source default: false
ariaLabelstring | undefinedOptionalAccessible name for the value; omit when the ring is purely decorative.
testIdstring | undefinedOptionalOptional test selector. Lands on the ring itself, not the label group.

Only explicit destructured parameter initializers are extracted. Other runtime defaults remain in implementation source.

Complete contract · JSON ↗Guidance and source · Markdown ↗

Overview

Determinate progress in three shapes chosen by context. All three take a 0-100 value (Progress.Steps derives it from completed / total).

Use when

Pick the shape by how the progress reads in place, not by preference.

Progress.Bar and Progress.Ring are both in use today; Progress.Steps is available but currently unused in the app.

Steps

Progress.Steps marks completed, active, and upcoming stages. Add showStepNumbers for numbered markers and stepLabels for per-step captions.

Size and pulsing

size is sm (default, compact), md, or lg and is shared by all three shapes; reach for lg to emphasize progress on a standalone screen. pulsing (Bar) animates the fill to signal an active operation.

Props

Controls below are for Progress.Bar; Progress.Steps and Progress.Ring expose their own args in the Steps and Ring stories above.

Usage by variant

ChoiceUse whenAvoid when
Shape: Progress.BarA value along a known scale that fills as work completes — a percentage on a screen or row.
Shape: Progress.StepsA small, fixed count of discrete stages — a setup wizard or onboarding flow.Stages that each carry a title, description, or timestamp — use Timeline, which shows event detail.
Shape: Progress.RingThe same 0-100 value in a compact circular badge for cards and tight corners.

Component specification

$schema../../../specs/component-spec.schema.json
Parts
Id
bar
Label
Progress.Bar
Description
Linear track that fills from 0 to 100.
Required
true
Id
steps
Label
Progress.Steps
Description
Segmented markers for a small fixed count of stages.
Id
ring
Label
Progress.Ring
Description
Circular badge form for cards and tight corners.
Allowed Design Choices
Variants
Bar
Label
Bar
Description
Linear determinate track.
Steps
Label
Steps
Description
Discrete stage markers.
Ring
Label
Ring
Description
Compact circular badge.
Sizes
Sm
Label
Small
Description
Compact default track, marker, and ring.
Md
Label
Medium
Description
Mid-scale track, marker, and ring.
Lg
Label
Large
Description
Emphasis track, marker, and ring.
Variants
Id
bar
Label
Bar
Description
Linear determinate progress.
Platforms
  • ios
  • android
  • web
Id
steps
Label
Steps
Description
Segmented stage progress.
Platforms
  • ios
  • android
  • web
Id
ring
Label
Ring
Description
Circular determinate progress.
Platforms
  • ios
  • android
  • web
Sizes
Id
sm
Label
Small
Description
The compact existing treatment.
Id
md
Label
Medium
Description
A mid-scale treatment.
Id
lg
Label
Large
Description
An emphasis treatment for standalone screens.
Measurements
Id
bar-track-height-sm
Label
Bar track height (small)
Kind
exact
Token
--cds-size-4
Value
4
Unit
px
Applies To
  • bar
Id
bar-track-height-md
Label
Bar track height (medium)
Kind
exact
Token
--cds-size-8
Value
8
Unit
px
Applies To
  • bar
Id
bar-track-height-lg
Label
Bar track height (large)
Kind
exact
Token
--cds-size-12
Value
12
Unit
px
Applies To
  • bar
Id
ring-diameter-sm
Label
Ring diameter (small)
Kind
exact
Token
--cds-size-32
Value
32
Unit
px
Applies To
  • ring
Id
ring-diameter-md
Label
Ring diameter (medium)
Kind
exact
Token
--cds-size-48
Value
48
Unit
px
Applies To
  • ring
Id
ring-diameter-lg
Label
Ring diameter (large)
Kind
exact
Token
--cds-size-64
Value
64
Unit
px
Applies To
  • ring
Id
group-gap
Label
Label and track gap
Kind
exact
Token
--cds-space-8
Value
8
Unit
px
Applies To
  • bar
  • steps
  • ring
Id
step-dot-size-sm
Label
Step dot size (small)
Kind
exact
Token
--cds-size-8
Value
8
Unit
px
Applies To
  • steps
Id
step-dot-size-md
Label
Step dot size (medium)
Kind
exact
Token
--cds-size-12
Value
12
Unit
px
Applies To
  • steps
Id
step-dot-size-lg
Label
Step dot size (large)
Kind
exact
Token
--cds-size-16
Value
16
Unit
px
Applies To
  • steps
Layout
Alignment
An optional label and value sit above the bar/steps; the ring centers its value.
Flow
Each shape is self-contained; Bar and Steps fill their container width while Ring is inline.
Notes
  • Use Timeline when each stage carries its own title, description, and timestamp.
Typography And Color
Typography
Label
Caption and value
Description
Labels and values use the body-small ramp.
Token
--cds-type-body-small-size
Colors
Label
Fill
Description
Completed progress uses the brand accent.
Token
--cds-brand
Label
Track
Description
The unfilled track uses the graph background.
Token
--cds-graph-bg
States
Id
determinate
Label
Determinate
Description
Fill reflects the current 0 to 100 value.
Id
pulsing
Label
Pulsing
Description
The bar fill pulses to signal an active or indeterminate operation.
Id
complete
Label
Complete
Description
All steps or full value are filled with the brand accent.
Behavior
Label
Shape choice
Description
Pick Bar for a scale, Steps for a small fixed count of stages, and Ring for a compact badge.
Label
Value clamping
Description
Values are clamped to the 0 to 100 range before rendering.
Accessibility
Label
Meaningful progress
Description
Set ariaLabel to expose role=progressbar with min, max, and current value.
Label
Decorative progress
Description
Omit ariaLabel to hide purely decorative progress from assistive tech.
Content Adaptation
Label
Optional value
Description
showValue renders a rounded percentage or completed/total count opposite the label.
Label
Step labels
Description
Steps can render numbers inside markers and captions beneath them.
Motion Haptics
Motion
Label
Fill transition
Description
The bar fill eases to its new width; the pulsing fill animates until it settles.
Haptics
Label
No feedback
Description
Progress is non-interactive and requests no haptics.
Platform DifferencesNone specified
Implementation preview

This design-owned implementation is ready to try and review. It does not establish product approval. Imported specifications retain their original review status.

Inspect version 0.2.0-preview.1