diff --git a/packages/terra-core-docs/CHANGELOG.md b/packages/terra-core-docs/CHANGELOG.md
index 7a1b7a27ee5..c7b46a85312 100644
--- a/packages/terra-core-docs/CHANGELOG.md
+++ b/packages/terra-core-docs/CHANGELOG.md
@@ -2,6 +2,9 @@
## Unreleased
+* Added
+ * Added examples and accessibility guide for `terra-image`.
+
## 1.18.0 - (January 9, 2023)
* Changed
diff --git a/packages/terra-core-docs/src/terra-dev-site/common/images/creative-commons/Matterhorn,_March_2019_(01).jpg b/packages/terra-core-docs/src/terra-dev-site/common/images/creative-commons/Matterhorn,_March_2019_(01).jpg
new file mode 100644
index 00000000000..a2a7a5117de
Binary files /dev/null and b/packages/terra-core-docs/src/terra-dev-site/common/images/creative-commons/Matterhorn,_March_2019_(01).jpg differ
diff --git a/packages/terra-core-docs/src/terra-dev-site/common/images/creative-commons/Matterhorn,_March_2019_(01)_150x150.jpg b/packages/terra-core-docs/src/terra-dev-site/common/images/creative-commons/Matterhorn,_March_2019_(01)_150x150.jpg
new file mode 100644
index 00000000000..86640efcbe5
Binary files /dev/null and b/packages/terra-core-docs/src/terra-dev-site/common/images/creative-commons/Matterhorn,_March_2019_(01)_150x150.jpg differ
diff --git a/packages/terra-core-docs/src/terra-dev-site/common/images/creative-commons/Matterhorn,_March_2019_(01)_1920x1280.jpg b/packages/terra-core-docs/src/terra-dev-site/common/images/creative-commons/Matterhorn,_March_2019_(01)_1920x1280.jpg
new file mode 100644
index 00000000000..73f65849edb
Binary files /dev/null and b/packages/terra-core-docs/src/terra-dev-site/common/images/creative-commons/Matterhorn,_March_2019_(01)_1920x1280.jpg differ
diff --git a/packages/terra-core-docs/src/terra-dev-site/common/images/creative-commons/Matterhorn,_March_2019_(01)_480x320.jpg b/packages/terra-core-docs/src/terra-dev-site/common/images/creative-commons/Matterhorn,_March_2019_(01)_480x320.jpg
new file mode 100644
index 00000000000..4f6f25e2846
Binary files /dev/null and b/packages/terra-core-docs/src/terra-dev-site/common/images/creative-commons/Matterhorn,_March_2019_(01)_480x320.jpg differ
diff --git a/packages/terra-core-docs/src/terra-dev-site/common/images/creative-commons/Matterhorn,_March_2019_(01)_960x640.jpg b/packages/terra-core-docs/src/terra-dev-site/common/images/creative-commons/Matterhorn,_March_2019_(01)_960x640.jpg
new file mode 100644
index 00000000000..65006291300
Binary files /dev/null and b/packages/terra-core-docs/src/terra-dev-site/common/images/creative-commons/Matterhorn,_March_2019_(01)_960x640.jpg differ
diff --git a/packages/terra-core-docs/src/terra-dev-site/common/images/creative-commons/Matterhorn,_March_2019_(01)__LICENSE.txt b/packages/terra-core-docs/src/terra-dev-site/common/images/creative-commons/Matterhorn,_March_2019_(01)__LICENSE.txt
new file mode 100644
index 00000000000..e69de29bb2d
diff --git a/packages/terra-core-docs/src/terra-dev-site/common/layout-helpers/Whitespace.jsx b/packages/terra-core-docs/src/terra-dev-site/common/layout-helpers/Whitespace.jsx
new file mode 100644
index 00000000000..fdbd3742243
--- /dev/null
+++ b/packages/terra-core-docs/src/terra-dev-site/common/layout-helpers/Whitespace.jsx
@@ -0,0 +1,39 @@
+import React from 'react';
+import PropTypes from 'prop-types';
+import classNames from 'classnames';
+import classNamesBind from 'classnames/bind';
+import styles from './Whitespace.module.scss';
+
+const cx = classNamesBind.bind(styles);
+
+const propTypes = {
+ /**
+ * Sets the height of a newline spacer, equivalent to number of lines based on lineheight, not fontsize.
+ * One of `1`, `2`, `3`, `4`, `5`, `6`, `7`, `8`, default is `1`.
+ */
+ newline: PropTypes.oneOf([1, 2, 3, 4, 5, 6, 7, 8]),
+};
+
+const defaultProps = {
+ newline: 1,
+};
+
+const Whitespace = ({
+ newline,
+ ...customProps
+}) => {
+ const WhitespaceClassNames = classNames(
+ cx(
+ 'whitespace',
+ `newline-${newline}`,
+ ),
+ customProps.className,
+ );
+
+ return
;
+};
+
+Whitespace.propTypes = propTypes;
+Whitespace.defaultProps = defaultProps;
+
+export default Whitespace;
diff --git a/packages/terra-core-docs/src/terra-dev-site/common/layout-helpers/Whitespace.module.scss b/packages/terra-core-docs/src/terra-dev-site/common/layout-helpers/Whitespace.module.scss
new file mode 100644
index 00000000000..0a56896412c
--- /dev/null
+++ b/packages/terra-core-docs/src/terra-dev-site/common/layout-helpers/Whitespace.module.scss
@@ -0,0 +1,48 @@
+/*
+ * SASS calculation
+ * based on lineheight of 20px (1.42857) for fontsize of 14px (1rem)
+ */
+@mixin terra-newline-height ($number-of-lines) {
+ height: 1.4285714286em * $number-of-lines;
+}
+
+:local {
+ .whitespace {
+ display: block;
+ margin: 0;
+ min-height: 0;
+ padding: 0;
+ }
+
+ .newline-1 {
+ @include terra-newline-height(1);
+ }
+
+ .newline-2 {
+ @include terra-newline-height(2);
+ }
+
+ .newline-3 {
+ @include terra-newline-height(3);
+ }
+
+ .newline-4 {
+ @include terra-newline-height(4);
+ }
+
+ .newline-5 {
+ @include terra-newline-height(5);
+ }
+
+ .newline-6 {
+ @include terra-newline-height(6);
+ }
+
+ .newline-7 {
+ @include terra-newline-height(7);
+ }
+
+ .newline-8 {
+ @include terra-newline-height(8);
+ }
+}
diff --git a/packages/terra-core-docs/src/terra-dev-site/doc/image/About.1.doc.mdx b/packages/terra-core-docs/src/terra-dev-site/doc/image/About.1.doc.mdx
index bb7518125bd..8dd4fb71231 100644
--- a/packages/terra-core-docs/src/terra-dev-site/doc/image/About.1.doc.mdx
+++ b/packages/terra-core-docs/src/terra-dev-site/doc/image/About.1.doc.mdx
@@ -2,6 +2,8 @@ import { Badge } from 'terra-image/package.json?dev-site-package';
import ImageDefault from './example/ImageDefault?dev-site-example';
import ImageFit from './example/ImageFitTypes?dev-site-example';
+import DecorativeImage from './example/DecorativeImage?dev-site-example';
+import InformativeImage from './example/InformativeImage?dev-site-example';
import ImagePropsTable from 'terra-image/src/Image?dev-site-props-table';
@@ -11,6 +13,36 @@ import ImagePropsTable from 'terra-image/src/Image?dev-site-props-table';
The terra-image component provides styling for visual imagery.
+
+# Informative Image
+
+Informative images are images that graphically represent concepts and information on a page. images are known as informative when they convey a concept or information of image with a short phrase or sentence.
+
+Images must have text alternatives described through `alt` prop which will provide the information or function represented by them. This will ensure that images are accessible for people with various disabilities.
+
+Images may be infomative when they are:
+- Used to label other information
+- Used to supplement other information
+- Conveying succinct information
+- Conveying an impression or emotion
+- Conveying file format
+
+
+# Decorative Image
+
+Decorative images are images that don’t add information to the content of a page but instead support existing content or are used plainly for aesthetics. For example, it can be an image depicting adjacent text or to make the website more visually attractive.
+
+Decorative Image should be used only when the purpose of an image is to add visual interest to the page, rather than to convey information that is important to understanding the page.
+
+Images may be decorative when they are:
+- Visual styling such as borders, spacers, and corners.
+- Supplementary to link text to improve its appearance or increase the clickable area.
+- Illustrative of adjacent text but not contributing information (“eye-candy”).
+- Identified and described by surrounding text.
+
+
+Provide a null text alternative (alt="") when the only purpose of an image is to add visual decoration to the page.
+
## Getting Started
- Install with [npmjs](https://www.npmjs.com):
@@ -42,6 +74,8 @@ import Image from 'terra-image';
## Examples
+
+
## Image Props
diff --git a/packages/terra-core-docs/src/terra-dev-site/doc/image/AccessibilityGuide.2.doc.mdx b/packages/terra-core-docs/src/terra-dev-site/doc/image/AccessibilityGuide.2.doc.mdx
new file mode 100644
index 00000000000..4b9033fb497
--- /dev/null
+++ b/packages/terra-core-docs/src/terra-dev-site/doc/image/AccessibilityGuide.2.doc.mdx
@@ -0,0 +1,317 @@
+import { Badge } from 'terra-image/package.json?dev-site-package';
+import { Notice } from '@cerner/terra-docs';
+import Whitespace from "../../common/layout-helpers/Whitespace";
+import A11yExampleInformative from './example/A11yExampleInformative';
+import A11yExampleInformativeConcise from './example/A11yExampleInformativeConcise';
+import A11yExampleDecorative from './example/DecorativeImage';
+
+
+
+# Accessibility Guide for Terra Image
+
+
+
+1. For each use of Terra Image, **special care needs to be taken to determine** whether it conveys **meaningful and informative context**, or is simply **adding visual decoration** to the page.
+2. Informative images **must provide alternative text to the alt attribute**. Writing **meaningful alternative text** is also critical to properly meet accessibility success criteria.
+3. Images set to be decorative need to ensure they are purely decorative, or the context must be provided already by other adjacent elements.
+
+
+
+
+
+### Why is this important?
+
+> Images and graphics make content more pleasant and easier to understand for many people, and in particular for those with cognitive and learning disabilities. They serve as cues that are used by people with visual impairments, including people with low vision, to orient themselves in the content.
+>
+> However, images are \[often\] used extensively on websites and can create major barriers when they are not accessible. Accessible images are beneficial in many situations, such as:
+>
+> - **People using screen readers:** The text alternative can be read aloud or rendered as Braille.
+> - **People using speech input software:** Users can put the focus onto a button or linked image with a single voice command.
+> - **People browsing speech-enabled websites:** The text alternative can be read aloud.
+> - **Mobile web users:** Images can be turned off, especially for data-roaming.
+> - **Search engine optimization:** Images become indexable by search engines.
+>
+> _ — excerpt from [Image Concepts (W3C: Web Accessibility Tutorials)](https://www.w3.org/WAI/tutorials/images/)_[[1]](/components/cerner-terra-core-docs/image/accessibility-guide#linked-references)
+
+
+
+## Accessibility Considerations:
+
+### Code Considerations
+
+> All non-text content must be represented in a text format in one way or another, whether in the form of an alt attribute for an image, an alternative representation of non-HTML objects, or within the accessibility API methods of non-HTML objects.
+>
+> _ — excerpt from [Summary and Checklist: Images, Canvas, SVG, and Other Non-Text Content (Deque)](https://dequeuniversity.com/assets/pdf/module-nontext/module-nontext-checklist.pdf)_[[2]](/components/cerner-terra-core-docs/image/accessibility-guide#linked-references)
+
+When using images, extra consideration needs to be taken for screen reader users that may be blind, have low vision, or have cognitive disabilities. Applications need to provide alternative non-visual descriptions for screen readers in the form of alt text. When a screen reader encounters an image, it will attempt to read the text alternative.[[3]](/components/cerner-terra-core-docs/image/accessibility-guide#linked-references)
+
+W3C (World Wide Web Consortium) divides images into seven concept categories for accessibility purposes:[[1]](/components/cerner-terra-core-docs/image/accessibility-guide#linked-references)
+
+- [Informative images](https://www.w3.org/WAI/tutorials/images/informative/)
+- [Decorative images](https://www.w3.org/WAI/tutorials/images/decorative/)
+- [Functional images](https://www.w3.org/WAI/tutorials/images/functional/)
+- [Images of text](https://www.w3.org/WAI/tutorials/images/textual/)
+- [Complex images](https://www.w3.org/WAI/tutorials/images/complex/)
+- [Groups of images](https://www.w3.org/WAI/tutorials/images/groups/)
+- [Images maps](https://www.w3.org/WAI/tutorials/images/imagemap/)
+
+Knowing which type of image and how to add proper alternative text appropriate for the usage type can be difficult. Use the [Alt Decision Tree (W3C)](https://www.w3.org/WAI/tutorials/images/decision-tree/) to help determine which usage is appropriate based on context and content of each image.
+
+The [Accessible Images When It Matters Most](https://accessibility.deque.com/accessible-images-when-it-matters-most) video presentation by Carie Fisher, Senior Accessibility Consultant at Deque, goes into depth about best practice techniques when creating accessible images and gives examples to help determine the appropiate image concept type.
+
+Terra Image handles two of the image concepts — **informative** images (also called _"meaningful"_ images) and **decoratiive** images (also called _"presentation"_ images). The other image concepts may be supported in the future or can be contructed by consumers following the reccomeneded patterns.
+
+----
+
+#### 1. When to use Image
+
+**Informative Images** graphically represent concepts and information, typically pictures, photos, and illustrations. Informative images convey a simple concept or information that can be expressed in a short phrase or sentence.[[1]](/components/cerner-terra-core-docs/image/accessibility-guide#linked-references)
+
+Informative Images **must have text alternatives provided by the alt attribute**, that describe the information or function represented by the image. This ensures that images can be used by people with various disabilities with help of assistive technologies. The text alternative should convey the meaning or content that is displayed visually, which typically isn't a literal description of the image. In some situations a detailed literal description may be needed, but only when the content of the image is all or part of the conveyed information.
+
+- When the image contributes meaning to the current page or context.
+- When the image is being used to suppliment and support other information.
+- When the image is an illustration, diagram, or photograph that shows directions or explains succint information.
+- When the image conveys an impression or emotion.
+
+
+
+
+
+**Accessibility Guidance: Creating Descriptive Alternative Text**
+
+_Example 1:_
+
+When deciding what to add for descriptive alternative text, consider how the image is being used and any surrounding content that helps to establish context.
+
+This image shows a photograph of the Matterhorn, but has no additional surrounding content, therefore the non-text content should be more descriptive and contain an objective description of the image shown. A recommended alternative text could be similar to: `alt="North-east face of the Matterhorn mountain peak and surrounding landscape covered in snow against a blue sky, located in the Swiss Apps near Zermatt, Switzerland"`.
+
+
+
+```diff
+ import React from 'react';
+ import Image from 'terra-image';
+ import matterhornImage from '../src/folder/Matterhorn_150x150.jpg';
+
++ const matterhornAlternativeText = 'North-east face of the Matterhorn
++ mountain peak and surrounding landscape covered in snow against a
++ blue sky, located in the Swiss Apps near Zermatt, Switzerland';
+
+ export default () => (
+ <>
+
+ Matterhorn
+ >
+ );
+```
+
+
+
+**Accessibility Guidance: Concise Alternative Text**
+
+_Example 2:_
+
+In this example, the photograph of the Matterhorn is accompanied by additional text that describes the information and gives context to the user that Matterhorn is a mountain peak located in the Alps near Zermatt, Switzerland. Since the context and description is already handled by the text, the alternative text can be more concise and the recommended text for this use would be: `alt="Matterhorn mountain peak"`.
+
+Additional guidance and examples can be read in [WebAIM's Alternative Text](https://webaim.org/techniques/alttext/) article, as well as the [Content Considerations](/components/cerner-terra-core-docs/image/accessibility-guide#content-considerations) section below.
+
+
+
+```diff
+ import React from 'react';
+ import Image from 'terra-image';
+ import matterhornImage from '../src/folder/Matterhorn_150x150.jpg';
+
++ const matterhornBriefAlternativeText = 'Matterhorn mountain peak';
+
+ export default () => (
+ <>
+
+ Matterhorn
++
++ Standing at 4,478 meters (14,692ft), Matterhorn is the fifth
++ highest peak in the Alps located on the border between Switzerland
++ and Italy, in the Monte Rosa area of the western Pennine Alps, and
++ overlooks the Swiss town of Zermatt.
++
+ >
+ );
+```
+
+
+
+**Additional WCAG Resources for Informative Images**
+- [G94: Providing short text alternative for non-text content that serves the same purpose and presents the same information as the non-text content](https://www.w3.org/WAI/WCAG21/Techniques/general/G94).
+- [H37: Using alt attributes on img elements](https://www.w3.org/WAI/WCAG21/Techniques/html/H37).
+
+
+
+----
+
+
+
+#### 2. When to use Decorative Image
+
+**Decorative Images** do not add information to the content of a page. For example, the information provided by the image might already be given using adjacent text, or the image might be included to make the website more visually attractive. The only purpose of an image is to add visual decoration to the page, rather than to convey information that is important to understanding the page.[[1]](/components/cerner-terra-core-docs/image/accessibility-guide#linked-references)
+
+Decorative images must have a null (empty) alt text (`alt=""`) so that they will be ignored by assistive technologies, such as screen readers. Any text values provided for these types of images would add audible clutter to screen reader output or could distract users if the topic is different from that in adjacent text. Leaving out the alt attribute is also not an option because when it is not provided, some screen readers will announce the file name of the image instead.
+
+To help with this, **Terra automatically adds the appropriate empty alt text** assignment for images that are decorative, and consumers should not provide alternative text when using `DecorativeImage`.
+
+- When the image is used as part of the page design.
+- When the image is helping to make something else easier to identify, but does not add to the information already provided.
+- When the image is used with adjacent already visible alternate text.
+- When the image is only shown for visual effects or ambiance (eye candy).
+
+
+
+
+
+**Accessibility Guidance: Adding Decorative Images**
+
+When an image is not part of the content and serves as visual reinforcement of structure that is already present in text, a Decorative Image is the appropriate choice. The example below is a composition that positions the image as a background behind the primary content. If the image were deleted, the important content would not be lost, since it already exists as text.
+
+The decorative image does not require adding alternative text, and the appropriate empty `alt=''` and `role='presentation'` attributes will be added automatically.
+
+
+
+```diff
+ import React from 'react';
+ import classNamesBind from 'classnames/bind';
+ import Image from 'terra-image';
+ import matterhornImage from '../src/folder/Matterhorn_960x640.jpg';
+ import styles from './BackgroundImageStyles.module.scss';
+
+ const cx = classNamesBind.bind(styles);
+
+ export default () => (
+
++
+
+
Matterhorn
+
+ Standing at 4,478 meters (14,692ft), Matterhorn is the fifth
+ highest peak in the Alps located on the border between Switzerland
+ and Italy, in the Monte Rosa area of the western Pennine Alps, and
+ overlooks the Swiss town of Zermatt.
+
+
+
+ );
+```
+
+
+
+**Additional WCAG Resources for Decorative Images**
+- [H2: Combining adjacent image and text links for the same resource](https://www.w3.org/WAI/WCAG21/Techniques/html/H2).
+- [H67: Using null alt text and no title attribute on img elements for images that AT should ignore](https://www.w3.org/WAI/WCAG21/Techniques/html/H67).
+
+
+
+
+----
+
+
+
+### Content Considerations
+
+As authors create alternative text descriptions for informative images — the content itself and choosing descriptive words and phrases is an equally important factor in ensuring proper accessibility in addition to the coding techniques listed above.
+
+
+#### Alternative Text
+
+These image description guidelines were developed by the Carl and Ruth Shapiro Family National Center for Accessible Media at WGBH (NCAM) in conjunction with the DIAGRAM Center (Digital Image And Graphic Resources for Accessible Materials) at Benetech.[[4]](/components/cerner-terra-core-docs/image/accessibility-guide#linked-references)
+
+> - _**Context is Key:**_ Survey the text surrounding an image to understand how it fits into the bigger picture. Use context to decide which basic concepts and terms have already been explained, and avoid repetition of explanations.
+> - _**Consider Your Audience:**_ Know your target reader (e.g. age, culture, subject-matter expertise). Use vocabulary and phrases appropriate for the reader.
+> - _**Be Concise:**_ More is NOT better - be succinct. Don't repeat information presented in the main or adjacent texts. Instead, direct readers to existing descriptions, when available (e.g. captions). Avoid introducing new concepts or terms.
+> - _**Be Objective:**_ Describe only what you see - physical appearances and actions rather than emotions and possible intentions. Don't interpret or analyze the material. Instead, allow readers to form their own opinions. Don't omit uncomfortable or controversial content, such as images associated with politics, religion, or sex.
+> - _**General to Specific:**_ Start with high-level context, and then drill down to details that enhance understanding. This provides the reader with options about how much information to read. Segment content into logical, digestible chunks.
+> - _**Tone and Language:**_ Apply the same writing style and terminology as the surrounding text. Write out abbreviations and symbols to ensure proper pronunciation by screen readers. Use descriptive vocabulary that adds meaning (e.g. “map” instead of “image”).
+>
+> _ — excerpts from [Image Description Guidelines (Diagram Center, A Benetech Initiative)](http://diagramcenter.org/table-of-contents-2.html)_[[4]](/components/cerner-terra-core-docs/image/accessibility-guide#linked-references)
+
+
+
+#### Additional Writing Resources and Content Strategies
+
+- [Deque » Blog: Accessibility Strategies for Your Content Team](https://www.deque.com/blog/accessibility-strategies-for-your-content-team/)
+- [Deque » Blog: How to Design Great Alt Text: An Introduction](https://www.deque.com/blog/great-alt-text-introduction/)
+- [Diagram Center (A Benetech Initiative) » Alternative Text Guidance by Image Type](http://diagramcenter.org/specific-guidelines-final-draft.html)
+- [WebAIM (Accessibility In Mind) » Alternative Text](https://webaim.org/techniques/alttext/)
+- [W3C Web Accessibility Initiative (WAI) » Tips: Writing for Web Accessibility](https://www.w3.org/WAI/tips/writing/#write-meaningful-text-alternatives-for-images)
+- [Yale University » Usability Best Practices: Images](https://usability.yale.edu/web-accessibility/articles/images)
+
+
+
+## Usability Expectations:
+
+### Interaction Details
+
+- **Informative images** are not interactive and do not respond to keyboard tab navigation or mouse/touch presses, but are expected to be read by screen readers and assistive technology.
+ - _Read more at [Informative Images (W3C: Web Accessibility Tutorials)](https://www.w3.org/WAI/tutorials/images/informative/)._
+- **Decorative images** should be ignored by screen readers and assistive technology and have no corresponding behaviors or interactions.
+ - _Read more at [Decorative Images (W3C: Web Accessibility Tutorials)](https://www.w3.org/WAI/tutorials/images/decorative/)._
+- **Functional images** that are interactive and used to initiate actions (e.g. as buttons, in hyperlinks, etc.) are not provided as a first-class feature of Terra Image. If Terra Image is used as a functional image, follow the recommended guidance for proper construction.
+ - _Read more at [functional Images (W3C: Web Accessibility Tutorials)](https://www.w3.org/WAI/tutorials/images/functional/)._
+
+### Keyboard Navigation
+
+Terra Image does not have any keyboard navigation expectations when used on its own.
+
+| Key/Sequence | Description |
+|---|---|
+|*none*| Has no keyboard navigation unless image is made to be interactive. |
+
+
+
+## Support Compliance:
+
+Terra is committed to ensuring its components provide maximum possible accessibility. However, using Terra components will not automatically make a product accessible.
+
+Final responsibility lies with the consumers of Terra components — ensuring proper usage, engineers following correct implementation patterns, and authors crafting content that follows best practice guidance — to make a product fully accessible.
+
+### WCAG Resources
+
+#### Success Criteria
+
+_Informative (non-decorative) usage of Terra Image **must** meet the following success criteria:_
+
+- [**1.1.1 Non-text Content**](https://www.w3.org/WAI/WCAG21/quickref/#non-text-content) - All non-text content that is presented to the user has a text alternative that serves the equivalent purpose, except for the situations listed\[...\]. (Level A)
+- [**1.4.5 Images of Text**](https://www.w3.org/WAI/WCAG21/quickref/#images-of-text) - If the technologies being used can achieve the visual presentation, text is used to convey information rather than images of text except \[for customizable and essential images\] (Level AA)
+- [**1.4.9 Images of Text (No Exception)**](https://www.w3.org/WAI/WCAG21/quickref/#images-of-text-no-exception) - Images of text are only used for pure decoration or where a particular presentation of text is essential to the information being conveyed (Level AAA)
+
+
+
+### Supported Features & Technology
+
+- JAWS Support with Chrome (PC)
+- NVDA Support with Chrome (PC)
+- VoiceOver Support with Chrome, Safari (MAC)
+- Mobile Touch Interactions with Screen Reader assistive technology
+- Speech Input Interactions with assistive technology
+
+### Partial Support & Requiring Further Enhancement
+
+- None identified
+- [Report a problem with this component on **GitHub**](https://github.com/cerner/terra-core/issues/new/choose)
+
+_For more information about Accessibility Support with Terra — go to [Component Standards: Accessibility (A11y)](https://engineering.cerner.com/terra-ui/about/terra-ui/component-standards#accessibility-a11y)._
+
+
+
+## Linked References:
+
+1. Eggert, Eric; Abou-Zahra, Shadi; et al. (27 July 2019). ["Web Accessibility Tutorials: Image Concepts"](https://www.w3.org/WAI/tutorials/images/). World Wide Web Consortium. Last updated 27 July 2019. Retrieved 2 March 2022.
+
+2. Deque staff (21 March 2019). ["Summary and Checklist: Images, Canvas, SVG, and Other Non-Text Content"](https://dequeuniversity.com/assets/pdf/module-nontext/module-nontext-checklist.pdf). Deque University. Publised Version 2019.03.21. Retrieved 2 March 2022.
+
+3. Yale staff (2022) ["Usability & Web Accessibility Articles: Images"](https://usability.yale.edu/web-accessibility/articles/images). Yale. Retrieved 2 March 2022.
+
+4. Benetech staff (June 2015). ["Image Description Guidelines"](http://diagramcenter.org/table-of-contents-2.html). Diagram Center, A Benetech Initiative. First published June 2015. Retrieved 2 March 2022.
diff --git a/packages/terra-core-docs/src/terra-dev-site/doc/image/ChangeLog.3.doc.mdx b/packages/terra-core-docs/src/terra-dev-site/doc/image/ChangeLog.4.doc.mdx
similarity index 100%
rename from packages/terra-core-docs/src/terra-dev-site/doc/image/ChangeLog.3.doc.mdx
rename to packages/terra-core-docs/src/terra-dev-site/doc/image/ChangeLog.4.doc.mdx
diff --git a/packages/terra-core-docs/src/terra-dev-site/doc/image/UpgradeGuide.2.doc.mdx b/packages/terra-core-docs/src/terra-dev-site/doc/image/UpgradeGuide.3.doc.mdx
similarity index 100%
rename from packages/terra-core-docs/src/terra-dev-site/doc/image/UpgradeGuide.2.doc.mdx
rename to packages/terra-core-docs/src/terra-dev-site/doc/image/UpgradeGuide.3.doc.mdx
diff --git a/packages/terra-core-docs/src/terra-dev-site/doc/image/assets/crocus.jpg b/packages/terra-core-docs/src/terra-dev-site/doc/image/assets/crocus.jpg
new file mode 100644
index 00000000000..322764f2399
Binary files /dev/null and b/packages/terra-core-docs/src/terra-dev-site/doc/image/assets/crocus.jpg differ
diff --git a/packages/terra-core-docs/src/terra-dev-site/doc/image/assets/decorative-bar.png b/packages/terra-core-docs/src/terra-dev-site/doc/image/assets/decorative-bar.png
new file mode 100644
index 00000000000..54332042dab
Binary files /dev/null and b/packages/terra-core-docs/src/terra-dev-site/doc/image/assets/decorative-bar.png differ
diff --git a/packages/terra-core-docs/src/terra-dev-site/doc/image/example/A11yExampleDecorativeImage.jsx b/packages/terra-core-docs/src/terra-dev-site/doc/image/example/A11yExampleDecorativeImage.jsx
new file mode 100644
index 00000000000..ac376ee3c5f
--- /dev/null
+++ b/packages/terra-core-docs/src/terra-dev-site/doc/image/example/A11yExampleDecorativeImage.jsx
@@ -0,0 +1,33 @@
+import React from 'react';
+import classNamesBind from 'classnames/bind';
+import Card from 'terra-card';
+import Image from 'terra-image';
+import matterhornBackgroundImage from '../../../../common/images/creative-commons/Matterhorn,_March_2019_(01)_960x640.jpg';
+import styles from './common/A11yExamples.module.scss';
+
+const cx = classNamesBind.bind(styles);
+
+const A11yExampleDecorativeImage = () => (
+
+
+
+
+
+ Matterhorn
+ Standing at 4,478 meters (14,692ft), Matterhorn is the fifth highest peak in the Alps located on the border between Switzerland and Italy, in the Monte Rosa area of the western Pennine Alps, and overlooks the Swiss town of Zermatt.
+
+
+ {'Photo Credit: '}
+ Liridon
+ {', '}
+ CC BY-SA 4.0
+ , via Wikimedia Commons
+
+
+
+
+
+
+);
+
+export default A11yExampleDecorativeImage;
diff --git a/packages/terra-core-docs/src/terra-dev-site/doc/image/example/A11yExampleInformative.jsx b/packages/terra-core-docs/src/terra-dev-site/doc/image/example/A11yExampleInformative.jsx
new file mode 100644
index 00000000000..a6efcc89e49
--- /dev/null
+++ b/packages/terra-core-docs/src/terra-dev-site/doc/image/example/A11yExampleInformative.jsx
@@ -0,0 +1,21 @@
+import React from 'react';
+import classNamesBind from 'classnames/bind';
+import Card from 'terra-card';
+import Image from 'terra-image';
+import matterhornImage from '../../../common/images/creative-commons/Matterhorn,_March_2019_(01)_150x150.jpg';
+import styles from './common/A11yExamples.module.scss';
+
+const cx = classNamesBind.bind(styles);
+
+const matterhornAlternativeText = 'North-east face of the Matterhorn mountain peak and surrounding landscape covered in snow against a blue sky, located in the Swiss Apps near Zermatt, Switzerland';
+
+const A11yGuideInformativeImage = () => (
+
+
+
+ Matterhorn
+
+
+);
+
+export default A11yGuideInformativeImage;
diff --git a/packages/terra-core-docs/src/terra-dev-site/doc/image/example/A11yExampleInformativeConcise.jsx b/packages/terra-core-docs/src/terra-dev-site/doc/image/example/A11yExampleInformativeConcise.jsx
new file mode 100644
index 00000000000..8c916e67a96
--- /dev/null
+++ b/packages/terra-core-docs/src/terra-dev-site/doc/image/example/A11yExampleInformativeConcise.jsx
@@ -0,0 +1,29 @@
+import React from 'react';
+import classNamesBind from 'classnames/bind';
+import Card from 'terra-card';
+import Image from 'terra-image';
+import matterhornImage from '../../../common/images/creative-commons/Matterhorn,_March_2019_(01)_150x150.jpg';
+import styles from './common/A11yExamples.module.scss';
+
+const cx = classNamesBind.bind(styles);
+
+const matterhornAlternativeText = 'Matterhorn mountain peak';
+
+export default () => (
+
+
+
+ Matterhorn
+ Standing at 4,478 meters (14,692ft), Matterhorn is the fifth highest peak in the Alps located on the border between Switzerland and Italy, in the Monte Rosa area of the western Pennine Alps, and overlooks the Swiss town of Zermatt.
+
+
+ {'Photo Credit: '}
+ Liridon
+ {', '}
+ CC BY-SA 4.0
+ , via Wikimedia Commons
+
+
+
+
+);
diff --git a/packages/terra-core-docs/src/terra-dev-site/doc/image/example/DecorativeImage.jsx b/packages/terra-core-docs/src/terra-dev-site/doc/image/example/DecorativeImage.jsx
new file mode 100644
index 00000000000..41f33a637c5
--- /dev/null
+++ b/packages/terra-core-docs/src/terra-dev-site/doc/image/example/DecorativeImage.jsx
@@ -0,0 +1,18 @@
+import React from 'react';
+import Image from 'terra-image';
+import decorativeBar from '../assets/decorative-bar.png';
+import crocus from '../assets/crocus.jpg';
+
+const DecorativeImageBar = () => (
+
+
Image used as part of page design.
+
This image is used as a border in the page design and has a purely decorative purpose.
+
+
Image as part of a text link.
+
This illustration of a crocus bulb is used to make the link easier to identify and to increase the clickable area but doesn’t add to the information already provided in the adjacent link text (of the same anchor). In this case, alt value for the image would be `null` / `empty`.
+
+
Crocus bulbs
+
+);
+
+export default DecorativeImageBar;
diff --git a/packages/terra-core-docs/src/terra-dev-site/doc/image/example/InformativeImage.jsx b/packages/terra-core-docs/src/terra-dev-site/doc/image/example/InformativeImage.jsx
new file mode 100644
index 00000000000..72babfefdbb
--- /dev/null
+++ b/packages/terra-core-docs/src/terra-dev-site/doc/image/example/InformativeImage.jsx
@@ -0,0 +1,15 @@
+import React from 'react';
+import Image from 'terra-image';
+import matterhornImage from '../../../common/images/creative-commons/Matterhorn,_March_2019_(01)_150x150.jpg';
+
+const matterhornAlternativeText = 'North-east face of the Matterhorn mountain peak and surrounding landscape covered in snow against a blue sky, located in the Swiss Apps near Zermatt, Switzerland';
+
+const InformativeImage = () => (
+
+
Information provided using Image.
+
+
Matterhorn
+
+);
+
+export default InformativeImage;
diff --git a/packages/terra-core-docs/src/terra-dev-site/doc/image/example/common/A11yExamples.module.scss b/packages/terra-core-docs/src/terra-dev-site/doc/image/example/common/A11yExamples.module.scss
new file mode 100644
index 00000000000..b256e3d2704
--- /dev/null
+++ b/packages/terra-core-docs/src/terra-dev-site/doc/image/example/common/A11yExamples.module.scss
@@ -0,0 +1,72 @@
+:local {
+ .card {
+ width: 100%;
+ }
+
+ .informative-example {
+ font-size: 0.85rem;
+ margin-left: auto;
+ margin-right: auto;
+ max-width: 40rem;
+ padding: 0.25rem 1rem 0;
+ text-align: center;
+ width: 100%;
+ }
+
+ .image {
+ margin: 0 auto;
+ }
+
+ .title {
+ display: block;
+ font-size: 1.1em;
+ margin-bottom: 0.25em;
+ margin-top: 0.5em;
+ }
+
+ .cite {
+ display: block;
+ margin-top: 0.25em;
+ }
+
+ .decorative-example {
+ min-height: 240px;
+ position: relative;
+ width: 100%;
+
+ .background {
+ height: 240px;
+ width: 100%;
+ }
+
+ .foreground {
+ padding: 20px;
+ position: absolute;
+ top: 0;
+ width: 100%;
+ }
+
+ .card {
+ opacity: 0.85;
+ }
+ }
+
+ .decorative-text-container {
+ font-size: 0.85rem;
+ padding-left: 1rem;
+ padding-right: 1rem;
+ text-align: center;
+ }
+
+ @media screen and (min-width: 544px) {
+ .informative-example {
+ font-size: 1rem;
+ }
+
+ .decorative-text-container {
+ font-size: 1rem;
+ padding-left: 3rem;
+ padding-right: 3rem;
+ }
+ }
+}
diff --git a/packages/terra-image/CHANGELOG.md b/packages/terra-image/CHANGELOG.md
index 8fb84829943..1829459c25a 100644
--- a/packages/terra-image/CHANGELOG.md
+++ b/packages/terra-image/CHANGELOG.md
@@ -2,6 +2,9 @@
## Unreleased
+* Added
+ * Added support for decorative images.
+
## 3.36.0 - (December 7, 2022)
* Changed
diff --git a/packages/terra-image/src/Image.jsx b/packages/terra-image/src/Image.jsx
index 8c6831f772e..5edde76c79d 100644
--- a/packages/terra-image/src/Image.jsx
+++ b/packages/terra-image/src/Image.jsx
@@ -5,24 +5,12 @@ import classNames from 'classnames';
import classNamesBind from 'classnames/bind';
import ThemeContext from 'terra-theme-context';
import styles from './Image.module.scss';
+import {
+ getDecorativeImage, getInformativeImage, ImageVariant, FitTypes,
+} from './_imageHelper';
const cx = classNamesBind.bind(styles);
-const ImageVariant = {
- DEFAULT: 'default',
- ROUNDED: 'rounded',
- CIRCLE: 'circle',
- THUMBNAIL: 'thumbnail',
-};
-
-const FitTypes = {
- COVER: 'cover',
- SCALEDOWN: 'scale-down',
- FILL: 'fill',
- CONTAIN: 'contain',
- NONE: 'none',
-};
-
const propTypes = {
/**
* The source string for the image which will be loaded and displayed.
@@ -37,9 +25,12 @@ const propTypes = {
*/
isFluid: PropTypes.bool,
/**
+ * 
* The text content that specifies an alternative text for an image.
+ * `alt` prop helps to provide meaningfull context for images and should be used for creating informative images. For decorative images `alt` prop can be ignored.
+ * whenever `alt` prop is empty OR not defined image will be marked as decorative by default and ignored by Assistive Tools.
*/
- alt: PropTypes.string.isRequired,
+ alt: PropTypes.string,
/**
* A React element which will be displayed during loading and in case of src load failure.
*/
@@ -66,14 +57,11 @@ const propTypes = {
fit: PropTypes.oneOf(['cover', 'scale-down', 'fill', 'contain', 'none']),
};
-/* eslint-disable react/default-props-match-prop-types */
const defaultProps = {
variant: 'default',
isFluid: false,
- alt: ' ',
fit: 'fill',
};
-/* eslint-enable react/default-props-match-prop-types */
class Image extends React.Component {
constructor(props) {
@@ -128,10 +116,13 @@ class Image extends React.Component {
createImage(customProps, imageClasses) {
const {
src, alt, height, width,
- } = this.props;
+ } = customProps;
+
+ const imageProps = (alt !== undefined && alt?.trim() !== '') ? getInformativeImage(customProps) : getDecorativeImage(customProps);
+
return (
{
+ const customProps = { ...props };
+ // removes Aria attributes, role and title from customProps
+ Object.keys(customProps).forEach(prop => {
+ if (prop.includes('aria') || prop === 'title' || prop === 'role') {
+ delete customProps[prop];
+ }
+ });
+
+ return { ...customProps, role: 'presentation' };
+};
+
+const getInformativeImage = (props) => {
+ const informativeImageProps = { ...props };
+ // removes role attribute if the value is set to `presentation` OR `none`
+ if (informativeImageProps.role && (informativeImageProps.role === 'presentation' || informativeImageProps.role === 'none')) {
+ delete informativeImageProps.role;
+ }
+
+ return { ...informativeImageProps };
+};
+
+export {
+ FitTypes, ImageVariant, getInformativeImage, getDecorativeImage,
+};
diff --git a/packages/terra-image/tests/jest/Image.test.jsx b/packages/terra-image/tests/jest/Image.test.jsx
index fb763b909b8..07e499dd874 100644
--- a/packages/terra-image/tests/jest/Image.test.jsx
+++ b/packages/terra-image/tests/jest/Image.test.jsx
@@ -12,9 +12,10 @@ const imagecontainerStyle1 = {
const image = ;
/* Default component */
-it('should render a default component', () => {
+it('should render a default component with decorative image attributes', () => {
const wrapper = shallow();
expect(wrapper.instance().props.alt).toEqual(' ');
+ expect(wrapper).toMatchSnapshot();
});
/* Default component with a height and width */
@@ -97,6 +98,24 @@ it('should render the placeholder image', () => {
expect(wrapper).toMatchSnapshot();
});
+/* Ignores roles passed for decorative images */
+it('should ignore provided role and render image with default decorative image role', () => {
+ const wrapper = shallow();
+ expect(wrapper).toMatchSnapshot();
+});
+
+/* Ignores Aria and title attributes passed for decorative images */
+it('should ignore Aria and title attribute for decorative image', () => {
+ const wrapper = shallow();
+ expect(wrapper).toMatchSnapshot();
+});
+
+/* Ignores decorative roles passed for informative images */
+it('should render image without decorative image role', () => {
+ const wrapper = shallow();
+ expect(wrapper).toMatchSnapshot();
+});
+
it('correctly applies the theme context className', () => {
const wrapper = mount(
diff --git a/packages/terra-image/tests/jest/__snapshots__/Image.test.jsx.snap b/packages/terra-image/tests/jest/__snapshots__/Image.test.jsx.snap
index 97984a3a9d5..1f29939a717 100644
--- a/packages/terra-image/tests/jest/__snapshots__/Image.test.jsx.snap
+++ b/packages/terra-image/tests/jest/__snapshots__/Image.test.jsx.snap
@@ -20,12 +20,39 @@ exports[`correctly applies the theme context className 1`] = `
className="image fill default orion-fusion-theme"
onError={[Function]}
onLoad={[Function]}
+ role="presentation"
src=""
/>
`;
+exports[`should ignore Aria and title attribute for decorative image 1`] = `
+
+`;
+
+exports[`should ignore provided role and render image with default decorative image role 1`] = `
+
+`;
+
exports[`should render a circle image component with fluid behavior 1`] = `
`;
+exports[`should render a default component with decorative image attributes 1`] = `
+
![]()
+`;
+
exports[`should render a hidden src image and a visible placeholder image 1`] = `
@@ -79,6 +118,18 @@ exports[`should render a thumbail image component with non-fluid behavior 1`] =
/>
`;
+exports[`should render image without decorative image role 1`] = `
+
+`;
+
exports[`should render the placeholder image 1`] = `
placeholder text