Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Docs: improve progress bar labels markup and explanations for accessibility #39364

Open
wants to merge 4 commits into
base: main
Choose a base branch
from
Open

Docs: improve progress bar labels markup and explanations for accessibility #39364

Changes from 1 commit
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
3a745aa
Docs: improve progress bar labels markup and explanations for accessi…
julien-deramond Nov 3, 2023
efd2ac3
Merge branch 'main' into main-jd-color-modes-progress-bars
patrickhlauke Nov 15, 2023
90e449b
Merge branch 'main' into main-jd-color-modes-progress-bars
mdo Jan 11, 2024
ec0f3b7
Merge branch 'main' into main-jd-color-modes-progress-bars
patrickhlauke May 24, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
32 changes: 13 additions & 19 deletions site/content/docs/5.3/components/progress.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -75,13 +75,15 @@ Add labels to your progress bars by placing text within the `.progress-bar`.
</div>
{{< /example >}}

Note that by default, the content inside the `.progress-bar` is controlled with `overflow: hidden`, so it doesn't bleed out of the bar. If your progress bar is shorter than its label, the content will be capped and may become unreadable. To change this behavior, you can use `.overflow-visible` from the [overflow utilities]({{< docsref "/utilities/overflow" >}}), but make sure to also define an explicit [text color]({{< docsref "/utilities/colors#colors" >}}) so the text remains readable. Be aware though that currently this approach does not take into account [color modes]({{< docsref "/customize/color-modes" >}}).
### Long labels

{{< example >}}
<div class="progress" role="progressbar" aria-label="Example with label" aria-valuenow="10" aria-valuemin="0" aria-valuemax="100">
<div class="progress-bar overflow-visible text-dark" style="width: 10%">Long label text for the progress bar, set to a dark color</div>
</div>
{{< /example >}}
Note that by default, the content inside the `.progress-bar` is controlled with `overflow: hidden`, so it doesn't bleed out of the bar. If your progress bar is shorter than its label, the content will be capped and may become unreadable. To change this behavior, you can use `.overflow-visible` from the [overflow utilities]({{< docsref "/utilities/overflow" >}}).

{{< callout warning >}}
**Accessibility warning:** Long labels may not be fully accessible with this method. As it relies on the text color having the right contrast ratio with both the `.progress` and `.progress-bar` background colors, your color palette could be incompatible with this approach.
Copy link
Member

@patrickhlauke patrickhlauke Nov 15, 2023 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

the colour problem applies to short labels inside progress bars as well though, so i wouldn't make this callout specific to long labels. move it further down where you talk about setting text colours etc?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

the colour problem applies to short labels inside progress bars as well though

I'm not sure to understand precisely this point.

My approach was the following:

  • .text-bg-* is taking care of the contrast issues (and if overridden, should be done by the users to ensure the right contrast).
  • When folks don't want to use these utilities, the following sentence is supposed to cover this use case: "... make sure to also set an appropriate text color, so the labels remain readable and have sufficient contrast".

So the remaining case would be the label not fitting in the really small space -> use overflow-visible but be careful (the yellow accessibility callout) because you probably never find a color contrast working for both the colored progress bar, the gray area behind, and the text over these 2 surfaces.

By moving the yellow callout down and making it non-specific to long labels, I have the impression that a use case wouldn't be explained/understood.

Do you have an idea/a wording to tackle everything in one callout moved further down? Don't hesitate to push a commit on top of mine. Would be great if there was a simplified way to explain that, my wording capacities are limited in English ^^

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not sure to understand precisely this point.

unless i'm missing something, regardless of length of the label, it will always have to contrast against both the progress bar itself and the progress background. it's just that it's likely that for "long" labels, the problem is likely more obvious?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I was thinking about the first two use cases in https://codepen.io/julien-deramond/pen/QWYxwXV where the overflow is hidden or when the value is static and the developers know whether the label can always fit within the progress bar and will never overlap the progress background.
Maybe it's a bad practice but I saw that on websites.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

sorry, getting back to this after a long break... but my point is even in those examples you mention, look at the first one...it doesn't quite fit into the blue bar either.

screenshot of the codepen, with the first '1%' text circled, as it also doesn't fully sit over the blue progress bar

so my point is: the callout applies in all situations - you'll likely never find a colour for the text that contrasts sufficiently against both the bar and the bar background, and particularly when the progress bar is actually used to show dynamic progress, you won't generally be able to guarantee that text fits in perfectly under all conditions. that's why i'd say the callout should be generalised, as it's not just a problem with dark mode etc


If the text can overlap the progress bar, we often recommend displaying the label outside of the progress bar for better accessibility.
{{< /callout >}}

## Backgrounds

Expand All @@ -106,28 +108,20 @@ Use background utility classes to change the appearance of individual progress b
{{< partial "callouts/warning-color-assistive-technologies.md" >}}
{{< /callout >}}

If you're adding labels to progress bars with a custom background color, make sure to also set an appropriate [text color]({{< docsref "/utilities/colors#colors" >}}), so the labels remain readable and have sufficient contrast.
If you're adding labels to progress bars with a custom background color, make sure to also set an appropriate [text color]({{< docsref "/utilities/colors#colors" >}}), so the labels remain readable and have sufficient contrast. We recommend using the [color and background]({{< docsref "/helpers/color-background" >}}) helper classes.

{{< example >}}
<div class="progress" role="progressbar" aria-label="Success example" aria-valuenow="25" aria-valuemin="0" aria-valuemax="100">
<div class="progress-bar bg-success" style="width: 25%">25%</div>
<div class="progress-bar text-bg-success" style="width: 25%">25%</div>
</div>
<div class="progress" role="progressbar" aria-label="Info example" aria-valuenow="50" aria-valuemin="0" aria-valuemax="100">
<div class="progress-bar bg-info text-dark" style="width: 50%">50%</div>
<div class="progress-bar text-bg-info" style="width: 50%">50%</div>
</div>
<div class="progress" role="progressbar" aria-label="Warning example" aria-valuenow="75" aria-valuemin="0" aria-valuemax="100">
<div class="progress-bar bg-warning text-dark" style="width: 75%">75%</div>
<div class="progress-bar text-bg-warning" style="width: 75%">75%</div>
</div>
<div class="progress" role="progressbar" aria-label="Danger example" aria-valuenow="100" aria-valuemin="0" aria-valuemax="100">
<div class="progress-bar bg-danger" style="width: 100%">100%</div>
</div>
{{< /example >}}

Alternatively, you can use the new combined [color and background]({{< docsref "/helpers/color-background" >}}) helper classes.

{{< example >}}
<div class="progress" role="progressbar" aria-label="Warning example" aria-valuenow="75" aria-valuemin="0" aria-valuemax="100">
<div class="progress-bar text-bg-warning" style="width: 75%">75%</div>
<div class="progress-bar text-bg-danger" style="width: 100%">100%</div>
</div>
{{< /example >}}

Expand Down