Feat: decorative/informative img (#30)

* feat: adds decorative image section separate from informative - edits a few examples - renames filenames * feat: adds demo page for testing decorative img (this is only for the purposes of testing and deciding on if aria-hidden should be included in the write up. delete these files when we come to consensus). * fix: edit a couple sentences * feat: edits a bit of the entries and adds a demo for images decorative - removes src file svg hack role="img" as it is no longer needed https://www.scottohara.me/blog/2019/05/22/contextual-images-svgs-and-a11y.html#:~:text=Updated%3A%20Image%20elements%20with%20SVG%20source%20exception - adds demo for image decorative - edits some wording in images decorative/informative * fix: a couple edits to markdown language * fix: edit decorative image demo entry and classes * Making edits to simplify and make extendable * Consolidated margin * Update _images.scss --------- Co-authored-by: charlietriplett <charlie@charliecharliecharlie.com>
tmobile · Feb 21, 2023 · 14daa58 · 14daa58
1 parent 47204c8
commit 14daa58
Show file tree

Hide file tree

Showing 8 changed files with 159 additions and 58 deletions.
diff --git a/.gitignore b/.gitignore
@@ -8,3 +8,4 @@ CNAME
 Icon[
 ]
 .DS_Store
+Gemfile.lock
diff --git a/_checklist-web/image-decorative.md b/_checklist-web/image-decorative.md
@@ -0,0 +1,84 @@
+---
+layout: entry
+title:  "Decorative image"
+description: "How to code and test accessible decorative images (jpg, gif, png, svg)"
+categories: main
+
+keyboard:
+  arrow-keys: |
+    Screenreader ignores the image completely
+
+mobile:
+  swipe: |
+    The screenreader ignores the image completely
+
+screenreader:
+  role:  |
+    The image is ignored
+
+gherkin-keyboard: 
+  - when:  |
+      the arrow keys to browse to an image
+    result: |
+      the image is skipped and ignored
+
+gherkin-mobile:
+  - when:  |
+      swipe to browse to an image
+
+wcag:
+  - name: Perceivable
+    list:
+      - criteria: All non-text content that is purely for decoration or which repeats existing on-screen text nearby should be ignored and skipped over by screenreaders.
+---
+
+## Decorative images
+
+There are times that images shouldn't be read because it would be repetitive or not add any value in addition to the existing page content. These types of images are generally included for purely stylistic purposes and don't impart any meaning to the rest of the content on the page.
+
+## Is this image decorative or informative?
+If the image conveys important meaning, and there's no other text on the page which explains the concept within it, then the image is likely informative. In this case, check out the [informative image checklist](/checklist-web/image) item instead. 
+
+If your image contains text inside it, it should not! This is a violation of [WCAG AA 1.4.5 Images of Text](https://www.w3.org/WAI/WCAG21/Understanding/images-of-text.html). Exceptions exist for logos.
+
+## The alt attribute is still required
+
+- To have valid HTML, the `alt` attribute must still be present, even when set to the empty empty value of `alt`. Note that `alt` and `alt=""` (no space) are equivalent in HTML.
+  - When the `alt` attribute is empty, the screen reader ignores it (and will not read anything).
+  - When the `alt` attribute is missing, the screen reader will read the `src` name or filename of the image which is a very poor user experience.
+
+## Reinforce decorative images with aria-hidden
+
+- Use `aria-hidden="true"` as a backup and reinforcement to `alt`:
+  - Backup: **developers often mistakenly omit the alt attribute entirely**, meaning that some screenreaders will read the entire filename without an alt attribute. Including `aria-hidden="true"` will act as a backup.
+  - Reinforcement: using `aria-hidden="true"` ensures that screenreaders ignores the image. Screenreaders have been observed reading an image role even when the alt attribute is empty.
+
+<example>
+{% include /examples/image-decorative.html %}
+</example>
+
+{% highlight html %}
+{% include /examples/image-decorative.html %}
+{% endhighlight %}
+
+## Using inline SVG
+
+### Inline SVG that conveys meaning
+
+Inline SVGs require some special code to be hidden properly from screen readers:
+- `aria-hidden="true"`
+
+If you are using a `<use />` element, add `aria-hidden="true"`.
+
+### Inline SVG that is decorative
+{% highlight html %}
+<svg aria-hidden="true" focusable="false">
+  <use href="#svg-id" aria-hidden="true" />
+  <!-- if not using <use> then the child elements 
+       of the inline SVG would go here -->
+</svg>
+{% endhighlight %}
+
+## Further reading
+- This page owes a lot to this exhaustive blog post: [Contextually Marking up accessible images and SVGs by Scott O'Hara](https://www.scottohara.me/blog/2019/05/22/contextual-images-svgs-and-a11y.html)
+- [W3C Image decision tree](https://www.w3.org/WAI/tutorials/images/decision-tree/)
diff --git a/_checklist-web/image.md b/_checklist-web/image.md
@@ -1,7 +1,7 @@
 ---
 layout: entry
-title:  "Image: jpg, gif, png, svg"
-description: "How to code and test accessible images the Web"
+title:  "Informative Image"
+description: "How to code and test accessible informative images (jpg, gif, png, svg)"
 categories: main
 
 keyboard:
@@ -34,59 +34,30 @@ wcag:
       - criteria: All non-text content that is presented to the user has a text alternative that serves the equivalent purpose, unless it is decorative or repetitive
       - criteria: If an image contains text critical to understanding the page the user has a text alternative that serves the equivalent purpose
 ---
+## Is this image decorative or informative?
+If the image conveys important meaning, and there's no other text on the page which explains the concept within it, then the image is likely informative. If the image is included for purely stylistic purposes and doesn't impart any meaning to the rest of the content on the page, then the image is likely decorative. In this case, check out the [decorative image checklist](/checklist-web/image-decorative) item instead. 
 
-## Basic examples
+If your image contains text inside it, it should not! This is a violation of [WCAG AA 1.4.5 Images of Text](https://www.w3.org/WAI/WCAG21/Understanding/images-of-text.html). Exceptions exist for logos.
 
-### Describe the content of the image
-If you were describing the image to someone who couldn't see it, what would you say?
+## Describe the content of the image
+If you were describing the image to someone via phone conversation and they couldn't see what you were looking at, what would you say?
 
 {% highlight html %}
 <img src="/farm.jpg" 
-     alt="Rustic barn surrounded by rolling hills">
+     alt="Rustic barn surrounded by rolling hills" />
 {% endhighlight %}
 
-### Linked SVG that conveys meaning
-
-{% highlight html %}
-<img src="/coffee-roaster.svg" 
-     role="img"
-     alt="Coffee roaster">
-{% endhighlight %}
-
-## Decorative images
-
-There are times that images shouldn't be read because they would be repetitive or not add any value to the content.
-
-### The alt attribute is still required
-
-- To be valid html, the `alt` attribute must still be present, even if empty
-  - When the `alt` attribute is empty, the screen reader ignores it.
-  - When the `alt` attribute is missing, the screen reader will read the src url or filename of the image.
-
-### Reinforce decorative images with aria-hidden
-
-- Use `aria-hidden="true"` as a backup and reinforcement:
-  - As a backup: **developers often mistakenly omit the alt attribute entirely**, meaning that some screenreaders will read the entire filename.
-  - As a **reinforcement** to ensure the screenreader ignores the image. Screenreaders have been observed reading an image role when the alt attribute is present but empty.
-
-{% highlight html %}
-<img src="/info-icon.png" aria-hidden="true" alt>
-{% endhighlight %}
-
-{% highlight html %}
-<a href="tel:8888888888">
-  <!-- The phone icon would be repetitive in this case and should be hidden -->
-  <img src="/phone-icon.png" aria-hidden="true" alt>
-  Call us: 888-888-888
-</a>
-{% endhighlight %}
-
-
 ## Using inline SVG
 
 ### Inline SVG that conveys meaning
 
-Inline SVGs require some special code to be read consistently in all screenreaders.
+Inline SVGs require some special code to be read consistently in all screenreaders:
+- Name: either `aria-label` or `<title />`
+- Role: `role="img"`
+
+If you are using a `<use />` element, add `aria-hidden="true"` to it.
+
+#### Using title
 
 {% highlight html %}
 <svg role="img" focusable="false">
@@ -97,18 +68,13 @@ Inline SVGs require some special code to be read consistently in all screenreade
 </svg>
 {% endhighlight %}
 
-### Inline SVG `<use>` that conveys meaning
-{% highlight html %}
-<svg role="img" aria-label="Name" focusable="false">
-  <use xlink:href="#..." aria-hidden="true"></use>
-</svg>
-{% endhighlight %}
-
+#### Using aria-label
 
-### Inline SVG that is decorative
 {% highlight html %}
-<svg aria-hidden="true" focusable="false">
-  <!-- ... --> 
+<svg role="img" aria-label="Accessible name" focusable="false">
+  <use href="#svg-id" aria-hidden="true" />
+  <!-- if not using <use> then the child elements 
+       of the inline SVG would go here -->
 </svg>
 {% endhighlight %}
 
@@ -118,6 +84,6 @@ Inline SVGs require some special code to be read consistently in all screenreade
 - they are set to stop after 5 seconds or 
 - if users are presented with a way to pause it
 
-### Further reading
-
+## Further reading
 - This page owes a lot to this exhaustive blog post: [Contextually Marking up accessible images and SVGs by Scott O'Hara](https://www.scottohara.me/blog/2019/05/22/contextual-images-svgs-and-a11y.html)
+- [W3C Image decision tree](https://www.w3.org/WAI/tutorials/images/decision-tree/)
diff --git a/_demos/image-decorative.md b/_demos/image-decorative.md
@@ -0,0 +1,8 @@
+---
+layout: demo
+title:  "Decorative Image"
+---
+
+{::nomarkdown}
+{% include /examples/image-decorative.html %}
+{:/}
diff --git a/_includes/examples/image-decorative.html b/_includes/examples/image-decorative.html
@@ -0,0 +1,19 @@
+<h3 class="h-charlie decorated">
+  <img
+    src="/assets/images/icons/icon-info.svg"
+    aria-hidden="true" 
+    class="icon"
+    alt />
+  Note: Your plan might be changing soon.
+</h3>
+<a 
+  href="tel:8888888888"
+  class="decorated">
+  <img 
+    src="/assets/images/icons/icon-phone.svg"
+    aria-hidden="true"
+    class="icon"
+    alt />
+    Call us: 888-888-8888
+</a>
+
diff --git a/_sass/modules/_images.scss b/_sass/modules/_images.scss
@@ -4,10 +4,17 @@
   display: block;
   margin: 0px auto;
   margin-bottom: .25rem;
-
 }
 
 .icon-large {
   height: 64px;
   width: 64px;
-}
+}
+
+.decorated {
+  display: flex;
+  .icon {
+    margin: 0;
+  }
+
+}
diff --git a/assets/images/icons/icon-info.svg b/assets/images/icons/icon-info.svg
diff --git a/assets/images/icons/icon-phone.svg b/assets/images/icons/icon-phone.svg
-Original file line number
+Diff line change
@@ Expand Up / @@ -8,3 +8,4 @@ CNAME @@
     Icon[
     ]
     .DS_Store
+    Gemfile.lock