-
Notifications
You must be signed in to change notification settings - Fork 0
Description
Components: Send a message
This issue is present throughout the API documentation.
Observation:
- Heading Structure & Duplicate Issues
Multiple headings include a # anchor inside the heading tag:
<h2 id="headers"><a href="#headers" class="header-anchor">#</a> Headers</h2>
Including the # inside heading may cause confusion: screen readers might read it as part of the heading. This can also trigger “duplicate heading” warnings if the plain heading appears elsewhere. - Context for Code Blocks & Screen Reader Clarity
Multiple back-to-back code snippets (e.g., JSON examples) lack contextual labels, which may confuse users navigating with screen readers.
(Attachment:
7.13.3. Context for Code Blocks & Screen Reader Clarity.png
7.13.3. Heading Structure & Duplicate Issues.mp4)
Recommendation:
- Move the anchor outside of the heading and add aria-hidden="true" to visually hide it:
<h2 id="headers">Headers</h2>
<a href="#headers" class="header-anchor" aria-hidden="true">#</a>
- Use
<figure>and<figcaption>:
<figure>
<figcaption>Example request body</figcaption>
<pre class="language-json" tabindex="0"><code>...</code></pre>
</figure>
Or add a visually hidden label:
<span class="sr-only">Example response:</span>
<pre tabindex="0">…</pre>