From fb2fd895708ec18093991413bbb4322f28e7783f Mon Sep 17 00:00:00 2001 From: MadanKumarGovindaswamy Date: Fri, 27 Oct 2023 16:09:41 +0530 Subject: [PATCH 01/12] Update: Terra-Badge Doc update --- .../terra-dev-site/doc/badge/About.1.doc.mdx | 18 ++++- .../doc/badge/example/BadgeInTable.jsx | 2 +- .../doc/badge/example/BadgeIntent.jsx | 80 ++++++++++++++----- 3 files changed, 79 insertions(+), 21 deletions(-) diff --git a/packages/terra-core-docs/src/terra-dev-site/doc/badge/About.1.doc.mdx b/packages/terra-core-docs/src/terra-dev-site/doc/badge/About.1.doc.mdx index a9b45c3b4fb..21ab8bd7cac 100644 --- a/packages/terra-core-docs/src/terra-dev-site/doc/badge/About.1.doc.mdx +++ b/packages/terra-core-docs/src/terra-dev-site/doc/badge/About.1.doc.mdx @@ -12,7 +12,7 @@ import BadgePropsTable from 'terra-badge/lib/Badge?dev-site-props-table'; # Terra Badge -The badge component displays content classification. +Badges are used to represent items like number of filtered items, number of unread items, or to represent state. If you need a selectable annotation consider using a label instead. ## Getting Started @@ -43,6 +43,22 @@ The Badge component must be composed inside the [Base][1] component with a local import Badge from 'terra-badge'; ``` +To implement an accessible terra badge: + +- Ensure a meaningful text is provided as `text` prop for terra-badge and choose appropriate intent that matches the defination of Badge text. + +- Ensure Information is not conveyed by only color added by different intent of terra-badge. + +- Ensure that the terra-badge is provided with visually hidden text to convey the purpose of the badge to users via screen reader or similar assistive technologies when required. + +- When multiple badges are used together, Consider following steps which will help users to perceive or understand the difference between the two badges. + + - Add an icon to visually convey information. + - Add a visually-hidden-text to convey information for screen reader users. + - Avoid having badges with similar intent on group. + +- visually-hidden-text should be ignored when the badge color and text is sufficient to convey information of badge. + ## 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/badge/example/BadgeInTable.jsx b/packages/terra-core-docs/src/terra-dev-site/doc/badge/example/BadgeInTable.jsx index 19f69b6d8b9..267bd175d07 100644 --- a/packages/terra-core-docs/src/terra-dev-site/doc/badge/example/BadgeInTable.jsx +++ b/packages/terra-core-docs/src/terra-dev-site/doc/badge/example/BadgeInTable.jsx @@ -45,7 +45,7 @@ const BadgeInTable = () => (
- +
diff --git a/packages/terra-core-docs/src/terra-dev-site/doc/badge/example/BadgeIntent.jsx b/packages/terra-core-docs/src/terra-dev-site/doc/badge/example/BadgeIntent.jsx index 4537a7a5290..dffaeb5b12e 100644 --- a/packages/terra-core-docs/src/terra-dev-site/doc/badge/example/BadgeIntent.jsx +++ b/packages/terra-core-docs/src/terra-dev-site/doc/badge/example/BadgeIntent.jsx @@ -6,29 +6,71 @@ import styles from './Badge.module.scss'; const cx = classNames.bind(styles); const BadgeIntent = () => ( -
-
- + +

+ Intent with severity of issues. +

+
+
+ +
+
+ +
+
+ +
+
+ +
+
+ +
-
- +

+ Secondary Intent can be used to label user name as NEW +

+
+
+ Segun Adebayo + +
-
- +

+ Primary Intent with unread items +

+
+
+ +
+
+ +
+
+ +
+
+ +
-
- +

+ Default Intent with read items +

+
+
+ +
+
+ +
+
+ +
+
+ +
-
- -
-
- -
-
- -
-
+ ); export default BadgeIntent; From 7f8df1557cb809aaf8b3536bcb878372ee51afaa Mon Sep 17 00:00:00 2001 From: MadanKumarGovindaswamy Date: Fri, 27 Oct 2023 16:52:08 +0530 Subject: [PATCH 02/12] Update CHANGELOG.md --- packages/terra-core-docs/CHANGELOG.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/packages/terra-core-docs/CHANGELOG.md b/packages/terra-core-docs/CHANGELOG.md index af8ebf9db10..3f997b64294 100644 --- a/packages/terra-core-docs/CHANGELOG.md +++ b/packages/terra-core-docs/CHANGELOG.md @@ -2,6 +2,9 @@ ## Unreleased +* Updated + * Updated doc examples for `terra-badge`. + ## 1.47.0 - (October 26, 2023) * Changed From 15696b5df48003a0fc4337510f9b1927be79e943 Mon Sep 17 00:00:00 2001 From: MadanKumarGovindaswamy Date: Tue, 31 Oct 2023 14:38:52 +0530 Subject: [PATCH 03/12] Update: terra badge doc update --- .../terra-dev-site/doc/badge/About.1.doc.mdx | 2 +- .../doc/badge/example/Badge.module.scss | 23 +++++++++++- .../doc/badge/example/BadgeIntent.jsx | 35 +++++++------------ 3 files changed, 35 insertions(+), 25 deletions(-) diff --git a/packages/terra-core-docs/src/terra-dev-site/doc/badge/About.1.doc.mdx b/packages/terra-core-docs/src/terra-dev-site/doc/badge/About.1.doc.mdx index 21ab8bd7cac..8b7b0e4a564 100644 --- a/packages/terra-core-docs/src/terra-dev-site/doc/badge/About.1.doc.mdx +++ b/packages/terra-core-docs/src/terra-dev-site/doc/badge/About.1.doc.mdx @@ -12,7 +12,7 @@ import BadgePropsTable from 'terra-badge/lib/Badge?dev-site-props-table'; # Terra Badge -Badges are used to represent items like number of filtered items, number of unread items, or to represent state. If you need a selectable annotation consider using a label instead. +The badge component displays content classification. Badges are used to represent items like number of filtered items, number of unread items, or to represent state. If you need a selectable annotation consider using a label instead. ## Getting Started diff --git a/packages/terra-core-docs/src/terra-dev-site/doc/badge/example/Badge.module.scss b/packages/terra-core-docs/src/terra-dev-site/doc/badge/example/Badge.module.scss index 1188aeaf589..a4f0ea347b8 100644 --- a/packages/terra-core-docs/src/terra-dev-site/doc/badge/example/Badge.module.scss +++ b/packages/terra-core-docs/src/terra-dev-site/doc/badge/example/Badge.module.scss @@ -13,4 +13,25 @@ max-width: 100%; overflow-x: auto; } -} + + .profile-name { + font-weight: bold; + } + + .profile-container { + border: 1px solid #c8cacb; + border-radius: 10px; + display: flex; + flex-wrap: wrap; + padding: 5px; + } + + .profile-name-container { + padding-left: 10px; + padding-top: 2px; + } + + .profile-badge { + margin: 5px; + } +} \ No newline at end of file diff --git a/packages/terra-core-docs/src/terra-dev-site/doc/badge/example/BadgeIntent.jsx b/packages/terra-core-docs/src/terra-dev-site/doc/badge/example/BadgeIntent.jsx index dffaeb5b12e..65d0d520a10 100644 --- a/packages/terra-core-docs/src/terra-dev-site/doc/badge/example/BadgeIntent.jsx +++ b/packages/terra-core-docs/src/terra-dev-site/doc/badge/example/BadgeIntent.jsx @@ -1,5 +1,6 @@ import React from 'react'; import Badge from 'terra-badge'; +import Avatar from 'terra-avatar'; import classNames from 'classnames/bind'; import styles from './Badge.module.scss'; @@ -30,41 +31,29 @@ const BadgeIntent = () => (

Secondary Intent can be used to label user name as NEW

-
-
- Segun Adebayo - +
+ +
+ Segun Adebayo +
+ UI Engineer +
+
+

- Primary Intent with unread items + Badges with read and unread items

-
- -
-
- -
-
- -
-
-

- Default Intent with read items -

-
- -
-
- +
From ec3e8e3996b4fa48230f540d92ad5c16724e95cb Mon Sep 17 00:00:00 2001 From: MadanKumarGovindaswamy Date: Tue, 31 Oct 2023 14:51:05 +0530 Subject: [PATCH 04/12] Update lint error --- .../src/terra-dev-site/doc/badge/example/Badge.module.scss | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/terra-core-docs/src/terra-dev-site/doc/badge/example/Badge.module.scss b/packages/terra-core-docs/src/terra-dev-site/doc/badge/example/Badge.module.scss index a4f0ea347b8..2cfa31110dd 100644 --- a/packages/terra-core-docs/src/terra-dev-site/doc/badge/example/Badge.module.scss +++ b/packages/terra-core-docs/src/terra-dev-site/doc/badge/example/Badge.module.scss @@ -34,4 +34,4 @@ .profile-badge { margin: 5px; } -} \ No newline at end of file +} From a50bc406c4a5a66c5114a115b37a9e51428d8d89 Mon Sep 17 00:00:00 2001 From: MadanKumarGovindaswamy Date: Fri, 3 Nov 2023 14:52:46 +0530 Subject: [PATCH 05/12] Update: Doc page --- packages/terra-badge/src/Badge.jsx | 12 ++++- .../terra-dev-site/doc/badge/About.1.doc.mdx | 47 +++++++++++++++---- .../doc/badge/example/Badge.module.scss | 5 ++ .../doc/badge/example/BadgeInTable.jsx | 14 ++---- .../doc/badge/example/BadgeIntent.jsx | 26 ++-------- .../badge/example/BadgeVisuallyHiddenText.jsx | 37 ++++++++++----- 6 files changed, 86 insertions(+), 55 deletions(-) diff --git a/packages/terra-badge/src/Badge.jsx b/packages/terra-badge/src/Badge.jsx index 00177f3fec0..8f64188ab1f 100644 --- a/packages/terra-badge/src/Badge.jsx +++ b/packages/terra-badge/src/Badge.jsx @@ -38,6 +38,9 @@ const propTypes = { icon: PropTypes.element, /** * Sets the badge color scheme. One of `default`, `primary`, `secondary`, `positive`, `negative`, `warning`, `info`. + * + * ![IMPORTANT](https://badgen.net/badge/UX/Accessibility/blue) + * Follow the accessibility guidance for color to ensure color is not the only method used to convey information. */ intent: PropTypes.oneOf(['default', 'primary', 'secondary', 'info', 'warning', 'positive', 'negative']), /** @@ -55,11 +58,16 @@ const propTypes = { size: PropTypes.oneOf(['tiny', 'small', 'medium', 'large', 'huge']), /** * Sets the badge text. + * + * ![IMPORTANT](https://badgen.net/badge/UX/Accessibility/blue) + * It is best practice to always use text. Use text that conveys the meaning or purpose of the badge. */ text: PropTypes.string, /** - * Text that describes the badge to a screen reader. Use this - * for creating an accessible badge. + * Additional text that can be visually hidden but supports people that use assistive technologies like screen readers. + * + * ![IMPORTANT](https://badgen.net/badge/UX/Accessibility/blue) + * Follow the Accessibility Guidance for visually hidden text above to better understand when to use this prop. */ visuallyHiddenText: PropTypes.string, }; diff --git a/packages/terra-core-docs/src/terra-dev-site/doc/badge/About.1.doc.mdx b/packages/terra-core-docs/src/terra-dev-site/doc/badge/About.1.doc.mdx index 8b7b0e4a564..d6f4469ad57 100644 --- a/packages/terra-core-docs/src/terra-dev-site/doc/badge/About.1.doc.mdx +++ b/packages/terra-core-docs/src/terra-dev-site/doc/badge/About.1.doc.mdx @@ -1,5 +1,6 @@ import { Badge } from 'terra-badge/package.json?dev-site-package'; +import { Notice } from "@cerner/terra-docs"; import BadgeIntent from './example/BadgeIntent?dev-site-example'; import BadgeSize from './example/BadgeSize?dev-site-example'; import BadgeIcon from './example/BadgeIcon?dev-site-example'; @@ -12,7 +13,7 @@ import BadgePropsTable from 'terra-badge/lib/Badge?dev-site-props-table'; # Terra Badge -The badge component displays content classification. Badges are used to represent items like number of filtered items, number of unread items, or to represent state. If you need a selectable annotation consider using a label instead. +The badge component displays content classification. Badges are used to represent counts (e.g., number of unread items) or to represent a status. If you need a selectable annotation consider using [`Terra Popup`](https://engineering.cerner.com/terra-ui/components/cerner-terra-framework-docs/popup/popup) or another control instead. ## Getting Started @@ -43,21 +44,49 @@ The Badge component must be composed inside the [Base][1] component with a local import Badge from 'terra-badge'; ``` + + +##### Accessibility Guidance: Badge Color To implement an accessible terra badge: -- Ensure a meaningful text is provided as `text` prop for terra-badge and choose appropriate intent that matches the defination of Badge text. +- Ensure the words used within the badge (the text provided as text prop) or the icon conveys the purpose of the badge. Badge color must always be used as a secondary or supportive method to understand meaning. + - Color must never be the only method used to convey badge meaning. + - A good example where words convey the meaning and color is supportive: + - Heart Rate: `High` + - Blood Pressure: `Critical` + - A bad example where color alone is used to convey meaning: + - `Heart Rate` + - `Blood Pressure` +- When using the intent prop to set badge colors, choose the appropriate intent prop type value that matches the purpose and intent of the badge(s). And, be consistent in the use of color per the meaning of the words. + - Do not use one color with different meanings. For example, do not have 2 or more badges using the same color each with a different meaning. + +##### Accessibility Guidance: Visually Hidden Text +Because Badges should always use text that provides the proper context and meaning of the badge, badges should generally make sense on their own. Additionally, Badges are usually placed next to or in very close proximity to the text they are referring to. However, there may be times we want to provide a little extra context for people that use Assistive Technologies (AT), like screen readers. + +Use visually-hidden-text when: + +- The visible relationship of the Badge is not also semantically connected or represented in code. + - For example, a Badge placed visibly next to one word within a string of words but the one word and Badge pairing is not coded as a semantic group and would not easily be associated together. +- The visible presentation provides visible context but we want to ensure more meaningful text for a screen reader user + - For example, a mailbox icon with a Badge count of 20 can easily be interpreted by sighted users a 20 unread messages. It would best to provide more context for AT users. In this instance we could have the Badge include the count and visually hidden text “unread messages” so a screen reader would read “20 unread messages” instead of just “20.” + +Other helpful hints in using visually-hidden-text: + +- Avoid using visually-hidden-text in a way that creates redundancy of words. For example, a badge titled “High” with visually hidden text “High Risk Factor” – in this example the word High would be read twice. It is unnecessary and the redundancy could cause confusion. +- Keep visually-hidden-text to a minimum in length. It should be short, simple, and to the point. +- Do not use visually-hidden-text when the text is sufficient to convey information of badge. + +**Remember the point of accessibility is to provide an equitable experience to all.** We do not want to give any user more information than another regardless of abilities. That said, we want to be cognizant that we don’t provide more information to the screen reader user that the sighted user may not have access to. -- Ensure Information is not conveyed by only color added by different intent of terra-badge. +##### Accessibility Guidance: Icons -- Ensure that the terra-badge is provided with visually hidden text to convey the purpose of the badge to users via screen reader or similar assistive technologies when required. +For icons to be effective within user interfaces, the icon used must make sense, be consistent and predictable, have an accessible name, and users must understand their purpose. If not implemented correctly, icons may prevent some of your users from understanding the UI. Refer to the [Terra Icon Accessibility Guide](https://engineering.cerner.com/terra-ui/components/cerner-terra-core-docs/icon/accessibility-guide) for proper guidance when using icons. -- When multiple badges are used together, Consider following steps which will help users to perceive or understand the difference between the two badges. + - - Add an icon to visually convey information. - - Add a visually-hidden-text to convey information for screen reader users. - - Avoid having badges with similar intent on group. +- When using Badges inside a larger group (e.g., inside a table or list of items), do not mix and match Badge sizes. Use one only one size of Badge per grouping of content. -- visually-hidden-text should be ignored when the badge color and text is sufficient to convey information of badge. +- Use only one Badge per item. Multiple Badges should not be used to pair with a singular item, instead use a [`Pill`](https://engineering.cerner.com/terra-ui/components/cerner-terra-framework-docs/pills/filter-pills) or [`Tag`](https://engineering.cerner.com/terra-ui/components/cerner-terra-core-docs/tag/about) but be sure to use the component that matches the intent of use case. Pills and Tags, while similar, are not the same thing. ## Component Features * [Cross-Browser Support](https://engineering.cerner.com/terra-ui/about/terra-ui/component-standards#cross-browser-support) diff --git a/packages/terra-core-docs/src/terra-dev-site/doc/badge/example/Badge.module.scss b/packages/terra-core-docs/src/terra-dev-site/doc/badge/example/Badge.module.scss index 2cfa31110dd..23de3c66ac5 100644 --- a/packages/terra-core-docs/src/terra-dev-site/doc/badge/example/Badge.module.scss +++ b/packages/terra-core-docs/src/terra-dev-site/doc/badge/example/Badge.module.scss @@ -34,4 +34,9 @@ .profile-badge { margin: 5px; } + + .message-count { + position: relative; + left: 5px + } } diff --git a/packages/terra-core-docs/src/terra-dev-site/doc/badge/example/BadgeInTable.jsx b/packages/terra-core-docs/src/terra-dev-site/doc/badge/example/BadgeInTable.jsx index 267bd175d07..a844ccc143c 100644 --- a/packages/terra-core-docs/src/terra-dev-site/doc/badge/example/BadgeInTable.jsx +++ b/packages/terra-core-docs/src/terra-dev-site/doc/badge/example/BadgeInTable.jsx @@ -1,6 +1,5 @@ import React from 'react'; import Badge from 'terra-badge'; -import IconHelpInverse from 'terra-icon/lib/icon/IconHelpInverse'; import Table, { Header, HeaderCell, @@ -13,7 +12,6 @@ import classNames from 'classnames/bind'; import styles from './Badge.module.scss'; const cx = classNames.bind(styles); -const Icon = ; const BadgeInTable = () => (
@@ -31,7 +29,7 @@ const BadgeInTable = () => (
- +
@@ -42,10 +40,7 @@ const BadgeInTable = () => (
- -
-
- +
@@ -56,10 +51,7 @@ const BadgeInTable = () => (
- -
-
- +
diff --git a/packages/terra-core-docs/src/terra-dev-site/doc/badge/example/BadgeIntent.jsx b/packages/terra-core-docs/src/terra-dev-site/doc/badge/example/BadgeIntent.jsx index 65d0d520a10..a7bc112914e 100644 --- a/packages/terra-core-docs/src/terra-dev-site/doc/badge/example/BadgeIntent.jsx +++ b/packages/terra-core-docs/src/terra-dev-site/doc/badge/example/BadgeIntent.jsx @@ -9,7 +9,10 @@ const cx = classNames.bind(styles); const BadgeIntent = () => (

- Intent with severity of issues. + The Intent prop can be used to apply colors to badges. Please refer to the important Accessibility Guidance sections above to ensure proper usage. +

+

+ An example usage of the “Intent” Badge:

@@ -28,9 +31,7 @@ const BadgeIntent = () => (
-

- Secondary Intent can be used to label user name as NEW -

+
@@ -42,23 +43,6 @@ const BadgeIntent = () => (
-

- Badges with read and unread items -

-
-
- -
-
- -
-
- -
-
- -
-
); diff --git a/packages/terra-core-docs/src/terra-dev-site/doc/badge/example/BadgeVisuallyHiddenText.jsx b/packages/terra-core-docs/src/terra-dev-site/doc/badge/example/BadgeVisuallyHiddenText.jsx index dcf2e01b4a5..9503780aef6 100644 --- a/packages/terra-core-docs/src/terra-dev-site/doc/badge/example/BadgeVisuallyHiddenText.jsx +++ b/packages/terra-core-docs/src/terra-dev-site/doc/badge/example/BadgeVisuallyHiddenText.jsx @@ -6,20 +6,33 @@ import styles from './Badge.module.scss'; const cx = classNames.bind(styles); const BadgeVisuallyHiddenText = () => ( -
-
- + +
+
+ +
+
+ +
+
+ +
+
+ +
-
- +

+ An example usage of Badge for the count of unread items using the Visually Hidden Text and Size props: +

+
+
-
- -
-
- -
-
+ ); export default BadgeVisuallyHiddenText; From fc7d101607daadbb349fa69b60c057f33d32c5dd Mon Sep 17 00:00:00 2001 From: MadanKumarGovindaswamy Date: Fri, 3 Nov 2023 15:00:15 +0530 Subject: [PATCH 06/12] update: changelog file and lint error --- packages/terra-badge/CHANGELOG.md | 3 +++ .../src/terra-dev-site/doc/badge/example/Badge.module.scss | 2 +- 2 files changed, 4 insertions(+), 1 deletion(-) diff --git a/packages/terra-badge/CHANGELOG.md b/packages/terra-badge/CHANGELOG.md index 7f99c277b82..a1db5643f85 100644 --- a/packages/terra-badge/CHANGELOG.md +++ b/packages/terra-badge/CHANGELOG.md @@ -2,6 +2,9 @@ ## Unreleased +* Changed + * Update props description in props table. + ## 3.58.0 - (October 16, 2023) * Added diff --git a/packages/terra-core-docs/src/terra-dev-site/doc/badge/example/Badge.module.scss b/packages/terra-core-docs/src/terra-dev-site/doc/badge/example/Badge.module.scss index 23de3c66ac5..b82f72ee4c3 100644 --- a/packages/terra-core-docs/src/terra-dev-site/doc/badge/example/Badge.module.scss +++ b/packages/terra-core-docs/src/terra-dev-site/doc/badge/example/Badge.module.scss @@ -36,7 +36,7 @@ } .message-count { + left: 5px; position: relative; - left: 5px } } From 59a80d161f140306bc8b56e85df604af67f56665 Mon Sep 17 00:00:00 2001 From: MadanKumarGovindaswamy Date: Fri, 3 Nov 2023 15:42:44 +0530 Subject: [PATCH 07/12] Update: add badge in doc --- .../src/terra-dev-site/doc/badge/About.1.doc.mdx | 9 +++++---- .../doc/badge/example/BadgeInDoc.jsx | 14 ++++++++++++++ 2 files changed, 19 insertions(+), 4 deletions(-) create mode 100644 packages/terra-core-docs/src/terra-dev-site/doc/badge/example/BadgeInDoc.jsx diff --git a/packages/terra-core-docs/src/terra-dev-site/doc/badge/About.1.doc.mdx b/packages/terra-core-docs/src/terra-dev-site/doc/badge/About.1.doc.mdx index d6f4469ad57..6a3c4402835 100644 --- a/packages/terra-core-docs/src/terra-dev-site/doc/badge/About.1.doc.mdx +++ b/packages/terra-core-docs/src/terra-dev-site/doc/badge/About.1.doc.mdx @@ -9,6 +9,7 @@ import BadgeInTable from './example/BadgeInTable?dev-site-example'; import BadgePropsTable from 'terra-badge/lib/Badge?dev-site-props-table'; +import BadgeInDoc from './example/BadgeInDoc'; # Terra Badge @@ -52,11 +53,11 @@ To implement an accessible terra badge: - Ensure the words used within the badge (the text provided as text prop) or the icon conveys the purpose of the badge. Badge color must always be used as a secondary or supportive method to understand meaning. - Color must never be the only method used to convey badge meaning. - A good example where words convey the meaning and color is supportive: - - Heart Rate: `High` - - Blood Pressure: `Critical` + - Heart Rate: + - Blood Pressure: - A bad example where color alone is used to convey meaning: - - `Heart Rate` - - `Blood Pressure` + - + - - When using the intent prop to set badge colors, choose the appropriate intent prop type value that matches the purpose and intent of the badge(s). And, be consistent in the use of color per the meaning of the words. - Do not use one color with different meanings. For example, do not have 2 or more badges using the same color each with a different meaning. diff --git a/packages/terra-core-docs/src/terra-dev-site/doc/badge/example/BadgeInDoc.jsx b/packages/terra-core-docs/src/terra-dev-site/doc/badge/example/BadgeInDoc.jsx new file mode 100644 index 00000000000..83e84a33fdf --- /dev/null +++ b/packages/terra-core-docs/src/terra-dev-site/doc/badge/example/BadgeInDoc.jsx @@ -0,0 +1,14 @@ +import React from 'react'; +import PropTypes from 'prop-types'; +import Badge from 'terra-badge'; + +const propTypes = { text: PropTypes.string, intent: PropTypes.string }; + +const BadgeInDoc = ({ + ...props +}) => ( + +); + +BadgeInDoc.propTypes = propTypes; +export default BadgeInDoc; From 7c9372957e3b85bc6360392a2479144782dad6a0 Mon Sep 17 00:00:00 2001 From: MadanKumarGovindaswamy Date: Mon, 6 Nov 2023 18:16:26 +0530 Subject: [PATCH 08/12] Update: Implementation page --- packages/terra-badge/src/Badge.jsx | 4 +-- .../jest/__snapshots__/Badge.test.jsx.snap | 9 ------ .../terra-dev-site/doc/badge/About.1.doc.mdx | 25 ++++++++++------ .../doc/badge/example/Badge.module.scss | 5 ---- .../doc/badge/example/BadgeIcon.jsx | 30 ++++++++++++------- .../doc/badge/example/BadgeInDoc.jsx | 4 +-- .../doc/badge/example/BadgeIntent.jsx | 11 +++++-- .../badge/example/BadgeVisuallyHiddenText.jsx | 23 +++++--------- 8 files changed, 55 insertions(+), 56 deletions(-) diff --git a/packages/terra-badge/src/Badge.jsx b/packages/terra-badge/src/Badge.jsx index 8f64188ab1f..589370e0f00 100644 --- a/packages/terra-badge/src/Badge.jsx +++ b/packages/terra-badge/src/Badge.jsx @@ -106,9 +106,9 @@ const Badge = ({ ); const textContent = text ? {text} : null; - const intentText = intent !== BadgeIntent.DEFAULT ? : null; + // const intentText = intent !== BadgeIntent.DEFAULT ? : null; const visuallyHiddenTextContent = visuallyHiddenText ? : null; - const content = isReversed ? [intentText, textContent, visuallyHiddenTextContent, icon, customProps.children] : [icon, intentText, textContent, visuallyHiddenTextContent, customProps.children]; + const content = isReversed ? [textContent, visuallyHiddenTextContent, icon, customProps.children] : [icon, textContent, visuallyHiddenTextContent, customProps.children]; return React.createElement('span', { ...customProps, className: badgeClassNames }, ...content); }; diff --git a/packages/terra-badge/tests/jest/__snapshots__/Badge.test.jsx.snap b/packages/terra-badge/tests/jest/__snapshots__/Badge.test.jsx.snap index 711dfedc743..0bfb97435b2 100644 --- a/packages/terra-badge/tests/jest/__snapshots__/Badge.test.jsx.snap +++ b/packages/terra-badge/tests/jest/__snapshots__/Badge.test.jsx.snap @@ -97,9 +97,6 @@ exports[`should render a badge component in the order, text and icon with info i - @@ -128,9 +125,6 @@ exports[`should render a badge component with icon and warning intent 1`] = ` Test icon - `; @@ -150,9 +144,6 @@ exports[`should render a badge component with text and secondary intent 1`] = ` - diff --git a/packages/terra-core-docs/src/terra-dev-site/doc/badge/About.1.doc.mdx b/packages/terra-core-docs/src/terra-dev-site/doc/badge/About.1.doc.mdx index 6a3c4402835..409d934ebee 100644 --- a/packages/terra-core-docs/src/terra-dev-site/doc/badge/About.1.doc.mdx +++ b/packages/terra-core-docs/src/terra-dev-site/doc/badge/About.1.doc.mdx @@ -47,39 +47,46 @@ import Badge from 'terra-badge'; -##### Accessibility Guidance: Badge Color +### Accessibility Guidance: Badge Color To implement an accessible terra badge: - Ensure the words used within the badge (the text provided as text prop) or the icon conveys the purpose of the badge. Badge color must always be used as a secondary or supportive method to understand meaning. - Color must never be the only method used to convey badge meaning. - A good example where words convey the meaning and color is supportive: - - Heart Rate: - - Blood Pressure: + - Heart Rate: + - Blood Pressure: - A bad example where color alone is used to convey meaning: - - - When using the intent prop to set badge colors, choose the appropriate intent prop type value that matches the purpose and intent of the badge(s). And, be consistent in the use of color per the meaning of the words. - Do not use one color with different meanings. For example, do not have 2 or more badges using the same color each with a different meaning. -##### Accessibility Guidance: Visually Hidden Text +### Accessibility Guidance: Visually Hidden Text Because Badges should always use text that provides the proper context and meaning of the badge, badges should generally make sense on their own. Additionally, Badges are usually placed next to or in very close proximity to the text they are referring to. However, there may be times we want to provide a little extra context for people that use Assistive Technologies (AT), like screen readers. Use visually-hidden-text when: -- The visible relationship of the Badge is not also semantically connected or represented in code. - - For example, a Badge placed visibly next to one word within a string of words but the one word and Badge pairing is not coded as a semantic group and would not easily be associated together. -- The visible presentation provides visible context but we want to ensure more meaningful text for a screen reader user +- **Ensure Programmatic Context**: The visible relationship of the Badge is not also semantically connected or represented in code. + - For example, a Badge placed visibly next to one word within a string of words but the one word and Badge pairing is not coded as a semantic group and would not easily be associated together. See the good example underneath the Accessibility Guidance: Badge Color section above. +- **Add Additional Context**: The visible presentation provides visible context but we want to ensure more meaningful text for a screen reader user. - For example, a mailbox icon with a Badge count of 20 can easily be interpreted by sighted users a 20 unread messages. It would best to provide more context for AT users. In this instance we could have the Badge include the count and visually hidden text “unread messages” so a screen reader would read “20 unread messages” instead of just “20.” +```jsx +import Badge from 'terra-badge'; + + + +``` + Other helpful hints in using visually-hidden-text: - Avoid using visually-hidden-text in a way that creates redundancy of words. For example, a badge titled “High” with visually hidden text “High Risk Factor” – in this example the word High would be read twice. It is unnecessary and the redundancy could cause confusion. - Keep visually-hidden-text to a minimum in length. It should be short, simple, and to the point. - Do not use visually-hidden-text when the text is sufficient to convey information of badge. -**Remember the point of accessibility is to provide an equitable experience to all.** We do not want to give any user more information than another regardless of abilities. That said, we want to be cognizant that we don’t provide more information to the screen reader user that the sighted user may not have access to. +**Remember the point of accessibility is to provide an equitable experience to all.** We do not want to give any user more information than another regardless of abilities. -##### Accessibility Guidance: Icons +### Accessibility Guidance: Icons For icons to be effective within user interfaces, the icon used must make sense, be consistent and predictable, have an accessible name, and users must understand their purpose. If not implemented correctly, icons may prevent some of your users from understanding the UI. Refer to the [Terra Icon Accessibility Guide](https://engineering.cerner.com/terra-ui/components/cerner-terra-core-docs/icon/accessibility-guide) for proper guidance when using icons. diff --git a/packages/terra-core-docs/src/terra-dev-site/doc/badge/example/Badge.module.scss b/packages/terra-core-docs/src/terra-dev-site/doc/badge/example/Badge.module.scss index b82f72ee4c3..2cfa31110dd 100644 --- a/packages/terra-core-docs/src/terra-dev-site/doc/badge/example/Badge.module.scss +++ b/packages/terra-core-docs/src/terra-dev-site/doc/badge/example/Badge.module.scss @@ -34,9 +34,4 @@ .profile-badge { margin: 5px; } - - .message-count { - left: 5px; - position: relative; - } } diff --git a/packages/terra-core-docs/src/terra-dev-site/doc/badge/example/BadgeIcon.jsx b/packages/terra-core-docs/src/terra-dev-site/doc/badge/example/BadgeIcon.jsx index d2ffff51637..556b78b551d 100644 --- a/packages/terra-core-docs/src/terra-dev-site/doc/badge/example/BadgeIcon.jsx +++ b/packages/terra-core-docs/src/terra-dev-site/doc/badge/example/BadgeIcon.jsx @@ -1,24 +1,32 @@ import React from 'react'; -import { IconBookmark } from 'terra-icon'; +import { IconBookmark, IconFeaturedOutlineYellow } from 'terra-icon'; import Badge from 'terra-badge'; import classNames from 'classnames/bind'; import styles from './Badge.module.scss'; const cx = classNames.bind(styles); const Icon = ; +const Bookmark = ; const BadgeIcon = () => ( -
-
- + +

+ Icon Usage Inside Badges: The following Badge example only illustrates icons inside of Badges. When Icons are used inside of Badges, be sure to follow the guidance prescribed in the + Icon Accessibility Guide + to ensure proper use of icons. Icons within icon-only Badges must be meaningful and have a meaningful label applied via the a11yLabel prop. +

+
+
+ +
+
+ +
+
+ +
-
- -
-
- -
-
+ ); export default BadgeIcon; diff --git a/packages/terra-core-docs/src/terra-dev-site/doc/badge/example/BadgeInDoc.jsx b/packages/terra-core-docs/src/terra-dev-site/doc/badge/example/BadgeInDoc.jsx index 83e84a33fdf..bc17cc73ed3 100644 --- a/packages/terra-core-docs/src/terra-dev-site/doc/badge/example/BadgeInDoc.jsx +++ b/packages/terra-core-docs/src/terra-dev-site/doc/badge/example/BadgeInDoc.jsx @@ -2,12 +2,12 @@ import React from 'react'; import PropTypes from 'prop-types'; import Badge from 'terra-badge'; -const propTypes = { text: PropTypes.string, intent: PropTypes.string }; +const propTypes = { text: PropTypes.string, intent: PropTypes.string, visuallyHiddenText: PropTypes.string }; const BadgeInDoc = ({ ...props }) => ( - + ); BadgeInDoc.propTypes = propTypes; diff --git a/packages/terra-core-docs/src/terra-dev-site/doc/badge/example/BadgeIntent.jsx b/packages/terra-core-docs/src/terra-dev-site/doc/badge/example/BadgeIntent.jsx index a7bc112914e..797992ec203 100644 --- a/packages/terra-core-docs/src/terra-dev-site/doc/badge/example/BadgeIntent.jsx +++ b/packages/terra-core-docs/src/terra-dev-site/doc/badge/example/BadgeIntent.jsx @@ -9,10 +9,13 @@ const cx = classNames.bind(styles); const BadgeIntent = () => (

- The Intent prop can be used to apply colors to badges. Please refer to the important Accessibility Guidance sections above to ensure proper usage. + The Intent prop can be used to apply colors to badges. Please refer to the + VisuallyHiddenText prop examples further below + to ensure proper + context is provided for assistive technology users to understand the purpose of the badge.

- An example usage of the “Intent” Badge: + Intent Badge Colors: The following Badge example only illustrates badge colors. This example is not intended to illustrate how Badges should be used. As noted above, multiple badges should not be used together. Instead, see Pills or Tag.

@@ -31,7 +34,9 @@ const BadgeIntent = () => (
-
+

+ Example usage of the Intent Badge. Please note that this use case does not require the VisuallyHiddenText prop because the badge is visually and programmatically grouped in a semantic container. Other use cases will require the VisuallyHiddenText prop. To effectively communicate context to assistive technology users. +

diff --git a/packages/terra-core-docs/src/terra-dev-site/doc/badge/example/BadgeVisuallyHiddenText.jsx b/packages/terra-core-docs/src/terra-dev-site/doc/badge/example/BadgeVisuallyHiddenText.jsx index 9503780aef6..41c4cb1d4ef 100644 --- a/packages/terra-core-docs/src/terra-dev-site/doc/badge/example/BadgeVisuallyHiddenText.jsx +++ b/packages/terra-core-docs/src/terra-dev-site/doc/badge/example/BadgeVisuallyHiddenText.jsx @@ -1,5 +1,6 @@ import React from 'react'; import Badge from 'terra-badge'; +import Button from 'terra-button'; import classNames from 'classnames/bind'; import styles from './Badge.module.scss'; @@ -7,30 +8,22 @@ const cx = classNames.bind(styles); const BadgeVisuallyHiddenText = () => ( +

+ Ensuring Programmatic Context Badge Example: When a Badge is paired with a word or item but not semantically understood as grouped with that word, add use the word or words as the visually hidden text string as illustrated in the following example. +

- -
-
- -
-
- +
- +

- An example usage of Badge for the count of unread items using the Visually Hidden Text and Size props: + Add Additional Context to a Badge Example: Use the VisuallyHiddenText prop to provide additional context that sighted users can see but may make the content more meaningful and better understood by screen reader users.

- +
); From 54298b23877cb5b145dfa0d394bed9db977d65b8 Mon Sep 17 00:00:00 2001 From: MadanKumarGovindaswamy Date: Mon, 6 Nov 2023 18:49:53 +0530 Subject: [PATCH 09/12] Update About.1.doc.mdx --- .../src/terra-dev-site/doc/badge/About.1.doc.mdx | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/packages/terra-core-docs/src/terra-dev-site/doc/badge/About.1.doc.mdx b/packages/terra-core-docs/src/terra-dev-site/doc/badge/About.1.doc.mdx index 409d934ebee..502842ac676 100644 --- a/packages/terra-core-docs/src/terra-dev-site/doc/badge/About.1.doc.mdx +++ b/packages/terra-core-docs/src/terra-dev-site/doc/badge/About.1.doc.mdx @@ -68,8 +68,6 @@ Use visually-hidden-text when: - **Ensure Programmatic Context**: The visible relationship of the Badge is not also semantically connected or represented in code. - For example, a Badge placed visibly next to one word within a string of words but the one word and Badge pairing is not coded as a semantic group and would not easily be associated together. See the good example underneath the Accessibility Guidance: Badge Color section above. -- **Add Additional Context**: The visible presentation provides visible context but we want to ensure more meaningful text for a screen reader user. - - For example, a mailbox icon with a Badge count of 20 can easily be interpreted by sighted users a 20 unread messages. It would best to provide more context for AT users. In this instance we could have the Badge include the count and visually hidden text “unread messages” so a screen reader would read “20 unread messages” instead of just “20.” ```jsx import Badge from 'terra-badge'; @@ -78,6 +76,9 @@ import Badge from 'terra-badge'; ``` +- **Add Additional Context**: The visible presentation provides visible context but we want to ensure more meaningful text for a screen reader user. + - For example, a mailbox icon with a Badge count of 20 can easily be interpreted by sighted users a 20 unread messages. It would best to provide more context for AT users. In this instance we could have the Badge include the count and visually hidden text “unread messages” so a screen reader would read “20 unread messages” instead of just “20.” + Other helpful hints in using visually-hidden-text: - Avoid using visually-hidden-text in a way that creates redundancy of words. For example, a badge titled “High” with visually hidden text “High Risk Factor” – in this example the word High would be read twice. It is unnecessary and the redundancy could cause confusion. From a0e816f93d308f690f757393f0422452e7b8413a Mon Sep 17 00:00:00 2001 From: MadanKumarGovindaswamy Date: Tue, 7 Nov 2023 13:01:30 +0530 Subject: [PATCH 10/12] Update: corrections --- .../terra-dev-site/doc/badge/About.1.doc.mdx | 6 ++- .../doc/badge/example/BadgeIcon.jsx | 5 +-- .../doc/badge/example/BadgeSize.jsx | 37 +++++++++++-------- .../badge/example/BadgeVisuallyHiddenText.jsx | 14 ++++++- 4 files changed, 39 insertions(+), 23 deletions(-) diff --git a/packages/terra-core-docs/src/terra-dev-site/doc/badge/About.1.doc.mdx b/packages/terra-core-docs/src/terra-dev-site/doc/badge/About.1.doc.mdx index 502842ac676..6446812600a 100644 --- a/packages/terra-core-docs/src/terra-dev-site/doc/badge/About.1.doc.mdx +++ b/packages/terra-core-docs/src/terra-dev-site/doc/badge/About.1.doc.mdx @@ -72,8 +72,10 @@ Use visually-hidden-text when: ```jsx import Badge from 'terra-badge'; - - +
+ Heart Rate:
+ Blood Pressure: +
``` - **Add Additional Context**: The visible presentation provides visible context but we want to ensure more meaningful text for a screen reader user. diff --git a/packages/terra-core-docs/src/terra-dev-site/doc/badge/example/BadgeIcon.jsx b/packages/terra-core-docs/src/terra-dev-site/doc/badge/example/BadgeIcon.jsx index 556b78b551d..945b2171295 100644 --- a/packages/terra-core-docs/src/terra-dev-site/doc/badge/example/BadgeIcon.jsx +++ b/packages/terra-core-docs/src/terra-dev-site/doc/badge/example/BadgeIcon.jsx @@ -1,12 +1,11 @@ import React from 'react'; -import { IconBookmark, IconFeaturedOutlineYellow } from 'terra-icon'; +import { IconBookmark } from 'terra-icon'; import Badge from 'terra-badge'; import classNames from 'classnames/bind'; import styles from './Badge.module.scss'; const cx = classNames.bind(styles); const Icon = ; -const Bookmark = ; const BadgeIcon = () => ( @@ -23,7 +22,7 @@ const BadgeIcon = () => (
- +
diff --git a/packages/terra-core-docs/src/terra-dev-site/doc/badge/example/BadgeSize.jsx b/packages/terra-core-docs/src/terra-dev-site/doc/badge/example/BadgeSize.jsx index 1dad6b0159a..62c0e5149fe 100644 --- a/packages/terra-core-docs/src/terra-dev-site/doc/badge/example/BadgeSize.jsx +++ b/packages/terra-core-docs/src/terra-dev-site/doc/badge/example/BadgeSize.jsx @@ -6,23 +6,28 @@ import styles from './Badge.module.scss'; const cx = classNames.bind(styles); const BadgeSize = () => ( -
-
- + +

+ The size prop can be used to change the size of Badges. The following is not an example of how to use Badges. It is only intended to illustrate the sizes that can be set. Never use size as a method to communicate meaning. +

+
+
+ +
+
+ +
+
+ +
+
+ +
+
+ +
-
- -
-
- -
-
- -
-
- -
-
+ ); export default BadgeSize; diff --git a/packages/terra-core-docs/src/terra-dev-site/doc/badge/example/BadgeVisuallyHiddenText.jsx b/packages/terra-core-docs/src/terra-dev-site/doc/badge/example/BadgeVisuallyHiddenText.jsx index 41c4cb1d4ef..bcf47a505c5 100644 --- a/packages/terra-core-docs/src/terra-dev-site/doc/badge/example/BadgeVisuallyHiddenText.jsx +++ b/packages/terra-core-docs/src/terra-dev-site/doc/badge/example/BadgeVisuallyHiddenText.jsx @@ -9,18 +9,28 @@ const cx = classNames.bind(styles); const BadgeVisuallyHiddenText = () => (

- Ensuring Programmatic Context Badge Example: When a Badge is paired with a word or item but not semantically understood as grouped with that word, add use the word or words as the visually hidden text string as illustrated in the following example. + Ensuring Programmatic Context Badge Example: + When a Badge is paired with a word or item but not semantically understood as grouped with that word, add use the word or words as the visually hidden text string as illustrated in the following example.

+ + Heart Rate +
+
+
+ + Blood Pressure +

- Add Additional Context to a Badge Example: Use the VisuallyHiddenText prop to provide additional context that sighted users can see but may make the content more meaningful and better understood by screen reader users. + Add Additional Context to a Badge Example: + Use the VisuallyHiddenText prop to provide additional context that sighted users can see but may make the content more meaningful and better understood by screen reader users.