Update wiki page with another method for making SVGs WCAG compliant

[roslynwythe]

Overview

As developers we need to update a wiki page with an additional method for providing SVG graphics with accessible names in order to comply with WCAG

Details

An accessible name is a short string of text that identifies a user interface element and gives users of assistive technology a label for it. The "alt-text" attribute is used to provide an accessible name for an img element, however the "alt-text" attribute is not applicable to an svg element. The wiki page https://github.com/hackforla/website/wiki/How-to-make-SVGs-and-other-images-WCAG-compliant describes methods for providing an accessible name to svg elements, and in this issue we will add a new method.

Action Items

• [x] We are currently in the process of moving the old wiki to the new website-wiki repo, so we will not be making any changes or additions to the old wiki at this time. Thus, we will be adding wiki content through a different process now. Read How to Contribute to the Wiki
• [x] Following the process outlined above in How to Contribute to the Wiki, copy the raw source of the page https://github.com/hackforla/website/wiki/How-to-make-SVGs-and-other-images-WCAG-compliant into a comment in this issue
• [x] Add a new section immediately before the text ""Accessible names/descriptions" with the heading "Use an outer svg with aria-label or aria-labelledby"
• [x] Mention that in many instances, we wrap svg elements in outer svg elements, in order to apply styling attributes (such as fill and viewBox to the outer svg), and outer svg can also provide an accessible name using these rules:
  • [x] If the desired accessible name appears as text in another element on the page, use the aria-labelledby attribute to reference the element containing the desired text.

Example:
<svg role="img"  viewBox="0 0 100 100"  aria-labelledby="resource-title">
  {% include svg/icon-github-color.svg %}
<svg>
<h4 id="resource-title">GitHub</h4>

• [x] If there is no element displaying the desired accessible name, use the aria-label attribute to specify the name, or else use the aria-labelledby attribute and reference a new child <title> element. If used, the <title> element should be the first child of the outer <svg>

Example:
<svg role="img"  viewBox="0 0 100 100"  aria-labelledby="titleID">
   <title id="titleID">GitHub</title>
   {% include svg/icon-github-color.svg %}
<svg>

• [x] Mention that if an appropriate name exists on the page, use of aria-labelledby is preferable to aria-label

Resources/Instructions

HTML and accessibility tree depicting a duplicate accessible name "GitHub GitHub" on the link wrapping an svg element

HTML and accessibility tree depicting solution to duplicate accessible name

https://github.com/hackforla/website/wiki/How-to-make-SVGs-and-other-images-WCAG-compliant https://www.w3.org/TR/using-aria/ https://canvas.workday.com/accessibility/the-accessibility-tree/#how-to-view-the-accessibility-tree

• This issue resulted from #4242

[github-actions[bot]]

Hi @roslynwythe, thank you for taking up this issue! Hfla appreciates you :)

Do let fellow developers know about your:- i. Availability: (When are you available to work on the issue/answer questions other programmers might have about your issue?) ii. ETA: (When do you expect this issue to be completed?)

You're awesome!

P.S. - You may not take up another issue until this issue gets merged (or closed). Thanks again :)

[github-actions[bot]]

Hi @Jperparas, thank you for taking up this issue! Hfla appreciates you :)

Do let fellow developers know about your:- i. Availability: (When are you available to work on the issue/answer questions other programmers might have about your issue?) ii. ETA: (When do you expect this issue to be completed?)

You're awesome!

P.S. - You may not take up another issue until this issue gets merged (or closed). Thanks again :)

[Jperparas]

Availability: 4/25-4/30 early afternoon

ETA: 4/30 EoD

[Jperparas]

Overview Using the alt property in img HTML tags or Accessible Rich Internet Applications (ARIA) labels with Scalable Vector Graphics (SVGs) and other images is important so that all images on the Hack for LA website are Web Content Accessibility Guidelines (WCAG) compliant. This pages explains how the Website Team deals with SVGs and other images to make them WCAG compliant.

Methods

Use an img HTML tag with the SVG or image as for the src and an alt attribute

When to use it

• Any new images added to the website repo, which are added to /assets/images directory or in a subdirectory of it
• Images already in /assets/images directory or in a subdirectory of it

Notes

• For SVGs, see the pros and cons detailed in The quick way: img element section in MDN Web Docs Adding vector graphics to the web.

Example of an image in an img tag that needs an alt attribute:

<img class="header-hero-image" src="/assets/images/toolkit/toolkit-hero.svg">

Steps:

In an img HTML tag,

1. The image needs to be in the /assets/images directory or be in a subdirectory of it
2. Set src to the path to the SVG or image
3. Add an alt attribute with an appropriate descriptive text. (Depending on the image, the alt attribute will either be an empty alt attribute (alt="") or will have an appropriate descriptive text. You can use this alt Decision Tree to help you decide what the alt attribute should contain.)

<img class="header-hero-image" src="/assets/images/toolkit/toolkit-hero.svg" alt="" >

Use an ARIA label in the div HTML tag wrapping the SVG

When to use it

• Any existing images in the _includes in the website repo

Notes

• For SVGs, see the pros and cons detailed in How to include SVG code inside your HTML section in MDN Web Docs Adding vector graphics to the web. This section discusses inline SVG, which is what this method does using Jekyll's include tag to insert an SVG into a HTML file and the result of this is an inline SVG when the site is generated.

Example of an SVG wrapped in a div tag that needs an ARIA label:

<div>
  {% include svg/logo-hfla-small.svg %}
</div>

Steps:

In an div HTML tag,

1. Add a role="img"
2. Add an aria-label with an appropriate descriptive text.

<div role="img" aria-label="Hack for LA">
  {% include svg/logo-hfla-small.svg %}
</div>

Use an outer SVG with aria-label or aria-labelledby

In many instances, we wrap svg elements in outer svg elements, in order to apply styling attributes (such as fill and viewBox to the outer svg), and outer svg can also provide an accessible name using these rules:

• If the desired accessible name appears as text in another element on the page, use the aria-labelledby attribute to reference the element containing the desired text

<svg role="img"  viewBox="0 0 100 100"  aria-labelledby="resource-title">
 {% include svg/icon-github-color.svg %}
</svg>
<h4 id="resource-title">GitHub</h4>

• If there is no element displaying the desired accessible name, use the aria-label attribute to specify the name, or else use the aria-labelledby attribute and reference a new child <title> element. If used, the <title> element should be the first child of the outer <svg>

[!NOTE] If an appropriate name exists on the page, use of aria-labelledby is preferable to aria-label

<svg role="img"  viewBox="0 0 100 100"  aria-labelledby="titleID">
   <title id="titleID">GitHub</title>
   {% include svg/icon-github-color.svg %}
</svg>

Accessible names/descriptions

Review the w3.org document about accessible names and descriptions here.

Naming:

• Naming with child content.
• Naming with a string attribute via aria-label.
• Naming by referencing content with aria-labelledby.
• Naming form controls with the label element.
• Naming fieldsets with the legend element.
• Naming tables and figures with captions.
• Fallback names derived from titles and placeholders.

Describing:

• Describing by referencing content with aria-describedby.
• Describing tables and figures with captions.
• Descriptions derived from titles.

Resources

• MDN: aria-label
• MDN: ARIA, img role
• a11y-101: Accessible SVGs
• w3.org: Accessible Names and Descriptions
• WCAG 2 Overview

[roslynwythe]

@Jperparas this is well done, however the "Solution" under "Potential conflicts with adding an accessible name to an element" is not always effective and the situation is rather complex, so I think it would be better to omit mention of this problem. I modified the last Action Item to be much simpler, so please edit accordingly.

[Jperparas]

@roslynwythe Thank you! I was dubious of the solution as well. I omitted the potential conflict section and added the new last Action Item.

[github-actions[bot]]

@Jperparas

Please add update using the below template (even if you have a pull request). Afterwards, remove the 'To Update !' label and add the 'Status: Updated' label.

1. Progress: "What is the current status of your project? What have you completed and what is left to do?"
2. Blockers: "Difficulties or errors encountered."
3. Availability: "How much time will you have this week to work on this issue?"
4. ETA: "When do you expect this issue to be completed?"
5. Pictures (optional): "Add any pictures of the visual changes made to the site so far."

If you need help, be sure to either: 1) place your issue in the Questions/In Review column of the Project Board and ask for help at your next meeting, 2) put a "Status: Help Wanted" label on your issue and pull request, or 3) put up a request for assistance on the #hfla-site channel. Please note that including your questions in the issue comments- along with screenshots, if applicable- will help us to help you. Here and here are examples of well-formed questions.

_{You are receiving this comment because your last comment was before Tuesday, May 7, 2024 at 12:06 AM PST.}

[Jperparas]

1. Progress: Completed all Tasks. linked comment to Content to be added/edited in the new website-wiki repo
2. Blockers: No Blockers waiting review
3. Availability Early Afternoon 5/11-5/13

[roslynwythe]

Thank you @Jperparas for creating this documentation of methods to make accesible SVGs.