feat: linked icon a11y

[fkakatie]

Description

This PR adds automatic aria-label attributes to icon-only links to fix Lighthouse accessibility errors ("Links do not have a discernible name"). When decorateIcon() processes an icon inside a link, it now:

1. Checks if the link contains only the icon (no text content)
2. Checks if an aria-label doesn't already exist
3. Sets aria-label to the icon's alt text (if provided) or icon name as fallback

Related Issue

Fixes #13

Motivation and Context

When authors create links using only SVG icons (common for brand logos, social icons, navigation), the resulting HTML has no accessible name for screen readers. This causes Lighthouse to flag these as accessibility violations, reducing scores unnecessarily.

The previous attempt (PR #14) was closed, but the underlying issue remained unresolved. This implementation takes a more conservative approach by only adding labels to icon-only links rather than all linked icons.

How Has This Been Tested?

Added comprehensive test coverage in test/decorate/decorateIcon.test.html:

1. Icon-only link test: Verifies aria-label is added using icon name
2. Existing aria-label test: Confirms existing labels are preserved
3. Link with text test: Ensures links with text content are skipped

Future Considerations

Should this be extracted to a more general link accessibility function?

Currently, this logic lives in decorateIcon() because:

• Icons are the primary source of icon-only links
• Icon name/alt text is already available in context
• Keeps the fix co-located with the problem

However, there could be value in a broader decorateLinks() function that:

• Finds all links lacking accessible names (not just icon links)
• Handles other link accessibility patterns (empty links, image-only links, etc.)
• Could be called from a central decoration entry point

Types of changes

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)

Checklist:

• I have signed the Adobe Open Source CLA.
• My code follows the code style of this project.
• My change requires a change to the documentation.
• I have updated the documentation accordingly.
• I have read the CONTRIBUTING document.
• I have added tests to cover my changes.
• All new and existing tests passed.

[ramboz]

The code is technically clean and does as the PR description states.

I'm less convinced of the actual accessibility of such an approach :)

For instance, if I have a breadcrumb that starts with the "house" icon to bring you back to the home page… I'm not sure that a screenreader reading "HOUSE" aloud is really going to be easily understood by a person with sight impairments.

Or another one, if you have a "3-lines" icon for hamburger icon toggle for the nav on mobile, while the screenreader reading this aloud be enough to convey what the button does?

We'd be fully dependent on a developer having chosen expressive icon names to convey the right message in the given context… I feel this is a bit of a stretch.

I would be tempted to let those continue failing in the audit to force website developers to use meaningful alt names instead. Defaulting to the "alt" which would potentially be empty, is good enough in my opinion. If they did the effort to specify a decent alt text, they are good to go… if they didn't, then the a11y audits will remind them.