[ciampo]

Part of #65528

See #83779 for the separate WPDS token update to the existing @wordpress/components ProgressBar.

What?

Add a compound Progress component to @wordpress/ui, with Root, Track, Indicator, Label, and Value parts. The track keeps the existing ProgressBar's 1.5px height. The existing @wordpress/components component remains supported.

Why?

Provide a design-system progress indicator with accessible labeling and formatted values. Start with neutral colors and allow a custom indicator color override.

How?

Wrap Base UI Progress with WPDS tokens and CSS Modules. Progress.Indicator uses neutral colors by default and supports a color override that accepts CSS colors, including HSL, CSS variables, and currentColor. The track retains its neutral WPDS color. Support determinate and indeterminate progress, custom ranges, composition through render, and ref forwarding.

Mark the component as use-with-caution, following the existing package guidance for components that are not yet recommended. Add Storybook usage guidelines for task progress, labeling, values, and custom colors.

Tone support

The MVP starts without a tone prop and uses neutral colors by default. Brand tone was discussed and removed for now. We can reconsider it if there is substantial demand and pushback against using neutral alone. Other tones, such as warning, error, or progress, could be considered in a follow-up. Their meaning and use for different warning levels need careful design consideration.

Testing Instructions

1. Open Components → @wordpress-ui → Progress → Usage Guidelines, then Default in this PR's Storybook. Confirm the neutral indicator and track colors, with a 1.5px track height.
2. Change value and color in Controls. Open Indeterminate to check progress with an unknown value. Bar Only should render without visible text.
3. Open Custom Value Format. Confirm that 3 of 10 images uploaded appears as both the visible value and the accessible value text.
4. Open Custom Color and Current Color. Try an HSL color in the color control. Only the filled indicator should change. Clear color to restore the neutral indicator color. currentColor should inherit the surrounding text color.
5. Check dark and custom themes, RTL, and WordPress global CSS with the toolbar. The bar should fill from the inline start and stay 1.5px tall. With reduced motion, indeterminate movement should become slower and stepped. In forced colors, the track and indicator should remain visible.

Testing Instructions for Keyboard

The progress bar is informational and does not add a Tab stop. With a screen reader, confirm the task name and current value. Indeterminate progress must not expose a numeric current value.

Screenshot

Use of AI Tools

Codex i/ Sol 6.1

[github-actions]

🤖 PR meta 🤖

🎉 Props

If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message.

Co-authored-by: ciampo <mciampini@git.wordpress.org>
Co-authored-by: simison <simison@git.wordpress.org>
Co-authored-by: jameskoster <jameskoster@git.wordpress.org>

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

Updated as activity occurs, without notifying anyone named here. Add the props-bot label to refresh.

📦 Bundle size

Size Change: +155 B (0%)

Total Size: 8.25 MB

📦 View Changed

Filename	Size	Change
build/scripts/block-editor/index.min.js	516 kB	+101 B (+0.02%)
build/scripts/theme/index.min.js	27 kB	+6 B (+0.02%)
build/styles/theme/design-tokens-rtl.css	3.17 kB	+20 B (+0.63%)
build/styles/theme/design-tokens-rtl.min.css	1.52 kB	+4 B (+0.26%)
build/styles/theme/design-tokens.css	3.17 kB	+20 B (+0.63%)
build/styles/theme/design-tokens.min.css	1.52 kB	+4 B (+0.26%)

_{2db579d Run}

⚡ Performance

Show the results

Client side metrics exclude the server response time.

front-end-block-theme

Metric	46913f4	trunk	% Change
timeToFirstByte	55.9 ms +11.27% -2.42%	56.45 ms +14.79% -3.54%	-0.97%
largestContentfulPaint	92 ms +8.7% -4.35%	96 ms +4.17% -8.33%	-4.17%
lcpMinusTtfb	34.1 ms +20.97% -1.76%	34.6 ms +20.38% -3.9%	-1.45%
wpBeforeTemplate	27.93 ms +16.65% -2.94%	27.72 ms +19.73% -1.84%	0.76%
wpTemplate	23.78 ms +4.33% -1.64%	24.07 ms +7.1% -2.99%	-1.2%
wpTotal	52.38 ms +10.84% -2.46%	52.72 ms +13.69% -3.22%	-0.64%
wpMemoryUsage	7.63 MB +0% -0%	7.59 MB +0% -0%	0.46%
wpDbQueries	17 +0% -0%	17 +0% -0%	0%

front-end-classic-theme

Metric	46913f4	trunk	% Change
timeToFirstByte	46.25 ms +5.41% -0.86%	46.9 ms +6.93% -0.96%	-1.39%
largestContentfulPaint	100 ms +6% -0%	100 ms +4% -0%	0%
lcpMinusTtfb	54.15 ms +1.66% -1.02%	53.1 ms +0.85% -4.33%	1.98%
wpBeforeTemplate	25.89 ms +1.74% -0.58%	26.17 ms +8.6% -1.07%	-1.07%
wpTemplate	17.53 ms +3.48% -0.97%	17.73 ms +1.86% -1.35%	-1.13%
wpTotal	43.46 ms +5.71% -0.94%	43.79 ms +7.58% -0.46%	-0.75%
wpMemoryUsage	6.25 MB +0% -0%	6.21 MB +0% -0%	0.71%
wpDbQueries	14 +0% -0%	14 +0% -0%	0%

media-processing

Metric	46913f4	trunk	% Change
mediaProcessingJpeg	391.33 ms +0.56% -0.78%	398.4 ms +0.16% -1.31%	-1.77%
mediaProcessingAvif	5997.53 ms +0.01% -0.21%	6058.13 ms +0.15% -0.3%	-1%
mediaProcessingJpegToAvif	4136.59 ms +0.12% -0.1%	4159.19 ms +0.31% -0.02%	-0.54%

media-upload

Metric	46913f4	trunk	% Change
jpegUploadProcessing	1463.76 ms +31.31% -4.12%	1404.68 ms +0.35% -1.03%	4.21%
pngUploadProcessing	170.71 ms +31.34% -2.24%	176.78 ms +20.39% -5.48%	-3.43%
largeJpegUploadProcessing	1405.13 ms +1.46% -0.56%	1403.91 ms +0.85% -0.55%	0.09%
multipleImageUploadProcessing	1526.47 ms +1.15% -0.67%	1556.73 ms +7.99% -0.64%	-1.94%

post-editor

Metric	46913f4	trunk	% Change
serverResponse	324.85 ms +6.15% -6.85%	314.73 ms +6.36% -6.89%	3.22%
firstPaint	186.2 ms +15.34% -11.94%	140.81 ms +7.69% -9.52%	32.23%
domContentLoaded	853.58 ms +2.24% -0.65%	834.21 ms +0.65% -1.58%	2.32%
loaded	854.6 ms +2.26% -0.66%	835.23 ms +0.63% -1.58%	2.32%
firstContentfulPaint	358.19 ms +2.67% -0.84%	343.47 ms +1.53% -8.11%	4.29%
firstBlock	2491.79 ms +1.48% -0.79%	2422.54 ms +0.47% -0.74%	2.86%
type	16.12 ms +9.93% -4.22%	15.96 ms +3.7% -2.19%	1%
typeWithoutInspector	17.07 ms +0.88% -4.04%	14.79 ms +3.38% -3.04%	15.42%
typeWithTopToolbar	22.28 ms +12.57% -11.76%	19.45 ms +7.3% -4.27%	14.55%
typeContainer	7.03 ms +6.54% -4.98%	6.94 ms +12.39% -7.93%	1.3%
focus	57.14 ms +15.7% -5.48%	57.33 ms +7.66% -6.99%	-0.33%
firstFocus	169.1 ms +0% -0%	163.84 ms +0% -0%	3.21%
selectAll	412.94 ms +1.31% -6.07%	413.44 ms +3.79% -2.02%	-0.12%
listViewOpen	49.04 ms +10.38% -9.42%	50.8 ms +12.17% -4.86%	-3.46%
inserterOpen	19.53 ms +5.79% -6.96%	17.69 ms +13.91% -5.03%	10.4%
inserterHover	1.74 ms +16.67% -6.9%	1.86 ms +4.84% -8.06%	-6.45%
inserterSearch	6.93 ms +5.05% -6.49%	6.39 ms +15.49% -1.72%	8.45%
loadPatterns	527.03 ms +3.54% -5.73%	510.45 ms +5.89% -3.67%	3.25%
wpTotal	315.39 ms +6.48% -6.88%	305.9 ms +6.56% -7.15%	3.1%
wpMemoryUsage	13.18 MB +0% -0%	13.14 MB +0% -0%	0.28%
wpDbQueries	54 +0% -0%	54 +0% -0%	0%

site-editor

Metric	46913f4	trunk	% Change
serverResponse	401.56 ms +6.95% -5.06%	390.03 ms +4.43% -1.16%	2.96%
firstPaint	233.31 ms +15.04% -8.25%	256.57 ms +21.71% -11.2%	-9.07%
domContentLoaded	1150.04 ms +1.76% -1.03%	1133.95 ms +1.47% -0.96%	1.42%
loaded	1151.21 ms +1.84% -1.01%	1135.19 ms +1.46% -0.96%	1.41%
firstContentfulPaint	468.16 ms +4.23% -1.86%	459.3 ms +1.97% -0.5%	1.93%
firstBlock	4118.88 ms +0.95% -2.21%	4047.33 ms +2.41% -1.08%	1.77%
type	20.15 ms +6% -1.84%	19.53 ms +3.23% -2.76%	3.17%
navigate	134.38 ms +1.92% -10.34%	110.94 ms +11.69% -2.47%	21.13%
loadPatterns	1338.5 ms +8.39% -8.94%	1456.61 ms +2.65% -6.13%	-8.11%
loadPages	1099.71 ms +0.85% -0.63%	1143.18 ms +3.89% -4.36%	-3.8%
wpTotal	390.43 ms +7.14% -5.21%	379.2 ms +4.48% -1.14%	2.96%
wpMemoryUsage	12.14 MB +0% -0%	12.10 MB +0% -0%	0.3%
wpDbQueries	43 +2.33% -0%	43 +2.33% -0%	0%

_{2db579d Run}

[simison]

Worth marking @wordpress/components version as "not recommended" at the same time? Similar to Spinner:

[ciampo]

Update:

I changed the API shape from monolithic to compound, mostly to mimic Base UI's shape and take advantage of the Label subcomponent which automatically and semantically labels the progress bar.

I'm also going to add a dedicated --wpds-color-background-thumb-neutral WPDS token.

Worth marking @wordpress/components version as "not recommended" at the same time? Similar to Spinner:

I'd personally do it in a separate PR, after refactoring current usage to the ui component. But no strong feelings

[simison]

Thoughts on adding max, which is already supported by Base UI and is also part of the official HTML API? More for completeness sake and being simple, than being a priority feature otherwise.

It would support counter-based progress ("100/1600 subscribers imported") versus %-based.

[ciampo]

Update:

• added dedicated WPDS tokens for the brand thumb background color
• removed size (we'll add it later only if necessary)

@simison the max prop should already be supported, can you double-check? There is a dedicated "Custom range" Storybook example about it

[simison]

Gave the component a test in the canvas loader; looks good!

• Canvas loader: Use Progress from @wordpress/ui #83860

[simison]

Tested in Gutenberg and storybook, this is looking good 👍

[jameskoster]

Do we definitely need to support different tones? If so should we include guidance about when to use them?

[ciampo]

Happy to remove from initial implementation if we're not sure about it. I was under the impression that consumers needed it

[ciampo]

Back to only neutral, no tone prop. Added a section in the PR description about it

[ciampo]

cc @WordPress/gutenberg-design

Flagging that we're setting a hardcoded 1.5px value for the height;

If this is meant to be indeeed 1.5px, should we use the focus ring width token (even if it wouldn't be applied for a focus ring)?

Alternatively, we should consider just making it 2px and use the dedicated WPDS token.

I'll merge this PR as-is, we can make changes in a follow-up