CodeBlock - aria argument and screen-reader improvements

[dchyun]

📌 Summary

PREVIEW

If merged, this PR would improve the accessibility of the CodeBlock by implementing the following features

• New arguments for @ariaLabel, @ariaLabelledBy, and @ariaDescribedBy
• Attaching the title and description, if present, to the code block element via aria-labelledby and aria-describedby
• Adding screen-reader only text to indicate line highlighting

It would also update the hds-clipboard modifier to support not copying sr-only text.

🛠️ Detailed description

Accessible names

The @ariaLabel, @ariaLabelledBy, and @ariaDescribedBy arguments have been added to the CodeBlock to align its approach to the CodeEditor.

Also, the setting of these aria attributes has been aligned to the CodeEditor in the following ways.

• If a title is present, aria-labelledby will be set to the ID of the title element
• If a description is present, aria-describedby, will be set to the ID of the description element
• If a custom value is set on the @ariaLabel argument, and a title is present, the title id will not be set in aria-labelledby

The docs (#2896) will be updated to match the CodeEditor and say that @ariaLabel or @ariaLabelledby must be used if a title is not present. Existing implementation of the CodeBlock should be updated to add these arguments, but this will not cause breaking changes for anyone.

Line highlighting for screen readers

Currently, there is no indication to screen reader users when line highlighting is used. Due to the fact that line numbers are also inaccessible to the screen reader (which can not be fixed since line numbers come from Prism), we can not add sr only text such as "Line 2 and 4 highlighed"

Instead the approach taken is to edit the code generated by prism to add sr-only text before and after line highlight starts indicating when highlighting starts, and when it ends. To prevent the sr-only text from being copied to the clipboard with the CopyButton, the hds-clipboard modifier has been updated to ignore sr-only text

The logic for determining where to add the sr only text mirrors the Prism plugin's code for determining highlights.

📸 Screenshots

Aria attributes for title and description

Before

After

Line highlighting screen-reader only copy

🔗 External links

Jira ticket: HDS-3349

---

👀 Component checklist

• Percy was checked for any visual regression
• A changelog entry was added via Changesets if needed (see templates here)

💬 Please consider using conventional comments when reviewing this PR.

[vercel]

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Updated (UTC)
hds-showcase	✅ Ready (Inspect)	Visit Preview	May 22, 2025 5:50pm
hds-website	✅ Ready (Inspect)	Visit Preview	May 22, 2025 5:50pm

[dchyun]

@MelSumner @shleewhite I've been working on the a11y improvements originally raised in HDS-3349.

For the accessible name and description I've aligned the Code Block to the Code Editor and attached the title + description to the code element if they are present + added some aria arguments.

My main open question is related to making line highlighting visible to the SR.

One approach would be to add some sr text saying which lines are highlighted. However, the code block line numbers come from Prism, and are not accessible to the sr. The code is read as one long block of text.

The approach I've taken currently is to add sr-only text stating when a highlight starts, and when it ends in the block of text.

This involves directly editing the code that prism js gives us, but I wanted to see if this would be a good approach to take, or if there are any other ideas we have for announcing line highlights to the screen reader.

[shleewhite]

the approach looks good! looking at the showcase though, seems like the "highlight start/end" strings are visible right now.

[MelSumner]

this seems like a great approach!

[shleewhite]

Looks good to me!

[shleewhite]

Is there a case for this outside of the CodeBlock component?

[dchyun]

There isn't right now, but it could be useful in general. I don't think there's a use case for having sr only text and wanting it copied, which is what would happen currently.