From c2d99be2b0d2e362a0161527e69526213d311657 Mon Sep 17 00:00:00 2001 From: pst67662 Date: Tue, 18 Feb 2020 14:26:30 +0100 Subject: [PATCH 1/3] RSP-1263 Documentation for StatusLight --- .../statuslight/docs/StatusLight.mdx | 133 ++++++++++++++++++ .../statuslight/src/StatusLight.tsx | 5 + .../@react-types/statuslight/src/index.d.ts | 9 ++ 3 files changed, 147 insertions(+) create mode 100644 packages/@react-spectrum/statuslight/docs/StatusLight.mdx diff --git a/packages/@react-spectrum/statuslight/docs/StatusLight.mdx b/packages/@react-spectrum/statuslight/docs/StatusLight.mdx new file mode 100644 index 00000000000..790fd3d9cf9 --- /dev/null +++ b/packages/@react-spectrum/statuslight/docs/StatusLight.mdx @@ -0,0 +1,133 @@ +import {Layout} from '@react-spectrum/docs'; +export default Layout; + +import docs from 'docs:@react-spectrum/statuslight'; +import {HeaderInfo, PropTable} from '@react-spectrum/docs'; +import packageData from '../package.json'; + +```jsx import +import '@react-spectrum/docs/src/client'; +import {StatusLight} from '@react-spectrum/statuslight'; +import {Switch} from '@react-spectrum/switch'; +import {VisuallyHidden} from '@react-aria/visually-hidden'; +``` + +# StatusLight + +

{docs.exports.StatusLight.description}

+ + + +## Example + +```tsx example +Default +``` + +## Content + +A visible label can be provided by passing children. Spectrum dictates that it should always be used with a label, never alone. +To indicate status use [semantic](#semantic-colors) or [label](#label-colors) variant color. + +```tsx example +Semantic color +Label color +``` + +### Accessibility + +If no visible label is provided (e.g. an icon only button), +an alternative text label must be provided to identify the control for accessibility. This should be added using +the `aria-label` prop. + +The visual cue provided by the status light is insufficient to comply with [WCAG 2.1 Success Criterion 1.4.1 on the Use of Color](https://www.w3.org/TR/WCAG21/#use-of-color), +which requires that "color is not used as the only visual means of conveying information, indicating an action, +prompting a response, or distinguishing a visual element." +If StatusLight communicates a state, like "Approved" or "Failed", that state must be included as part of the label. + +#### Using role="status" + +In cases where the status changes at runtime, +it may be appropriate to add `role="status"` so that the status change will be announced politely by assistive technology. +When using `role="status"`, be sure to provide appropriate context for the status change in the label for the StatusLight. +A status change that announces "Approved" without meaningful context would not be helpful. +Also, use caution when adding `role="status"` in cases where multiple status lights can update at once. +For example, with a large list of files that change status when deployed, +a single announcement when all files have deployed would be preferable to the verbosity of each file status announcing individually. + +```tsx example +function Example() { + let [isApproved, setIsApproved] = React.useState(false); + + return ( +
+ + Pull Request + {isApproved ? "Approved" : "Needs Approval"} + + setIsApproved(!isApproved)}>Toggle Status +
+ ); +} +``` + +### Internationalization + +To internationalize a StatusLight, a localized string should be set as the child content of the StatusLight. +For languages that are read right to left (e.g. Hebrew and Arabic), the StatusLight is placed on the right side of the text. + +## Props + + + +## Visual Options + +### Variant + +#### Semantic colors +[View guidelines](https://spectrum.adobe.com/page/status-light/#Semantic-variants) + +When status lights have a semantic meaning, they should use semantic colors. +Use the appropriate color to indicate status as follows. + +```tsx example +Gray: Archived, Deleted, Paused, Draft, Not Started, Ended +Green: Approved, Complete, Success, New, Purchased, Licensed +Orange: Needs Approval, Pending, Scheduled, Syncing, Indexing, Processing +Red: Error, Alert, Rejected, Failed +Blue: Active, In Use, Live, Published +``` + +#### Label colors +[View guidelines](https://spectrum.adobe.com/page/status-light/#Non-semantic-variants) + +When status lights are used to color code categories and labels commonly found in data visualization, +they use label colors. The ideal usage for these is when there are 8 or fewer categories or labels being color coded. +Use them in the following order to ensure the greatest possible color differences for multiple forms of color blindness: + +```tsx example +Indigo +Celery +Magenta +Yellow +Fuchsia +Seafoam +Chartreuse +Purple +``` + +### Disabled +[View guidelines](https://spectrum.adobe.com/page/status-light/#Disabled) + +Use `isDisabled` prop to match the state of a containing element. +Note that the `isDisabled` prop alters the visual style of the StatusLight, +but does not convey any state information to assistive technology. + +```tsx example +Yellow +``` diff --git a/packages/@react-spectrum/statuslight/src/StatusLight.tsx b/packages/@react-spectrum/statuslight/src/StatusLight.tsx index 7405cd299c6..55023c7c5ee 100644 --- a/packages/@react-spectrum/statuslight/src/StatusLight.tsx +++ b/packages/@react-spectrum/statuslight/src/StatusLight.tsx @@ -38,5 +38,10 @@ function StatusLight(props: SpectrumStatusLightProps, ref: DOMRef Date: Wed, 19 Feb 2020 15:36:52 +0100 Subject: [PATCH 2/3] RSP-1263: cr update --- packages/@react-spectrum/statuslight/docs/StatusLight.mdx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/packages/@react-spectrum/statuslight/docs/StatusLight.mdx b/packages/@react-spectrum/statuslight/docs/StatusLight.mdx index 790fd3d9cf9..3e3438233cb 100644 --- a/packages/@react-spectrum/statuslight/docs/StatusLight.mdx +++ b/packages/@react-spectrum/statuslight/docs/StatusLight.mdx @@ -31,7 +31,7 @@ import {VisuallyHidden} from '@react-aria/visually-hidden'; ## Content -A visible label can be provided by passing children. Spectrum dictates that it should always be used with a label, never alone. +A visible label is always required and can be provided by passing children. To indicate status use [semantic](#semantic-colors) or [label](#label-colors) variant color. ```tsx example @@ -48,7 +48,7 @@ the `aria-label` prop. The visual cue provided by the status light is insufficient to comply with [WCAG 2.1 Success Criterion 1.4.1 on the Use of Color](https://www.w3.org/TR/WCAG21/#use-of-color), which requires that "color is not used as the only visual means of conveying information, indicating an action, prompting a response, or distinguishing a visual element." -If StatusLight communicates a state, like "Approved" or "Failed", that state must be included as part of the label. +If StatusLight communicates a state, such as "Approved" or "Failed", that state must be included as part of the label. #### Using role="status" @@ -124,7 +124,7 @@ Use them in the following order to ensure the greatest possible color difference ### Disabled [View guidelines](https://spectrum.adobe.com/page/status-light/#Disabled) -Use `isDisabled` prop to match the state of a containing element. +Use the `isDisabled` prop to match the state of a containing element. Note that the `isDisabled` prop alters the visual style of the StatusLight, but does not convey any state information to assistive technology. From 8aec139e474f5dfaa63f544c81aff1d1e0e1489e Mon Sep 17 00:00:00 2001 From: pst67662 Date: Thu, 20 Feb 2020 16:38:43 +0100 Subject: [PATCH 3/3] RSP-1263: cr update --- .../@react-spectrum/statuslight/docs/StatusLight.mdx | 10 ++++++++-- packages/@react-types/statuslight/src/index.d.ts | 7 ++----- 2 files changed, 10 insertions(+), 7 deletions(-) diff --git a/packages/@react-spectrum/statuslight/docs/StatusLight.mdx b/packages/@react-spectrum/statuslight/docs/StatusLight.mdx index 3e3438233cb..f663e532b07 100644 --- a/packages/@react-spectrum/statuslight/docs/StatusLight.mdx +++ b/packages/@react-spectrum/statuslight/docs/StatusLight.mdx @@ -6,10 +6,10 @@ import {HeaderInfo, PropTable} from '@react-spectrum/docs'; import packageData from '../package.json'; ```jsx import -import '@react-spectrum/docs/src/client'; import {StatusLight} from '@react-spectrum/statuslight'; import {Switch} from '@react-spectrum/switch'; import {VisuallyHidden} from '@react-aria/visually-hidden'; +import User from '@spectrum-icons/workflow/User'; ``` # StatusLight @@ -41,10 +41,16 @@ To indicate status use [semantic](#semantic-colors) or [label](#label-colors) va ### Accessibility -If no visible label is provided (e.g. an icon only button), +If textual child is not provided (e.g. an icon only), an alternative text label must be provided to identify the control for accessibility. This should be added using the `aria-label` prop. +```tsx example + + + +``` + The visual cue provided by the status light is insufficient to comply with [WCAG 2.1 Success Criterion 1.4.1 on the Use of Color](https://www.w3.org/TR/WCAG21/#use-of-color), which requires that "color is not used as the only visual means of conveying information, indicating an action, prompting a response, or distinguishing a visual element." diff --git a/packages/@react-types/statuslight/src/index.d.ts b/packages/@react-types/statuslight/src/index.d.ts index 7466d2cff16..8a659a73d01 100644 --- a/packages/@react-types/statuslight/src/index.d.ts +++ b/packages/@react-types/statuslight/src/index.d.ts @@ -2,16 +2,13 @@ import {DOMProps, StyleProps} from '@react-types/shared'; import {ReactNode} from 'react'; export interface SpectrumStatusLightProps extends DOMProps, StyleProps { - /** The content to display as the label */ + /** The content to display as the label. */ children: ReactNode, /** * The variant changes the color of the status light. * When status lights have a semantic meaning, they should use the variant for semantic colors. */ variant: 'positive' | 'negative' | 'notice' | 'info' | 'neutral' | 'celery' | 'chartreuse' | 'yellow' | 'magenta' | 'fuchsia' | 'purple' | 'indigo' | 'seafoam', - /** - * Whether the status light is disabled or not. - * Shows that an element exists, but is not available in that circumstance. - */ + /** Whether the status light is disabled. */ isDisabled?: boolean }