twbs
Docs: improve progress bar labels markup and explanations for accessibility
Description
Usage of color and background helper classes
In the current Progress > Backgrounds documentation, we say the following:
Alternatively, you can use the new combined color and background helper classes.”
In the same spirit as what we've done in https://github.com/twbs/bootstrap/pull/39214, this PR suggests always using .text-bg-{color} when a label is used within the progress component. If one changes the colors between the light and the dark mode (contrary to Bootstrap), you'd like the text color to adapt automatically in light and dark mode to have sufficient contrast. And it can't be done with .text-dark or other utilities.
The idea here is to:
- keep the examples without labels with
.bg-{color} - change the label examples to use
.text-bg-{color} - modify the documentation explanation to always suggest the use of
.text-bg-{color}
Note: we talked about it internally and @mdo seemed to agree with this option
Long labels
The second part of the current Progress > Labels mentions something to handle the long labels. It's already mentioned that “Be aware though that currently this approach does not take into account color modes.”
However, I don't think there's anything we can provide that will make it work all the time.
Right now, we use .text-dark which obviously doesn’t work in dark mode as mentioned.
Based on my previous proposal, we should rather use .text-bg-primary which works well in dark mode and half-works in light mode (only on the blue color):
The issue here is that we will never find anything that can work for both colors with the actual color palette. It can only work if the color palette is compatible and that .progress and .progress-bar have the same tint. Said differently, that they are both using light colors or dark colors so that the text color has sufficient contrast.
Since we don't know how the color palettes of projects will be built, I suggest that we don't show this example anymore in our documentation but still explain that it's possible, but with a big warning regarding accessibility and contrast ratio, and that we rather recommend most of the time to display the label outside the progress bar.
Note: we talked about it internally and @mdo seemed to agree with this option
Friendly ping for @mdo and @patrickhlauke for wording and double-checking the explanation. We might want to show how to display the label outside of the progress bar and keep it accessible.
Please also note that I haven't changed the Cheatsheet example since the values fit within the progress bar and don't have any contrast ratio issues.
Target version
IMO this is non-breaking for users so it could be embedded directly into the v5.3.x. Thoughts?
Type of changes
- [x] Documentation (non-breaking change)
Checklist
- [x] I have read the contributing guidelines
- [x] My code follows the code style of the project (using
npm run lint) - [x] My change introduces changes to the documentation
- [x] I have updated the documentation accordingly
- (N/A) I have added tests to cover my changes
- [x] All new and existing tests passed
Live previews
- https://deploy-preview-39364--twbs-bootstrap.netlify.app/docs/5.3/components/progress/#labels
- https://deploy-preview-39364--twbs-bootstrap.netlify.app/docs/5.3/components/progress/#backgrounds
- https://deploy-preview-39364--twbs-bootstrap.netlify.app/docs/5.3/examples/cheatsheet/#progress (stays the same)
Adding the v5.4.0 project here too @julien-deramond in case we want to save this for a larger release as opposed to a patch.
@julien-deramond happy to help push this to the end if you need a hand
@julien-deramond happy to help push this to the end if you need a hand
I could definitely use a hand to push this to the end. I haven't forgotten, but my TODO list is a bit out of control right now 😅
I agree with what you mentioned in our discussion on this PR. I tried to explain some edge cases where users know the size of the colored part and the specific wording (e.g., in a resume to show skills, on a website for fixed prices or quotas, etc.), where our label-version could be used. However, your explanation is simpler and fits most cases, while my examples are more edge cases. If you think it's better not to mention them at all, I'll follow your judgment.
I'd love to see your perspective on this PR!
@julien-deramond I'm about to disappear for a weak of vacation, but once I'm back, let's get this over the line. The example might still be useful, but as mentioned I think the callout makes sense as a more general callout for the whole component (not just for edge cases). I'll have a think while I'm at the side of a pool :)