diff --git a/src/_components/divider.md b/src/_components/divider.md index 66a1f6661..f2f2874e0 100644 --- a/src/_components/divider.md +++ b/src/_components/divider.md @@ -7,6 +7,10 @@ intro-text: "Dividers are used sparingly to separate significant sections of con status: use-best-practice web: true mobile-app: false +anchors: + - anchor: Example + - anchor: Usage + - anchor: Accessibility considerations --- ## Example @@ -24,5 +28,24 @@ mobile-app: false ### When to consider something else -- Avoid using divider between short, individual items that are in close proximity with one another, _unless_ they are separating navigation links. Consider using white space or headers instead to create vertical separation. -- Use a background color box or card to separate a chunk of interactive elements, like search controls, from a list of search results. +* **Short items in close proximity.** Avoid using a divider between short, individual items that are close to one another, _unless_ they separate navigation links. Consider using white space or headers instead to create vertical separation. +* **Grouped interactive elements.** Use a background color box or card to separate a chunk of interactive elements, like search controls, from a list of search results. + +### How this component works + +The Divider component creates a horizontal rule between sections of content. Use it to separate distinct groups of information when spacing or headings alone don't provide enough visual separation. + +In most cases, dividers are decorative. If a divider communicates a meaningful change in topic or structure, don't hide it from assistive technology. +## Accessibility considerations + +### Decorative vs semantic dividers + +Not all dividers should be announced to screen readers. Most dividers are decorative when used alongside headings or within well-structured content. + +**Use `aria-hidden="true"` for decorative dividers when:** +- The divider only provides visual separation +- Content structure is already clear through headings or other markup + +**Do not use `aria-hidden="true"` for semantic dividers when:** +- The divider marks a significant topic change meaningful to non-visual users +- The divider is the primary indicator of a content boundary