diff --git a/packages/terra-alert/CHANGELOG.md b/packages/terra-alert/CHANGELOG.md index a6ad5b97af0..4ced5cb7fc3 100644 --- a/packages/terra-alert/CHANGELOG.md +++ b/packages/terra-alert/CHANGELOG.md @@ -2,6 +2,9 @@ ## Unreleased +* Changed + * Jest snapshots updated due to decorative / informative icon changes in terra-icon. + ## 4.62.0 - (January 9, 2023) * Changed diff --git a/packages/terra-alert/tests/jest/__snapshots__/Alert.test.jsx.snap b/packages/terra-alert/tests/jest/__snapshots__/Alert.test.jsx.snap index 69369f46230..28bb44f2623 100644 --- a/packages/terra-alert/tests/jest/__snapshots__/Alert.test.jsx.snap +++ b/packages/terra-alert/tests/jest/__snapshots__/Alert.test.jsx.snap @@ -171,7 +171,6 @@ exports[`Alert of type alert with text content should render an Alert component xmlns="http://www.w3.org/2000/svg" >
+ + +
+``` +Refer to [Accessibility guide](https://engineering.cerner.com/terra-ui/components/cerner-terra-core-docs/icon/AccessibilityGuide) to know more about informative and decorative icons. + ## Component Features * [Cross-Browser Support](https://engineering.cerner.com/terra-ui/about/terra-ui/component-standards#cross-browser-support) * [Responsive Support](https://engineering.cerner.com/terra-ui/about/terra-ui/component-standards#responsive-support) diff --git a/packages/terra-core-docs/src/terra-dev-site/doc/icon/AccessibilityGuide.2.doc.mdx b/packages/terra-core-docs/src/terra-dev-site/doc/icon/AccessibilityGuide.2.doc.mdx new file mode 100644 index 00000000000..9552a2c4a30 --- /dev/null +++ b/packages/terra-core-docs/src/terra-dev-site/doc/icon/AccessibilityGuide.2.doc.mdx @@ -0,0 +1,238 @@ +import { Notice } from "@cerner/terra-docs"; +import { Badge } from 'terra-image/package.json?dev-site-package'; +import Whitespace from '../../common/layout-helpers/Whitespace'; + +import A11yMeaningfulReadOnly from './example/A11yMeaningfulReadOnly'; +import A11yGroupInteractive from './example/A11yGroupInteractive'; +import A11yDecorative from './example/A11yDecorative'; +import A11yGroupReadOnly from './example/A11yGroupReadOnly'; +import A11yMeaningfulInteractive from './example/A11yMeaningfulInteractive'; + +import IconAudio from 'terra-icon/lib/icon/IconAudio'; +import IconAnnouncement from "terra-icon/lib/icon/IconAnnouncement"; + +import FilledStar from 'terra-icon/lib/icon/IconFeaturedOutlineYellow'; +import EmptyStar from 'terra-icon/lib/icon/IconFeaturedOff'; + +import FilledDecorativeStar from 'terra-icon/lib/icon/IconFeaturedOutlineYellow'; +import EmptyDecorativeStar from 'terra-icon/lib/icon/IconFeaturedOff'; +import VisuallyHiddenText from 'terra-visually-hidden-text'; + + + +# Accessibility Guide for Terra Icon + + + +Using icons improperly may prevent some of your users from understanding your UI. + + + + + +## Why is this important? + +Icons are a type of image or graphic, and as such: + +> 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 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 +> +> _  — excerpt from [Image Concepts (W3C: Web Accessibility Tutorials)](https://www.w3.org/WAI/tutorials/images/)_[[1]](/components/cerner-terra-core-docs/icon/accessibility-guide#linked-references) + +## Accessibility Considerations + +### Code Considerations + +Every Terra Icon has two variants: _Meaningful_ and _Decorative_. The table below explains the difference between the two, and how to import them into your code. + +| Variant | Purpose | Example | +| --- | --- | --- | +| Meaningful | Convey information to the user and must provide a text alternative via the `a11yLabel` prop. | `` | +| Decorative | Only for aesthetic purposes. | `` | + +The following sections go into more detail about when and how to use each variant. + +---- + +#### When to use _Meaningful Icons_ + +Meaningful icons are icons that convey information to the user. **Meaningful icons must provide an alternative text using the `a11yLabel` prop**. + +> 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/icon/accessibility-guide#linked-references) + +You should pick an `a11yLabel` that conveys the same information that a user viewing the icons would perceive. That way, no information will be hidden from a user who cannot view the icon with the text. + + + + + +###### Accessibility Guidance: Using meaningful icons + +
+ +
+
+ + import IconAnnouncement from 'terra-icon/lib/icon/IconAnnouncement'; + + // Set the a11yLabel to convey the meaning of the icon. + +   + Facilities will be closed tomorrow. + +
+ +The announcement icon () in this example is informative, because it means _the following text is an announcement_. However, that meaning is only conveyed if the user can see the icon. Setting the icon's `a11yLabel="Announcement"` conveys the same information to a screen reader user. + +The screen reader user will hear something like: Image: Announcement. Facilities will be closed tomorrow. + +###### Accessibility Guidance: Interactive meaningful icons + +
+ +
+
+ + import IconMediaPlay from 'terra-icon/lib/icon/IconMediaPlay'; + import IconMediaFastForward from 'terra-icon/lib/icon/IconMediaFastForward'; + import IconMediaRewind from 'terra-icon/lib/icon/IconMediaRewind'; + +
+ Playback controls
+ + + +
+ +
+ +The screen reader user will hear something like: Group: Playback Controls. Button image Rewind. Button image Play. Button image Fast Forward. + + + +#### Groups of Meaningful Icons + +Some icons only make sense in the context of a group of icons. For example, in a five-star rating system each star icon only makes sense when used with the other four stars. + + + +###### Accessibility Guidance: Using groups of icons + +
+ +
+
+ import DecorativeStar from "terra-icon/lib/icon/IconFeaturedOutlineYellow"; + import DecorativeEmptyStar from "terra-icon/lib/icon/IconFeaturedOutline"; + import Star from "terra-icon/lib/icon/IconFeaturedOutlineYellow"; + + Rating:  + + + + + + +
+ +The first star icon () is meaningful and conveys the rating to the screen reader user. The other icons ( and ) are decorative so that the screen reader won't mention them. Mentioning the other icons in the group provides no benefit and serves only to confuse the user. +The screen reader user will hear something like: Rating. Four out of five stars. + +###### Accessibility Guidance: An interactive group of icons + +
+ +
+
+ + import Star from 'terra-icon/lib/icon/IconFeaturedOutlineYellow'; + import EmptyStar from 'terra-icon/lib/icon/IconFeaturedOutline'; + import VisuallyHiddenText from 'terra-visually-hidden-text'; + + Rating:  + + + + + + + +
+ +This example shows important differences in how to handle an interactive group of icons: That the user can click on any of the stars (links) to change the rating. You must convey what will happen when the user clicks on each icon. The meaning of the rating is conveyed by the `` given first. Each star icon ( and ) describes its own action, e.g. rating an item one star. + +The screen reader user will hear: Rating: Four out of five stars. Button image Rate one star. Button image Rate two stars. Button image Rate three stars. Button image Rate four stars. Button image Rate five stars. + + + +#### When to use Decorative Icons + +Decorative icons provide no additional information or context. Use decorative icons when you could remove the icon entirely from the content without losing any information. + +* You do not set the `a11yLabel` prop when using a decorative icon. +* Decorative icons are ignored by screen readers and other assistive tech. + + + +###### Accessibility Guidance: Using decorative icons + +
+ +
+
+ + import IconAnnouncement from "terra-icon/lib/icon/IconAnnouncement"; + + +   + Announcement: Facilities will be closed tomorrow. + +
+ +This example is similar to the Announcement example above, but it uses a decorative icon instead of a meaningful one. The decorative icon is ignored by the screen reader. The screen reader user will hear something like: Announcement: Facilities will be closed tomorrow. + + + +## Usability Expectations + +### Interaction Details + +None + +### Keyboard Navigation + +None + +## 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 Icon **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) + +### 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. Published Version 2019.03.21. Retrieved 2 March 2022. diff --git a/packages/terra-core-docs/src/terra-dev-site/doc/icon/Static.2.doc.mdx b/packages/terra-core-docs/src/terra-dev-site/doc/icon/Static.3.doc.mdx similarity index 100% rename from packages/terra-core-docs/src/terra-dev-site/doc/icon/Static.2.doc.mdx rename to packages/terra-core-docs/src/terra-dev-site/doc/icon/Static.3.doc.mdx diff --git a/packages/terra-core-docs/src/terra-dev-site/doc/icon/Themeable.3.doc.mdx b/packages/terra-core-docs/src/terra-dev-site/doc/icon/Themeable.4.doc.mdx similarity index 100% rename from packages/terra-core-docs/src/terra-dev-site/doc/icon/Themeable.3.doc.mdx rename to packages/terra-core-docs/src/terra-dev-site/doc/icon/Themeable.4.doc.mdx diff --git a/packages/terra-core-docs/src/terra-dev-site/doc/icon/UpgradeGuide.4.doc.mdx b/packages/terra-core-docs/src/terra-dev-site/doc/icon/UpgradeGuide.5.doc.mdx similarity index 100% rename from packages/terra-core-docs/src/terra-dev-site/doc/icon/UpgradeGuide.4.doc.mdx rename to packages/terra-core-docs/src/terra-dev-site/doc/icon/UpgradeGuide.5.doc.mdx diff --git a/packages/terra-core-docs/src/terra-dev-site/doc/icon/example/A11yDecorative.jsx b/packages/terra-core-docs/src/terra-dev-site/doc/icon/example/A11yDecorative.jsx new file mode 100644 index 00000000000..2e1a1fb6a5f --- /dev/null +++ b/packages/terra-core-docs/src/terra-dev-site/doc/icon/example/A11yDecorative.jsx @@ -0,0 +1,17 @@ +// This file is autogenerated from scripts/src/generate-example +import React from 'react'; +import DecorativeIconAnnouncement from 'terra-icon/lib/icon/IconAnnouncement'; +import Card from 'terra-card'; +import { width, height } from './common'; + +const A11yDecorative = () => ( + + + +   + Announcement: Facilities will be closed tomorrow. + + +); + +export default A11yDecorative; diff --git a/packages/terra-core-docs/src/terra-dev-site/doc/icon/example/A11yGroupInteractive.jsx b/packages/terra-core-docs/src/terra-dev-site/doc/icon/example/A11yGroupInteractive.jsx new file mode 100644 index 00000000000..4f635047251 --- /dev/null +++ b/packages/terra-core-docs/src/terra-dev-site/doc/icon/example/A11yGroupInteractive.jsx @@ -0,0 +1,32 @@ +import React from 'react'; +import Star from 'terra-icon/lib/icon/IconFeaturedOutlineYellow'; +import EmptyStar from 'terra-icon/lib/icon/IconFeaturedOutline'; +import VisuallyHiddenText from 'terra-visually-hidden-text'; +import Card from 'terra-card'; +import { width, height } from './common'; + +const A11yGroupInteractive = () => ( + + + Rating:  + + + + + + + + +); + +export default A11yGroupInteractive; diff --git a/packages/terra-core-docs/src/terra-dev-site/doc/icon/example/A11yGroupReadOnly.jsx b/packages/terra-core-docs/src/terra-dev-site/doc/icon/example/A11yGroupReadOnly.jsx new file mode 100644 index 00000000000..5b90d4a6a7a --- /dev/null +++ b/packages/terra-core-docs/src/terra-dev-site/doc/icon/example/A11yGroupReadOnly.jsx @@ -0,0 +1,22 @@ +// This file is autogenerated from scripts/src/generate-example +import React from 'react'; +import Star from 'terra-icon/lib/icon/IconFeaturedOutlineYellow'; +import DecorativeEmptyStar from 'terra-icon/lib/icon/IconFeaturedOutline'; +import Card from 'terra-card'; +import { width, height } from './common'; + +const InformativeStar = (); +const DecorativeStar = (); +const A11yGroupReadOnly = () => ( + + + Rating:  + {InformativeStar} + {DecorativeStar} + {DecorativeStar} + + + +); + +export default A11yGroupReadOnly; diff --git a/packages/terra-core-docs/src/terra-dev-site/doc/icon/example/A11yMeaningfulInteractive.jsx b/packages/terra-core-docs/src/terra-dev-site/doc/icon/example/A11yMeaningfulInteractive.jsx new file mode 100644 index 00000000000..769a731051f --- /dev/null +++ b/packages/terra-core-docs/src/terra-dev-site/doc/icon/example/A11yMeaningfulInteractive.jsx @@ -0,0 +1,29 @@ +// This file is autogenerated from scripts/src/generate-example +import React from 'react'; +import Card from 'terra-card'; +import IconMediaPlay from 'terra-icon/lib/icon/IconMediaPlay'; +import IconMediaFastForward from 'terra-icon/lib/icon/IconMediaFastForward'; +import IconMediaRewind from 'terra-icon/lib/icon/IconMediaRewind'; +import { width, height } from './common'; + +const A11yMeaningfulInteractive = () => ( + + +
+ Playback controls +
+ + + +
+ + +); + +export default A11yMeaningfulInteractive; diff --git a/packages/terra-core-docs/src/terra-dev-site/doc/icon/example/A11yMeaningfulReadOnly.jsx b/packages/terra-core-docs/src/terra-dev-site/doc/icon/example/A11yMeaningfulReadOnly.jsx new file mode 100644 index 00000000000..9745f477eb4 --- /dev/null +++ b/packages/terra-core-docs/src/terra-dev-site/doc/icon/example/A11yMeaningfulReadOnly.jsx @@ -0,0 +1,19 @@ +import React from 'react'; +import IconAnnouncement from 'terra-icon/lib/icon/IconAnnouncement'; +import Card from 'terra-card'; +import { width, height } from './common'; + +const A11yMeaningfulReadOnly = () => ( + + + +   Facilities will be closed tomorrow. + + +); + +export default A11yMeaningfulReadOnly; diff --git a/packages/terra-core-docs/src/terra-dev-site/doc/icon/example/common.js b/packages/terra-core-docs/src/terra-dev-site/doc/icon/example/common.js new file mode 100644 index 00000000000..4007bd137bf --- /dev/null +++ b/packages/terra-core-docs/src/terra-dev-site/doc/icon/example/common.js @@ -0,0 +1,2 @@ +export const height = '2em'; +export const width = height; diff --git a/packages/terra-form-field/CHANGELOG.md b/packages/terra-form-field/CHANGELOG.md index 962d17b939e..34126636925 100644 --- a/packages/terra-form-field/CHANGELOG.md +++ b/packages/terra-form-field/CHANGELOG.md @@ -2,6 +2,9 @@ ## Unreleased +* Changed + * Jest snapshots updated due to decorative / informative icon changes in terra-icon. + ## 4.22.0 - (January 9, 2023) * Changed diff --git a/packages/terra-form-field/tests/jest/__snapshots__/Field.test.jsx.snap b/packages/terra-form-field/tests/jest/__snapshots__/Field.test.jsx.snap index 3089204a814..ccb05714027 100644 --- a/packages/terra-form-field/tests/jest/__snapshots__/Field.test.jsx.snap +++ b/packages/terra-form-field/tests/jest/__snapshots__/Field.test.jsx.snap @@ -74,7 +74,6 @@ exports[`correctly applies the theme context className 1`] = ` xmlns="http://www.w3.org/2000/svg" >