From 1299b163c7526b0e6892856d87e8710bc195d7f5 Mon Sep 17 00:00:00 2001 From: "Patrick H. Lauke" Date: Sat, 21 Jan 2023 17:51:45 +0000 Subject: [PATCH] Docs: tweak icon link and callouts (#37923) * Tweak callout for icon link - no need to talk about `alt` for `` since these don't use `` - make start of sentence more readable * Tweak language of dropdown warning callout * Tweak popover warning callout * Tweak rtl warning callouts * Tweak color warning callout * Add/move accessibility callout for color to relevant pages * Update site/content/docs/5.3/helpers/icon-link.md * Update site/layouts/partials/callouts/warning-color-assistive-technologies.md Co-authored-by: Mark Otto --- site/content/docs/5.3/components/dropdowns.md | 2 +- site/content/docs/5.3/components/popovers.md | 2 +- site/content/docs/5.3/getting-started/rtl.md | 4 ++-- site/content/docs/5.3/helpers/color-background.md | 4 ++++ site/content/docs/5.3/helpers/icon-link.md | 2 +- site/content/docs/5.3/utilities/background.md | 4 ++++ site/content/docs/5.3/utilities/colors.md | 8 ++++---- .../callouts/warning-color-assistive-technologies.md | 2 +- 8 files changed, 18 insertions(+), 10 deletions(-) diff --git a/site/content/docs/5.3/components/dropdowns.md b/site/content/docs/5.3/components/dropdowns.md index c31847588b..19719a9f27 100644 --- a/site/content/docs/5.3/components/dropdowns.md +++ b/site/content/docs/5.3/components/dropdowns.md @@ -1057,7 +1057,7 @@ Add `data-bs-toggle="dropdown"` to a link or button to toggle a dropdown. ### Via JavaScript {{< callout warning >}} -Dropdowns must have `data-bs-toggle="dropdown"` on their trigger element, regardless of using the Data API or JavaScript. +Dropdowns must have `data-bs-toggle="dropdown"` on their trigger element, regardless of whether you call your dropdown via JavaScript or use the data-api. {{< /callout >}} Call the dropdowns via JavaScript: diff --git a/site/content/docs/5.3/components/popovers.md b/site/content/docs/5.3/components/popovers.md index ad86cdfead..877039b958 100644 --- a/site/content/docs/5.3/components/popovers.md +++ b/site/content/docs/5.3/components/popovers.md @@ -167,7 +167,7 @@ const popover = new bootstrap.Popover(exampleEl, options) Avoid adding an excessive amount of content in popovers with the `html` option. Once popovers are displayed, their content is tied to the trigger element with the `aria-describedby` attribute, causing all of the popover's content to be announced to assistive technology users as one long, uninterrupted stream. -Popovers do not manage keyboard focus order, and their placement can be random in the DOM, so be careful when adding interactive elements (like forms or links). In cases where you must use these elements, consider using a modal dialog to help keep content accessible and usable for keyboard users and users of assistive technologies. +Popovers do not manage keyboard focus order, and their placement can be random in the DOM, so be careful when adding interactive elements (like forms or links), as it may lead to an illogical focus order or make the popover content itself completely unreachable for keyboard users. In cases where you must use these elements, consider using a modal dialog instead. {{< /callout >}} ### Options diff --git a/site/content/docs/5.3/getting-started/rtl.md b/site/content/docs/5.3/getting-started/rtl.md index 11269d1fda..156f205639 100644 --- a/site/content/docs/5.3/getting-started/rtl.md +++ b/site/content/docs/5.3/getting-started/rtl.md @@ -13,7 +13,7 @@ We recommend getting familiar with Bootstrap first by reading through our [Getti You may also want to read up on [the RTLCSS project](https://rtlcss.com/), as it powers our approach to RTL. {{< callout warning >}} -**Bootstrap's RTL feature is still experimental** and will probably evolve according to user feedback. Spotted something or have an improvement to suggest? [Open an issue]({{< param repo >}}/issues/new/choose), we'd love to get your insights. +**Bootstrap's RTL feature is still experimental** and will evolve based on user feedback. Spotted something or have an improvement to suggest? [Open an issue]({{< param repo >}}/issues/new/choose), we'd love to get your insights. {{< /callout >}} ## Required HTML @@ -161,7 +161,7 @@ Need both LTR and RTL on the same page? Thanks to [RTLCSS String Maps](https://r After running Sass then RTLCSS, each selector in your CSS files will be prepended by `.ltr`, and `.rtl` for RTL files. Now you're able to use both files on the same page, and simply use `.ltr` or `.rtl` on your components wrappers to use one or the other direction. {{< callout warning >}} -**Edge cases and known limitations —** Please consider the following when working with a combined LTR and RTL implementation: +**Edge cases and known limitations** to consider when working with a combined LTR and RTL implementation: 1. When switching `.ltr` and `.rtl`, make sure you add `dir` and `lang` attributes accordingly. 2. Loading both files can be a real performance bottleneck: consider some [optimization]({{< docsref "/customize/optimize" >}}), and maybe try to [load one of those files asynchronously](https://www.filamentgroup.com/lab/load-css-simpler/). diff --git a/site/content/docs/5.3/helpers/color-background.md b/site/content/docs/5.3/helpers/color-background.md index aee048e0ff..d64ca43391 100644 --- a/site/content/docs/5.3/helpers/color-background.md +++ b/site/content/docs/5.3/helpers/color-background.md @@ -23,6 +23,10 @@ Color and background helpers combine the power of our [`.text-*` utilities]({{< {{< /text-bg.inline >}} {{< /example >}} +{{< callout info >}} +{{< partial "callouts/warning-color-assistive-technologies.md" >}} +{{< /callout >}} + ## With components Use them in place of combined `.text-*` and `.bg-*` classes, like on [badges]({{< docsref "/components/badge#background-colors" >}}): diff --git a/site/content/docs/5.3/helpers/icon-link.md b/site/content/docs/5.3/helpers/icon-link.md index 66b2036bbf..ac36dcb3f0 100644 --- a/site/content/docs/5.3/helpers/icon-link.md +++ b/site/content/docs/5.3/helpers/icon-link.md @@ -13,7 +13,7 @@ The icon link helper component modifies our default link styles to enhance their Icon links assume [Bootstrap Icons](https://icons.getbootstrap.com) are being used, but you can use any icon or image you like. {{< callout >}} -Icons used here are likely to be purely decorative, which means they should be hidden from assistive technologies using `aria-hidden="true"`, as we've done in our examples. For icons that are more than decorative, provide an appropriate text alternative via `alt` for `` elements `role="img"` and `aria-label` for SVGs. +When icons are purely decorative, they should be hidden from assistive technologies using `aria-hidden="true"`, as we've done in our examples. For icons that convey meaning, provide an appropriate text alternative by adding `role="img"` and an appropriate `aria-label="..."` to the SVGs. {{< /callout >}} ## Example diff --git a/site/content/docs/5.3/utilities/background.md b/site/content/docs/5.3/utilities/background.md index f3502b28ac..eea5532919 100644 --- a/site/content/docs/5.3/utilities/background.md +++ b/site/content/docs/5.3/utilities/background.md @@ -6,6 +6,10 @@ group: utilities toc: true --- +{{< callout info >}} +{{< partial "callouts/warning-color-assistive-technologies.md" >}} +{{< /callout >}} + ## Background color Similar to the contextual text color classes, set the background of an element to any contextual class. Background utilities **do not set `color`**, so in some cases you'll want to use `.text-*` [color utilities]({{< docsref "/utilities/colors" >}}). diff --git a/site/content/docs/5.3/utilities/colors.md b/site/content/docs/5.3/utilities/colors.md index af0cadce57..2023049d40 100644 --- a/site/content/docs/5.3/utilities/colors.md +++ b/site/content/docs/5.3/utilities/colors.md @@ -6,6 +6,10 @@ group: utilities toc: true --- +{{< callout info >}} +{{< partial "callouts/warning-color-assistive-technologies.md" >}} +{{< /callout >}} + ## Colors Colorize text with color utilities. If you want to colorize links, you can use the [`.link-*` helper classes]({{< docsref "/helpers/colored-links" >}}) which have `:hover` and `:focus` states. @@ -42,10 +46,6 @@ Color utilities like `.text-*` that generated from our original `$theme-colors` **Deprecation:** With the addition of the expanded theme colors and variables, the `.text-body-secondary` utility has been deprecated as of v5.3.0. Its default value has also has been reassigned to the new `--bs-secondary-color` CSS variable to better support color modes. It will be removed in v6.0.0. {{< /callout >}} -{{< callout info >}} -{{< partial "callouts/warning-color-assistive-technologies.md" >}} -{{< /callout >}} - ## Opacity {{< added-in "5.1.0" >}} diff --git a/site/layouts/partials/callouts/warning-color-assistive-technologies.md b/site/layouts/partials/callouts/warning-color-assistive-technologies.md index 49551880e5..aaa6f64c86 100644 --- a/site/layouts/partials/callouts/warning-color-assistive-technologies.md +++ b/site/layouts/partials/callouts/warning-color-assistive-technologies.md @@ -1 +1 @@ -**ProTip!** Conveying meaning through color alone will not be conveyed to users of assistive technologies like screen readers. Please ensure the context is is obvious itself (e.g., the visible text) or is included through alternative means, such as additional text hidden with the `.visually-hidden` class. \ No newline at end of file +**Accessibility tip:** Using color to add meaning only provides a visual indication, which will not be conveyed to users of assistive technologies like screen readers. Please ensure the meaning is obvious from the content itself (e.g., the visible text) or is included through alternative means, such as additional text hidden with the `.visually-hidden` class. \ No newline at end of file