add accessibility section for CSS Custom Highlight API

[mohammed-ali-osman]

Description

This PR adds an Accessibility section to the CSS Custom Highlight API page.

• Summarizes the intended behavior from the specification: the type attribute can be used by user agents to expose semantic meaning (such as spelling or grammar errors) to assistive technologies.

• Notes that current support is limited and inconsistent across browsers and platform accessibility APIs.

• Provides guidance for developers: custom highlights should not be relied on alone to convey important information; semantic HTML elements like <mark> or additional accessible cues should be used when highlighting conveys meaning.

This update ensures that developers are aware of accessibility limitations and helps prevent assumptions about screen reader support.

Fixes #43408

[github-actions]

Preview URLs (5 pages)

• /en-US/docs/Web/API/Animation
• /en-US/docs/Web/API/CSS_Custom_Highlight_API
• /en-US/docs/Web/API/Canvas_API/Tutorial/Drawing_text
• /en-US/docs/Web/API/Canvas_API
• /en-US/docs/Web/API/Web_Animations_API

External URLs (5)

URL: /en-US/docs/Web/API/Canvas_API/Tutorial/Drawing_text
Title: Drawing text

• https://html.spec.whatwg.org/multipage/canvas.html (1 time)

---

URL: /en-US/docs/Web/API/Web_Animations_API
Title: Web Animations API

• https://alistapart.com/article/designing-safer-web-animation-for-motion-sensitivity/ (1 time) (Note! This may be a new URL 👀)
• https://css-tricks.com/introduction-reduced-motion-media-query/ (1 time) (Note! This may be a new URL 👀)
• https://webkit.org/blog/7551/responsive-design-for-motion/ (1 time) (Note! This may be a new URL 👀)
• https://www.w3.org/TR/UNDERSTANDING-WCAG20/time-limits-pause.html (1 time) (Note! This may be a new URL 👀)

(comment last updated: 2026-08-12 23:07:22)

[Josh-Cena]

@chrisdavidmills I'd be happy to review this but I'm not sure if this section is in the correct place. What's the standard practice for documenting a11y in APIs with CSS?

[chrisdavidmills]

@chrisdavidmills I'd be happy to review this but I'm not sure if this section is in the correct place. What's the standard practice for documenting a11y in APIs with CSS?

This is interesting. "Accessibility" sections are well-established in the HTML and CSS sections, but I don't think I've ever worked on one in the API section before.

Grepping around the site, I can see 4 such sections in existence:

• https://developer.mozilla.org/en-US/docs/Web/API/Animation#accessibility_concerns
• https://developer.mozilla.org/en-US/docs/Web/API/EditContext_API#accessibility
• https://developer.mozilla.org/en-US/docs/Web/API/Window/open#accessibility_concerns
• https://developer.mozilla.org/en-US/docs/Web/API/Canvas_API/Tutorial/Drawing_text#accessibility_concerns

We probably ought to add these sections to the API templates at some point. I think the heading should always be "Accessibility", for consistency. In terms of placement:

• In reference pages, any "Accessibility" section should always go just before the "Examples" section (or the "Specifications" section if no "Examples" section exists).
• In API landing pages, the "Accessibility" section should be put as a subsection inside "Concepts and usage"

Again, for consistency.

Which is all to say, I think the placement in this case is correct.

[Josh-Cena]

Thank you